עיצוב הודעות

בדף הזה מוסבר איך אפליקציות ל-Google Chat יכולות לעצב טקסט כדי לשלוח הודעות שמכילות:

• טקסט עשיר שכולל היפר-קישורים או תיוג של משתמש אחד או כל המשתמשים במרחב משותף ב-Chat.
• טקסט שמופיע בממשק של כרטיס, כולל טקסט של פסקה או טקסט בממשק המשתמש שמוצג לצד סמל, כמו כפתור.

איך מעצבים הודעת טקסט

ב-Chat אתם יכולים להוסיף עיצוב בסיסי להודעות טקסט, כולל הדגשה, הטיה וקו חוצה. העיצוב של הודעות טקסט שונה מהעיצוב של הודעות כרטיס, כי הודעות טקסט מעוצבות באותו תחביר שבו משתמשי Chat משתמשים.

בהודעות שנשלחות או מאוחזרות באמצעות Chat API, אפשר להשתמש בתחביר Markdown רגיל (MARKUP_SYNTAX_MARKDOWN) או בתחביר תגי עיצוב של Chat‏ (MARKUP_SYNTAX_CHAT). אפשר להגדיר תחביר תגי עיצוב כברירת מחדל ברמת האפליקציה במסוף Google Cloud (ראו הגדרת Google Chat API):

• ‫Markdown: תחביר Markdown רגיל (MARKUP_SYNTAX_MARKDOWN), שמבוסס על המפרט של CommonMark עם תוספים נוספים. אפליקציות חדשות שנוצרות ב-Chat מוגדרות כברירת מחדל ל-Markdown.
• Chat: תחביר תגי העיצוב של Chat ‏ (MARKUP_SYNTAX_CHAT). אפליקציות Chat קיימות מוגדרות כברירת מחדל ל-Chat כדי לשמור על תאימות לדורות קודמים.

אפשר גם לציין את markup_syntax בבקשות ספציפיות ל-Chat API כדי לשנות את ברירת המחדל ברמת האפליקציה. אם לא מציינים את markup_syntax בבקשת API, העיצוב נקבע לפי האופן שבו קוראים ל-Chat API:

• אפליקציות Chat מוגדרות: משתמשות בתחביר של תגי עיצוב שנשמר בדף ההגדרות של Chat API.
• פרויקטים ב-Cloud שלא הוגדרו: אם הפרויקט ב-Cloud שולח קריאה ל-Chat API בלי הגדרה שמורה של אפליקציית Chat, הבקשות מוגדרות כברירת מחדל ל-MARKUP_SYNTAX_MARKDOWN.
• תגובות לפעולות לפיתוח האפליקציה (webhook) נכנסות: ברירת המחדל היא MARKUP_SYNTAX_CHAT. איך שולחים הודעות באמצעות תגובות לפעולה מאתר אחר (webhook) נכנסות

כדי לעצב הודעות טקסט, משתמשים בתחביר הבא:

לדוגמה, נניח שיש לכם את קובץ ה-JSON הבא:

    {
      "text": "Your pizza delivery *has arrived*!\nThank you for using _Cymbal Pizza!_"
    }

הודעת הטקסט המעוצבת הזו מוצגת כך במרחב משותף ב-Chat:

איך רואים את עיצוב הטקסט בהודעות

כשמשתמש שולח הודעה, גוף ההודעה בטקסט פשוט נמצא בשדה text. חלק מהעיצוב שמוחל על הודעת הטקסט באמצעות תחביר Markdown נמצא בשדה text. עיצוב נוסף נמצא בשדה formattedText לפלט בלבד, כולל:

• תחביר Markdown נוסף לטקסט
• אזכורים של משתמשים
• היפר-קישורים בהתאמה אישית
• סמלי אמוג'י בהתאמה אישית

לדוגמה, נניח שהמשתמש שולח את הטקסט הבא:

