לקבל אינטראקציות של משתמשים ולהגיב להן

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

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

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

אפליקציות צ'אט יכולות ליצור ולהציג ממשקים בדרכים הבאות:

דרישות מוקדמות

איך פועלות האינטראקציות של המשתמשים

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

בתרשים הבא אפשר לראות איך אפליקציות ל-Google Chat מעבדות אינטראקציות של משתמשים ומגיבות להן:

הארכיטקטורה של עיבוד האינטראקציות של המשתמשים באפליקציות ל-Google Chat.

טריגרים

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

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

טריגר תיאור תשובה אופיינית
נוסף למרחב

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

האפליקציה ל-Chat שולחת הודעת היכרות שמסבירה מה היא עושה ואיך המשתמשים במרחב יכולים להשתמש בה.
Message

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

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

משתמש מסיר את האפליקציה ל-Chat ממרחב משותף, או שאדמין ב-Google Workspace מסיר את האפליקציה ל-Chat בשביל משתמש בארגון שלו.

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

האפליקציה ל-Chat מסירה את כל ההתראות הנכנסות שהוגדרו למרחב (למשל, מחיקת webhook) ומנקה את האחסון הפנימי. אפליקציות הצ'אט לא יכולות להגיב בטריגר הזה כי הן כבר לא חלק מהמרחב.
פקודת אפליקציה

המשתמש מפעיל פקודה באפליקציה ל-Chat (כמו פקודה דרך שורת הפקודות, פקודה מהירה או פעולה בהודעה).

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

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

האפליקציה ל-Chat מחזירה אובייקט RenderActions ששולח כרטיס דף בית (pushCard) או מעדכן את כרטיס דף הבית שמוצג (updateCard).

אתם יכולים להגדיר את נקודות הקצה או את פונקציות הקריאה החוזרת של הטריגרים האלה בדף Configuration של Chat API במסוף Google Cloud. להוראות מפורטות, ראו הגדרת Google Chat API.

הגדרת הצעות לפרומפטים

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

כדי להוסיף ולהגדיר הצעות לפרומפט:

  1. במסוף Google Cloud, נכנסים לדף Configuration של Chat API:

    לדף ההגדרות של Chat API

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

  3. בשדה Rank (1-3), מזינים מספר מ-1 עד 3 כדי לציין את סדר התצוגה. לכל הנחיה מוגדרת צריך להיות דירוג ייחודי.

  4. בקטע בחירת סוג, בוחרים את אופן הפעולה של ההנחיה:

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

    • אם בחרתם באפשרות "פרומפט טקסטואלי":

      1. בשדה כותרת, מזינים את הכותרת של ההנחיה שמוצגת בצ'יפ, עד 30 תווים. הכותרת לא יכולה להכיל קווים נטויים או לוכסנים הפוכים.
      2. בשדה טקסט ההנחיה, מזינים את הטקסט שיופיע בשורת הכתיבה, עד 60 תווים. טקסט ההנחיה לא יכול להכיל לוכסנים או לוכסנים הפוכים.
      3. אופציונלי: מוסיפים שמות וטקסטים מקומיים למשתמשים בשפות אחרות:
      4. בקטע הנחיות מותאמות לשוק המקומי, לוחצים על הוספת שפה.
      5. בקטע שפה, בוחרים שפה נתמכת מהתפריט.
      6. בשדה כותרת מותאמת לשוק המקומי, מזינים את הכותרת המותאמת לשוק המקומי, עד 30 תווים.
      7. בשדה Localized text, מזינים את הטקסט המותאם לשוק המקומי של ההנחיה, עד 60 תווים.
      8. חוזרים על הפעולה כדי להוסיף עוד שפות לפי הצורך.
    • אם בחרתם באפשרות "פקודה":

      1. בשדה מזהה פקודה, בוחרים את הפקודה מהתפריט.
  6. לוחצים על סיום ואז על שמירה בתחתית הדף.

טיפול בניסיונות חוזרים של קריאות HTTP לשירות שלכם

אם בקשת HTTPS לשירות שלכם נכשלת (למשל, בגלל זמן קצוב לתפוגה, כשל זמני ברשת או קוד סטטוס של HTTPS שאינו 2xx), יכול להיות ש-Google Chat תנסה לשלוח שוב את ההודעה כמה פעמים תוך כמה דקות (אבל זה לא מובטח). כתוצאה מכך, יכול להיות שאפליקציית Chat תקבל את אותו אירוע כמה פעמים במצבים מסוימים. אם הבקשה הושלמה בהצלחה אבל החזירה מטען ייעודי (payload) לא תקין, אפליקציית Google Chat לא תנסה לשלוח אותה שוב.

אובייקטים מסוג אירוע

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

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

הגדרת סוגי האירועים והתגובות

כשאפליקציית הצ'אט מקבלת אובייקט מסוג אירוע, המבנה של המטען הייעודי (payload) והאופן שבו אתם מגיבים תלויים בשאלה אם אפליקציית הצ'אט מוגדרת כתוסף ל-Google Workspace.

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

סוג האפליקציה מקבל אירועים של תוספים
(ברירת המחדל לאפליקציות חדשות שנוצרו אחרי יולי 2025)
מקבל אירועים ב-Chat
(ברירת המחדל הקודמת, לפני יולי 2025)
אפליקציות של Apps Script
בודקים את קובץ המניפסט (appsscript.json)
האובייקט chat מוגדר בתוך addOns:
{
  "addOns": {
    "chat": {}
  }
}
האובייקט chat מוגדר ברמה הבסיסית (root) של המניפסט:
{
  "chat": {}
}
אפליקציות אחרות
בודקים את דף ההגדרות של Google Chat API
תיבת הסימון "פיתוח האפליקציה ל-Chat כתוסף ל-Google Workspace" מסומנת. תיבת הסימון "פיתוח אפליקציית הצ'אט הזו כתוסף ל-Google Workspace" לא מסומנת.
איפה אפשר למצוא את מאמרי העזרה במדריכים ובדוגמאות הקוד

מאמרי עזרה בנושא אירועים: אובייקטים מסוג אירוע בתוספים
קטעים מכווצים (לדוגמה, אפליקציות ל-Chat שהן לא תוספים: קבלה של אירועי אינטראקציה ותגובה להם)

מאמרי עזרה בנושא אירועים: אירועי אינטראקציה ב-Chat API
איך מגיבים מחזירים פעולה, כמו DataActions או RenderActions.
איך מגיבים באמצעות פעולה
החזרת משאב Message.
איך עונים באמצעות הודעה

מטענים ייעודיים (payloads) של אובייקטים מסוג אירוע

כל אובייקט מסוג אירוע של תוספים כולל commonEventObject עם פרטים על המארח והפלטפורמה (hostApp: "CHAT",‏ clientPlatform,‏ userLocale,‏ userTimezone,‏ parameters ו-formInputs) ואובייקט chat שמכיל הקשר ספציפי ל-Chat:

  • בטריגר דף הבית של האפליקציה (כשמשתמש פותח את הכרטיסייה דף הבית בצ'אט אישי עם האפליקציה ל-Chat), האובייקט chat מכיל את chat.user ואת chat.eventTime בלי שדה איחוד payload. כשמשתמש לוחץ על כפתור בכרטיס של דף הבית, אובייקט האירוע כולל את chat.buttonClickedPayload יחד עם commonEventObject.parameters (וגם את commonEventObject.formInputs אם הכרטיס מכיל קלט של טופס).
  • באינטראקציות במרחבים משותפים ובהודעות (Added to space,‏ Message,‏ Removed from space,‏ App command או אינטראקציות עם לחצנים ווידג'טים), האובייקט chat כולל את chat.user,‏ chat.space,‏ chat.eventTime ואת מטען הייעודי (payload) של האינטראקציה:
    • ‫messagePayload: מכיל את space,‏ message ו-configCompleteRedirectUri כשמשתמש שולח הודעה.
    • ‫addedToSpacePayload: מכיל את space, interactionAdd ו-configCompleteRedirectUri כשאפליקציית הצ'אט נוספת למרחב משותף.
    • ‫removedFromSpacePayload: מכיל את space כשאפליקציית הצ'אט מוסרת ממרחב משותף.
    • ‫buttonClickedPayload: מכיל את space,‏ message,‏ isDialogEvent ו-dialogEventType כשמשתמש לוחץ על לחצן בכרטיס או בתיבת דו-שיח.
    • ‫widgetUpdatedPayload: מכיל את space כשמשתמש יוצר אינטראקציה עם ווידג'ט, כמו הקלדה בתפריט לבחירה מרובה עם מקור נתונים חיצוני.
    • ‫appCommandPayload: מכיל את space, message, appCommandMetadata, isDialogEvent, dialogEventType ו-configCompleteRedirectUri כשמשתמש מפעיל פקודה באפליקציה.

כשסשנים של שיחות מופעלים במרחב של צ'אט אישי עם אפליקציית Chat, האובייקט space ב-payload של האינטראקציה (כמו chat.messagePayload.space,‏ chat.addedToSpacePayload.space,‏ chat.buttonClickedPayload.space,‏ chat.widgetUpdatedPayload.space או chat.appCommandPayload.space) כולל את sessionState (מוגדר כ-THREAD) ואת sessionEnableTime, והאובייקט thread (chat.messagePayload.message.thread,‏ chat.buttonClickedPayload.message.thread,‏ chat.appCommandPayload.message.thread או chat.appCommandPayload.thread) מזהה את השרשור של הסשן (spaces/{space}/threads/{thread}).

במאמר אובייקטים מסוג אירוע מוסבר על אובייקטים מסוג אירוע של תוספים ב- Chat ובאפליקציות אחרות של Google Workspace.

שליחת תשובה

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

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

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

  • ‫DataActions: יוצר או מעדכן הודעות בצ'אט (CreateMessageAction, UpdateMessageAction) או מצרף תצוגות מקדימות של קישורים (UpdateInlinePreviewAction) באמצעות chatDataActionMarkup.
  • ‫RenderActions: יוצר, מעדכן או סוגר דף בית או תיבת דו-שיח (pushCard,‏ updateCard,‏ endNavigation: "CLOSE_DIALOG"), או מספק הצעות דינמיות לקלט בתפריט לבחירה מרובה (modifyCard).
  • ‫AuthorizationError: מציג למשתמשים כרטיס הרשאה בסיסי (basic_authorization_prompt) כדי להיכנס או לאמת את הזהות בשירות חיצוני.

בטבלה הבאה מפורטות הפעולות שאפליקציות ל-Chat יכולות לבצע בתגובה להודעות. אפליקציות צ'אט יכולות להחזיר אובייקטים של JSON ישירות או ליצור את התשובה באמצעות AddOnResponseService ו-CardService של Apps Script.

תשובה מאפליקציית Chat הפעולה הנדרשת להחזרה (JSON) פעולה נדרשת להחזרה (Apps Script)
לשלוח הודעה או לעדכן הודעה. ‫DataActions (createMessageAction או updateMessageAction) DataActionsResponse
לראות תצוגה מקדימה של קישורים בהודעות שמשתמשי Chat שולחים במרחב המשותף. ‫DataActions (updateInlinePreviewAction) DataActionsResponse
להציג או לעדכן דף בית בכרטיסייה דף הבית של צ'אט ישיר. ‫RenderActions (pushCard או updateCard) ActionResponse
לפתוח, לעדכן או לסגור תיבת דו-שיח. ‫RenderActions (pushCard,‏ updateCard או endNavigation: "CLOSE_DIALOG") ActionResponse
כדי לאסוף מידע מכרטיס או מתיבת דו-שיח, אפשר להציע פריטים לבחירה על סמך מה שהמשתמשים מקלידים בתפריט לבחירת כמה פריטים. ‫RenderActions (modifyCard) ActionResponse
לבקש הגדרה או הרשאה לשירות חיצוני. ‫AuthorizationError (basic_authorization_prompt) AuthorizationException

מענה באמצעות שליחת הודעה

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

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

ההודעות של אפליקציות הצ'אט יכולות לכלול:

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

{
  "hostAppDataAction": {
    "chatDataAction": {
      "createMessageAction": {
        "message": <var>MESSAGE</var>
      }
    }
  }
}

מחליפים את MESSAGE במשאב Message מ-Chat API.

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

Node.js

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The request object from Google Chat.
 * @param {Object} res The response object from the Chat app.
 */
exports.cymbalApp = function cymbalApp(req, res) {
  const chatEvent = req.body.chat;
  // Send an onboarding message when added to a Chat space
  if (chatEvent.addedToSpacePayload) {
    res.json({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
      text: 'Hi, Cymbal at your service. I help you manage your calendar ' +
        'from Google Chat. Take a look at your schedule today by typing ' +
        '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. ' +
        'To learn what else I can do, type `/help`.'
    }}}}});
  }
};

Python

from flask import Flask, request, json
app = Flask(__name__)

@app.route('/', methods=['POST'])
def cymbal_app():
  """Sends an onboarding message when the Chat app is added to a space.

  Returns:
    Mapping[str, Any]: The response object from the Chat app.
  """
  chat_event = request.get_json()["chat"]
  if "addedToSpacePayload" in chat_event:
    return json.jsonify({ "hostAppDataAction": { "chatDataAction": {
      "createMessageAction": { "message": {
        "text": 'Hi, Cymbal at your service. I help you manage your calendar ' +
        'from Google Chat. Take a look at your schedule today by typing ' +
        '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. ' +
        'To learn what else I can do, type `/help`.'
      }}
    }}})

Java

@SpringBootApplication
@RestController
public class App {
  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  /*
   * Sends an onboarding message when the Chat app is added to a space.
   *
   * @return The response object from the Chat app.
   */
  @PostMapping("/")
  @ResponseBody
  public GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
    JsonNode chatEvent = event.at("/chat");
    if (!chatEvent.at("/addedToSpacePayload").isEmpty()) {
      return new GenericJson() { {
        put("hostAppDataAction", new GenericJson() { {
          put("chatDataAction", new GenericJson() { {
            put("createMessageAction", new GenericJson() { {
              put("message", new Message().setText(
                "Hi, Cymbal at your service. I help you manage your calendar " +
                "from Google Chat. Take a look at your schedule today by typing " +
                "`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. " +
                "To learn what else I can do, type `/help`."
              ));
            } });
          } });
        } });
      } };
    }
    return new GenericJson();
  }
}

Apps Script

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Google Chat.
 * @return {Object} Response from the Chat app.
 */
function onAddedToSpace(event) {
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: 'Hi, Cymbal at your service. I help you manage your calendar ' +
          'from Google Chat. Take a look at your schedule today by typing ' +
          '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. ' +
          'To learn what else I can do, type `/help`.'
  }}}}};
}

דוגמת הקוד מחזירה את הודעת ה-SMS הבאה:

דוגמה להודעה על תהליך ההצטרפות.

עריכת הודעה

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

כדי לעדכן הודעה של אפליקציית Chat בתגובה לאינטראקציה, מחזירים את DataActions עם UpdateMessageAction:

{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateMessageAction": {
        "message": <var>MESSAGE</var>
      }
    }
  }
}

מחליפים את MESSAGE במשאב Message מ-Chat API.

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

שליחת תשובה אסינכרונית באמצעות Google Chat API

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

  • להגיב לאינטראקציה אחרי 30 שניות (למשל, אחרי השלמת משימה ארוכה).
  • שליחת הודעות לפי לוח זמנים, או שליחת התראות על שינויים במשאבים חיצוניים.
  • לבצע משימות מחוץ למרחב שבו התרחשה האינטראקציה.
  • לבצע משימות ב-Chat שלא זמינות כפעולות סינכרוניות, כמו הצגת רשימה של מרחבים או הוספת חברים למרחב.
  • לבצע משימות בשם משתמש ב-Chat (שדורשות אימות משתמש).

אם אתם מגיבים לאינטראקציה אחרי 30 שניות, כדי למנוע הודעת שגיאה שגלויה למשתמשים שאומרת שאפליקציית הצ'אט לא מגיבה, אתם צריכים לאשר את קבלת האובייקט מסוג אירוע תוך 30 שניות על ידי החזרת תגובה ריקה:

Node.js

async function onEvent(req, res) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return res.send({});
};

Python

def on_event(event) -> dict:
  # Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return {}

Java

public String onEvent(JsonNode event) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return "{}";
}

Apps Script

function onEvent(event) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return null;
}

כדי לשלוח הודעה באמצעות Chat API, צריך להגדיר אימות ולקרוא ל-method‏ spaces.messages.create. איך שולחים הודעות? בסקירה הכללית על Chat API מוסבר איך משתמשים בשיטות נוספות של Chat API.

אפליקציות צ'אט שהן לא תוספים: קבלת אינטראקציות של משתמשים ותגובה להן

אפליקציות ל-Chat שהן לא תוספים ל-Google Workspace מקבלות אירועי אינטראקציה של Chat API ‏(Event) במקום אובייקטים מסוג אירוע של תוספים ל-Google Workspace ‏(EventObject), ומגיבות בהחזרת משאב Message במקום פעולה.

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

סוגים של אירועי אינטראקציה

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

אינטראקציה של משתמשים eventType תשובה אופיינית מאפליקציה ל-Chat שהיא לא תוסף
משתמש שולח הודעה לאפליקציה ל-Chat. לדוגמה, מתייג את האפליקציה ל-Chat או משתמש בפקודה דרך שורת הפקודות. MESSAGE אפליקציית הצ'אט מגיבה על סמך תוכן ההודעה. לדוגמה, אפליקציית Chat עונה לפקודה דרך שורת הפקודות /about בהודעה שמסבירה את המשימות שאפליקציית Chat יכולה לבצע.
משתמש מוסיף אפליקציה ל-Chat למרחב. ADDED_TO_SPACE האפליקציה ל-Chat שולחת הודעת היכרות שמסבירה מה היא עושה ואיך המשתמשים במרחב המשותף יכולים להשתמש בה.
משתמש מסיר אפליקציה ל-Chat ממרחב משותף. REMOVED_FROM_SPACE אפליקציית הצ'אט מסירה את כל ההתראות הנכנסות שהוגדרו למרחב (למשל, מחיקת webhook) ומנקה את האחסון הפנימי.
משתמש לוחץ על כפתור בכרטיס מהודעה, מתיבת דו-שיח או מדף הבית של אפליקציית Chat. CARD_CLICKED האפליקציה ל-Chat מעבדת ושומרת את הנתונים שהמשתמש שלח, או מחזירה כרטיס אחר.
המשתמש פותח את דף הבית של האפליקציה ל-Chat בלחיצה על הכרטיסייה דף הבית בצ'אט אישי. APP_HOME אפליקציית הצ'אט מחזירה כרטיס סטטי או אינטראקטיבי מדף הבית.
המשתמש שולח טופס מדף הבית של האפליקציה ל-Chat. SUBMIT_FORM האפליקציה ל-Chat מעבדת ושומרת את הנתונים שהמשתמש שלח, או מחזירה כרטיס אחר.
משתמש מפעיל פקודה באמצעות פקודה מהירה. APP_COMMAND האפליקציה ל-Chat מגיבה בהתאם לפקודה שהופעלה. לדוגמה, אפליקציית Chat עונה לפקודה About בהודעה שמסבירה את המשימות שאפליקציית Chat יכולה לבצע.

כדי לראות את כל אירועי האינטראקציה הנתמכים ודוגמאות למטענים ייעודיים (payloads) בפורמט JSON, קראו את המאמר סוגים של אירועי אינטראקציה באפליקציות ל-Chat ואת מאמרי העזרה של EventType.

אירועי אינטראקציה מתיבות דו-שיח

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

  • השדה isDialogEvent מוגדר ל-true.
  • המאפיין DialogEventType (REQUEST_DIALOG,‏ SUBMIT_DIALOG או CANCEL_DIALOG) מבהיר אם האינטראקציה מפעילה פתיחה של תיבת דו-שיח, שולחת מידע מתיבת דו-שיח או סוגרת תיבת דו-שיח.

אירועי אינטראקציה במרחבים עם סשנים

כשהשיחות מחולקות לנושאים במרחב של צ'אט אישי עם אפליקציה ל-Chat שהיא לא תוסף, השדה space ברמה העליונה של אירוע האינטראקציה כולל את space.sessionState (מוגדר כ-THREAD) ואת space.sessionEnableTime, והשרשור של השיחה מזוהה באמצעות message.thread או thread.

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

  1. במסוף Google Cloud, נכנסים לדף Configuration של Chat API:

    לדף ההגדרות של Chat API

  2. בקטע Interactive features, מבטלים את הסימון של Build this Chat app as a Google Workspace add-on, ומגדירים את Functionality, נקודת קצה אחת של Connection settings (כתובת URL של נקודת קצה ב-HTTP, ‏Apps Script, שם נושא ב-Cloud Pub/Sub או Dialogflow), ‏Commands, ‏Starter prompts, ‏Link previews ו-Visibility.

  3. לוחצים על שמירה.

איך עונים להודעות באפליקציות ל-Chat שהן לא תוספים

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

Node.js

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The event object from Chat API.
 * @param {Object} res The response object from the Chat app.
 */
exports.cymbalApp = function cymbalApp(req, res) {
  // Send an onboarding message when added to a Chat space
  if (req.body.type === 'ADDED_TO_SPACE') {
    res.json({
      'text': 'Hi, Cymbal at your service. I help you manage your calendar ' +
        'from Google Chat. Take a look at your schedule today by typing ' +
        '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To ' +
        'learn what else I can do, type `/help`.'
    });
  }
};

Python

from flask import Flask, request, json
app = Flask(__name__)

@app.route('/', methods=['POST'])
def cymbal_app():
  """Sends an onboarding message when the Chat app is added to a space.

  Returns:
    Mapping[str, Any]: The response object from the Chat app.
  """
  event = request.get_json()
  if event['type'] == 'ADDED_TO_SPACE':
    return json.jsonify({
      'text': 'Hi, Cymbal at your service. I help you manage your calendar ' +
      'from Google Chat. Take a look at your schedule today by typing ' +
      '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To ' +
      'learn what else I can do, type `/help`.'
    })
  return json.jsonify({})

Java

@SpringBootApplication
@RestController
public class App {
  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  /*
   * Sends an onboarding message when the Chat app is added to a space.
   *
   * @return The response object from the Chat app.
   */
  @PostMapping("/")
  @ResponseBody
  public Message onEvent(@RequestBody JsonNode event) {
    switch (event.get("type").asText()) {
      case "ADDED_TO_SPACE":
        return new Message().setText(
          "Hi, Cymbal at your service. I help you manage your calendar " +
          "from Google Chat. Take a look at your schedule today by typing " +
          "`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. " +
          "To learn what else I can do, type `/help`.");
      default:
        return new Message();
    }
  }
}

Apps Script

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onAddToSpace(event) {
  return {
    'text': 'Hi, Cymbal at your service. I help you manage your calendar ' +
      'from Google Chat. Take a look at your schedule today by typing ' +
      '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To learn ' +
      'what else I can do, type `/help`.'
  };
}