‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

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

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

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

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

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

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

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

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

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

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

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

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

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

טריגרים

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

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

טריגר	תיאור	תשובה אופיינית
נוסף למרחב	משתמש מוסיף את אפליקציית הצ'אט למרחב משותף, או שאדמין ב-Google Workspace מתקין את אפליקציית הצ'אט במרחבים משותפים של צ'אטים אישיים בשביל המשתמשים בארגון. במאמר התקנת אפליקציות מ-Marketplace בדומיין במרכז העזרה של Google Workspace Admin מוסבר איך אדמינים יכולים להתקין אפליקציות ל-Chat.	האפליקציה ל-Chat שולחת הודעת היכרות שמסבירה מה היא עושה ואיך המשתמשים במרחב יכולים לתקשר איתה.
Message	משתמש יוצר אינטראקציה עם אפליקציית הצ'אט בהודעה באחת מהדרכים הבאות: שליחת הודעה במרחב של צ'אט אישי באמצעות אפליקציית Chat. מתייגים את האפליקציה ל-Chat בכל סוג של מרחב. שולח הודעה שמכילה קישור שתואם לתבנית ה-URL של התצוגות המקדימות של הקישורים. הקלדת טקסט בתפריט לבחירת כמה אפשרויות בווידג'ט של `selectionInput` .	האפליקציה ל-Chat תגיב בהתאם לתוכן של ההודעה. לדוגמה, אפליקציית Chat יכולה לענות בהודעה, לצרף כרטיס תצוגה מקדימה של קישור או להציע פריטים בתפריט לבחירה מרובה.
הוסרתם מהמרחב המשותף	משתמש מסיר את האפליקציה ל-Chat ממרחב משותף, או שאדמין ב-Google Workspace מסיר את האפליקציה ל-Chat בשביל משתמש בארגון שלו. המשתמשים לא יכולים להסיר אפליקציות ל-Chat שהאדמין התקין. אם משתמש התקין בעבר את אפליקציית Chat, היא תישאר מותקנת גם אם אדמין ב-Google Workspace ינסה להסיר אותה.	האפליקציה ל-Chat מסירה את כל ההתראות הנכנסות שהוגדרו למרחב (למשל, מחיקת webhook) ומנקה את כל האחסון הפנימי. אפליקציות הצ'אט לא יכולות להגיב עם הודעות לטריגר הזה כי הן כבר לא חברות במרחב המשותף.
פקודת אפליקציה	המשתמש מפעיל פקודה באפליקציה ל-Chat (כמו פקודה דרך שורת הפקודות, פקודה מהירה או פעולה בהודעה).	האפליקציה ל-Chat תגיב לפקודה. לדוגמה, היא יכולה להשיב בהודעה או לפתוח תיבת דו-שיח.
דף הבית של האפליקציה	המשתמש פותח את הכרטיסייה דף הבית במרחב של צ'אט ישיר עם האפליקציה ל-Chat, או מבצע פעולה בווידג'ט בכרטיס של דף הבית.	אפליקציית הצ'אט מחזירה אובייקט `RenderActions` ששולח כרטיס דף בית (`pushCard`) או מעדכן את כרטיס דף הבית שמוצג (`updateCard`).

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

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

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

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

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

לדף ההגדרות של Chat API
בקטע תכונות אינטראקטיביות, מאתרים את האפשרות הצעות לפרומפטים ולוחצים על הוספת הצעה לפרומפט.
בשדה דירוג (1-3), מזינים מספר מ-1 עד 3 כדי לציין את סדר התצוגה.
בקטע בחירת סוג, בוחרים איך ההודעה תתנהג:
- פרומפט טקסטואלי: מאכלס את שורת הכתיבה בטקסט מוגדר מראש כשהמשתמש לוחץ על הצעה לפרומפט.
- שורת הפקודה: מריצה פקודה רשומה דרך שורת הפקודות או פקודה מהירה כשלוחצים עליה. אי אפשר לבחור פקודות שדורשות ארגומנטים נוספים.
מגדירים את ההנחיה בהתאם לסוג שנבחר:
- אם בחרתם באפשרות "פרומפט טקסטואלי":
  1. בשדה כותרת, מזינים את הכותרת של ההנחיה שמוצגת בצ'יפ (עד 30 תווים).
  2. בקטע טקסט של הנחיה, מזינים את הטקסט שמאוכלס בשורת הכתיבה (עד 60 תווים).
  3. אופציונלי: מוסיפים שמות וטקסטים מקומיים למשתמשים בשפות אחרות:
  4. בקטע הנחיות מותאמות לשוק המקומי, לוחצים על הוספת שפה.
  5. בקטע שפה, בוחרים שפה נתמכת מהתפריט הנפתח.
  6. בקטע שם מותאם לשוק המקומי, מזינים את השם המותאם לשוק המקומי (עד 30 תווים).
  7. בקטע טקסט של הנחיה מותאמת לשוק המקומי, מזינים את הטקסט של ההנחיה המותאמת לשוק המקומי (עד 60 תווים).
  8. חוזרים על הפעולה כדי להוסיף עוד שפות לפי הצורך.
- אם בחרתם באפשרות "שורת הפקודה":
  1. בפקודה דרך שורת הפקודות / פקודה מהירה, בוחרים את הפקודה מהתפריט הנפתח.
לוחצים על סיום ואז על שמירה בתחתית הדף.

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

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

אובייקטים של אירועים

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

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

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

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

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

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

מטענים ייעודיים של אובייקטים של אירועים

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

בטריגר דף הבית של האפליקציה (כשמשתמש פותח את הכרטיסייה דף הבית בצ'אט אישי עם האפליקציה ל-Chat), האובייקט chat מכיל את chat.user ואת chat.eventTime בלי שדה האיחוד payload. כשמשתמש לוחץ על כפתור בכרטיס של דף הבית, אובייקט האירוע כולל את chat.buttonClickedPayload יחד עם commonEventObject.parameters (וגם את commonEventObject.formInputs אם הכרטיס מכיל קלט של טופס).
באינטראקציות במרחבים משותפים ובהודעות (נוסף למרחב המשותף, הודעה, הוסר מהמרחב המשותף, פקודת אפליקציה או אינטראקציות עם לחצנים ווידג'טים), האובייקט 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 ובאפליקציות אחרות של Google Workspace.

שליחת תשובה

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

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

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

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

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

תשובה מאפליקציית הצ'אט	הפעולה הנדרשת להחזרה (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`

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

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

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

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

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

כדי להשיב באמצעות הודעה, מחזירים את 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`.'
  }}}}};
}

דוגמת הקוד מחזירה את הודעת הטקסט הבאה:

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

עדכון הודעה

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

כדי לעדכן הודעה של אפליקציית 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 שהן לא תוספים: קבלת אינטראקציות של משתמשים ותגובה להן

אפליקציות ל-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 למרחב.	`ADDED_TO_SPACE`	האפליקציה ל-Chat שולחת הודעת היכרות שמסבירה מה היא עושה ואיך המשתמשים במרחב יכולים להשתמש בה.
משתמש מסיר אפליקציה ל-Chat ממרחב משותף.	`REMOVED_FROM_SPACE`	אפליקציית Chat מסירה את כל ההתראות הנכנסות שהוגדרו למרחב (למשל, מחיקת Webhook) ומנקה את כל האחסון הפנימי.
משתמש לוחץ על כפתור בכרטיס מהודעה, מתיבת דו-שיח או מדף הבית של אפליקציית הצ'אט.	`CARD_CLICKED`	אפליקציית הצ'אט מעבדת ושומרת את הנתונים שהמשתמש שלח, או מחזירה כרטיס אחר.
המשתמש פותח את דף הבית של האפליקציה ל-Chat בלחיצה על הכרטיסייה דף הבית בצ'אט אישי.	`APP_HOME`	אפליקציית הצ'אט מחזירה כרטיס סטטי או אינטראקטיבי מדף הבית.
המשתמש שולח טופס מדף הבית של האפליקציה ל-Chat.	`SUBMIT_FORM`	אפליקציית הצ'אט מעבדת ושומרת את הנתונים שהמשתמש שלח, או מחזירה כרטיס אחר.
משתמש מפעיל פקודה באמצעות פקודה מהירה.	`APP_COMMAND`	אפליקציית הצ'אט מגיבה בהתאם לפקודה שהופעלה. לדוגמה, אפליקציית Chat עונה לפקודה About בהודעה שמסבירה את המשימות שאפליקציית Chat יכולה לבצע.

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

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

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

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

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

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

לדף ההגדרות של Chat API
בקטע תכונות אינטראקטיביות, מבטלים את הבחירה באפשרות פיתוח האפליקציה הזו ל-Chat כתוסף ל-Google Workspace, ומגדירים את הפונקציונליות, נקודת קצה אחת בהגדרות החיבור (כתובת URL של נקודת קצה ב-HTTP, ‏Apps Script, שם נושא ב-Cloud Pub/Sub או Dialogflow), פקודות, הודעות פתיחה, תצוגות מקדימות של קישורים והרשאות גישה.
לוחצים על שמירה.

איך עונים להודעות באפליקציות ל-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`.'
  };
}

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

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

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

טריגרים

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

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

אובייקטים של אירועים

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

מטענים ייעודיים של אובייקטים של אירועים

שליחת תשובה

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

Node.js

Python

Java

Apps Script

עדכון הודעה

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

Node.js

Python

Java

Apps Script

נושאים קשורים

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

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

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

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

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

Node.js

Python

Java

Apps Script

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