אם ההודעה עוצבה באמצעות התפריט עיצוב בממשק המשתמש של Chat, השדה text מכיל רק את הטקסט, והשדה formattedText מכיל את תגי העיצוב, הטקסט וההיפר-קישור. בדוגמה הבאה מוצגת טיוטה של הודעת SMS עם מילה שמכילה היפר-קישור, פריטים ברשימה ומילה אחת מודגשת:

ההודעה מתקבלת בפורמט הבא:

    {
      "text": "I can meet there at:\nNoon\n3 pm\n5 pm\nWhat time works for you?",
      "formattedText": "I can meet <http://example.com|there> at:\n* Noon\n* 3 pm\n* 5 pm\nWhat time works for *you*?",
    }

קישורים לפורמטים

אם תכללו בטקסט של ההודעה כתובת URL פשוטה, כמו http://www.example.com/, היא תהפוך אוטומטית להיפר-קישור ב-Google Chat.

כדי לספק טקסט חלופי לקישור, משתמשים בתחביר הבא:

• בהודעות API שמוגדרות עם Markdown, משתמשים בתחביר הקישור הרגיל של Markdown:

  תחביר לדוגמה	הטקסט שמוצג ב-Google Chat
  [Example website](https://example.com)	Example website

• בהודעות טקסט פשוט רגילות, משתמשים בתחביר של קו אנכי:

  תחביר לדוגמה	הטקסט שמוצג ב-Google Chat
  <https://example.com|Example website>	Example website

  הקו האנכי וטקסט הקישור הם אופציונליים, כך ש-<https://example.com> ו-https://example.com שקולים.

איך משתמשים באמוג'י בהתאמה אישית בהודעת SMS

אפליקציות צ'אט יכולות לשלוח הודעות SMS עם אמוג'י בהתאמה אישית כדי להפוך את ההודעות לאישיות יותר. אפשר ליצור אמוג'י בהתאמה אישית ולהשתמש בהם רק בארגונים ב-Google Workspace, ורק אם האדמין הפעיל את האפשרות הזו בארגון. מידע נוסף מופיע במאמרים הסבר על אמוג'י בהתאמה אישית ב-Google Chat וניהול ההרשאות לאמוג'י בהתאמה אישית.

כדי ליצור הודעות עם אמוג'י בהתאמה אישית, האפליקציה צריכה להשתמש באימות משתמש. אי אפשר להשתמש באמוג'י בהתאמה אישית בהודעות שנוצרו באמצעות webhook או בהודעות שנוצרו באמצעות אימות של אפליקציה.

כדי להוסיף אמוג'י בהתאמה אישית לטקסט של הודעה, מציינים את name או את emoji_name של המשאב customEmoji:

{
    "text": "Hello <customEmojis/CUSTOM_EMOJI_ID>."
}

כדי להשתמש בדוגמה הזו, צריך להחליף את CUSTOM_EMOJI_ID במזהה של האמוג'י בהתאמה אישית. המזהה הזה מופיע בשדה name או בשדה emoji_name של המשאב customEmoji.

אם האפליקציה שולחת הודעות באמצעות תחביר Markdown, אתם יכולים לציין אמוג'י בהתאמה אישית בפורמט של תג HTML באמצעות המזהה של האמוג'י בהתאמה אישית:

{
  "text": "Hello <chat-emoji data-custom-emoji=\"customEmojis/CUSTOM_EMOJI_ID\">."
}

או לציין את השם של האמוג'י בהתאמה אישית:

{
  "text": "Hello <chat-emoji data-emoji-name=\"CUSTOM_EMOJI_NAME\">."
}

כדי להשתמש בדוגמאות האלה, מחליפים את CUSTOM_EMOJI_ID במזהה של האמוג'י בהתאמה אישית, ואת CUSTOM_EMOJI_NAME בשם הקוד המקוצר של האמוג'י בהתאמה אישית.

איך מתייגים משתמשים בהודעות טקסט

אפליקציות צ'אט יכולות לשלוח הודעות טקסט עם תיוג @של משתמש אחד או של כל המשתמשים במרחב ב-Chat. אפליקציות הצ'אט יכולות גם לתייג משתמשים שלא הצטרפו למרחב או שהם חברים במרחב שנמצא במצב ייבוא.

בהודעות שקטות אי אפשר לתייג משתמשים. אם תכללו תיוג בהודעה שקטה, תוחזר שגיאה.

תיוג משתמשים ספציפיים ב-@

כדי לתייג משתמש ספציפי, מוסיפים <users/{user}> להודעת הטקסט, כאשר {user} הוא המזהה של המשתמש. לדוגמה, נניח שבהודעת הטקסט הבאה, 123456789012345678901 מייצג את המזהה של המשתמש Mahan S.:‎

{
    "text": "A customer has reported an issue. Assigning ticket #942 to <users/123456789012345678901>."
}

אם האפליקציה שלכם שולחת הודעות באמצעות תחביר Markdown, השתמשו בפורמט תג ה-HTML chat-user כדי לציין את מזהה המשתמש:

{
  "text": "Assigning ticket #942 to <chat-user data-user=\"users/123456789012345678901\">."
}

או לציין כתובת אימייל:

{
  "text": "Assigning ticket #942 to <chat-user data-email=\"mahan@example.com\">."
}

הודעת ה-SMS מוצגת כך:

אפשר לציין את הערך של users/{user} בדרכים הבאות:

• אם אפליקציית Google Chat מגיבה להודעה שנשלחה על ידי המשתמש, אתם יכולים להשתמש בשדה message.sender.name של אירוע האינטראקציה MESSAGE.

• אם האפליקציה ל-Google Chat יוצרת הודעת טקסט אסינכרונית, אתם יכולים לציין את הערך של users/{user} בדרכים הבאות:

  • משתמשים בשדה name של המשאב User ב-Google Chat, למשל users/123456789012345678901.
  • משתמשים בכתובת האימייל של המשתמש ככתובת אימייל חלופית לערך {user}. לדוגמה, אם כתובת האימייל היא mahan@example.com, אפשר לציין את המשתמש בתור users/mahan@example.com. כדי להשתמש בכתובת אימייל חלופית, אפליקציית Google Chat צריכה לאמת את הזהות כמשתמש.

• אם אתם משתמשים ב-People API, אתם יכולים להשתמש גם בשיטה people.get כדי לזהות את מזהה המשתמש.

תיוג כל המשתמשים ב-@

כדי ליצור הודעת טקסט שמתייגת את כל המשתתפים במרחב, מחליפים את {user} ב-all. בדוגמה הבאה ב-JSON, כל המשתמשים מתויגים בהודעה:

{
    "text": "Important message for <users/all>: Code freeze starts at midnight tonight!"
}

אם האפליקציה שולחת הודעות באמצעות תחביר Markdown, צריך לציין את התיוג באמצעות פורמט תג ה-HTML של chat-user:

{
  "text": "Important message for <chat-user data-user=\"users/all\">: Code freeze starts at midnight tonight!"
}

הוספת ציטוטים להודעת SMS

אפליקציות צ'אט יכולות לכלול ציטוטים בהודעות SMS כדי לספק למשתמשים מידע מפורט על המקור. יש שתי דרכים לספק מקורות:

• ציטוטים מוטבעים: הוספת כרטיסים אינטראקטיביים שמופיעים כשמשתמשים מציבים את הסמן מעל חלקים ספציפיים בטקסט של ההודעה.
• רשימת מקורות בכותרת התחתונה: רשימת מקורות שמוצגת בתחתית ההודעה כקישורים בכותרת התחתונה.

הציטוטים נתמכים רק כשהשדה markupSyntax של ההודעה מוגדר כ-MARKUP_SYNTAX_MARKDOWN. התכונה הזו נתמכת רק ביצירת הודעות אסינכרוניות באמצעות Chat API.

כדי להוסיף ציטוטים בגוף ההודעה:

1. מציינים את המקורות ברשימה citations של ההודעה elements, ומקצים id ייחודי לכל אובייקט Citation.
2. בטקסט של ההודעה, תוחמים את הטקסט שרוצים לצטט באמצעות תג ה-HTML‏ chat-citation בפורמט הבא: <chat-citation data-id="{id}">{text}</chat-citation>. חשוב לוודא שהערך של {id} תואם למזהה שהגדרתם ב-elements. המערכת מתעלמת מציטוטים ללא הפניה (ללא תג תואם).

{
  "text": "This is a <chat-citation data-id=\"cite_1\">cited</chat-citation> text.",
  "markupSyntax": "MARKUP_SYNTAX_MARKDOWN",
  "elements": {
    "citations": [
      {
        "id": "cite_1",
        "citedSources": [
          {
            "title": "Example Source",
            "uri": "https://example.com"
          }
        ]
      }
    ]
  }
}

כדי להוסיף רשימת מקורות בכותרת התחתונה של הודעה, צריך לציין את המקורות ברשימה citedSources של ההודעה elements. כל המקורות שמופיעים כאן מוצגים באופן אוטומטי מתחת להודעה כקישורים בכותרת התחתונה, ואין צורך בתגים בתוך השורה בטקסט של ההודעה.

{
  "text": "This is a message with a footer source.",
  "markupSyntax": "MARKUP_SYNTAX_MARKDOWN",
  "elements": {
    "citedSources": [
      {
        "title": "Example Source",
        "uri": "https://example.com"
      }
    ]
  }
}

עיצוב טקסט שמופיע בכרטיסים

בתוך כרטיסים, רוב שדות הטקסט תומכים בעיצוב טקסט בסיסי באמצעות קבוצת משנה קטנה של תגי HTML. העיצוב של הטקסט בהודעות עם כרטיסים שונה מהעיצוב של הטקסט בהודעות SMS, כי הודעות SMS מעוצבות באותו תחביר שבו משתמשי Chat משתמשים.

אתם יכולים להשתמש בכלי ליצירת כרטיסים כדי לעצב ולראות תצוגה מקדימה של ממשקי המשתמש וההודעות של אפליקציות ל-Chat:

עיצוב טקסט של פסקה

בטבלה הבאה מפורטים התגים הנתמכים והמטרה שלהם:

כדי להגדיר רשימות ובלוקים של קוד, משתמשים בתגים הבאים:

This is a code block.

Markdown

כשההגדרה תחביר Markdown מופעלת, אתם יכולים להשתמש בתחביר הבא:

הוספת סמלים לטקסט

כדי להציג סמלים לצד טקסט בכרטיס, אפשר להשתמש בווידג'טים DecoratedText ו-ButtonList.

בקטעים הבאים מוסבר איך להשתמש בסמלים מובנים, בסמלים של Google Material או בסמלים בהתאמה אישית בטקסט מעוצב או בלחצנים.

שימוש בסמלים מ-Chat

כדי להשתמש בסמלים המובנים שזמינים ב-Chat, צריך לציין אחד מהבאים:

בטבלה הבאה מפורטים הסמלים המובנים שאפשר להשתמש בהם בהודעות בכרטיסים:

דוגמה לכרטיס עם סמל אימייל:

שימוש בסמלים של Material Design

אתם יכולים להשתמש בסמלים של Material כדי לבחור מתוך יותר מ-2, 500 אפשרויות של סמלים ולהתאים אישית את העובי, המילוי והדירוג של הסמלים.

הנה דוגמה לכרטיס עם סמל של material של Google:

שימוש בסמלים בהתאמה אישית

כדי להוסיף סמל בהתאמה אישית, צריך לכלול את השדה iconUrl ולציין את כתובת ה-URL של הסמל.

הנה דוגמה לסמל מותאם אישית: