בדף הזה מוסבר איך אפליקציית Chat שלכם יכולה לקבל אינטראקציות של משתמשים ב-Google Chat ולהגיב להן.
כדי ליצור ממשקים אינטראקטיביים לאפליקציות ל-Chat, משתמשים ברכיבים הבאים:
- טריגרים: הדרכים שבהן משתמשי Google Chat יכולים להפעיל אפליקציה ל-Chat, כמו הוספה שלה למרחב או שליחת הודעה אליה.
- אובייקטים מסוג אירוע: הנתונים שאפליקציות ל-Chat מקבלות מטריגרים או מאינטראקציות בממשק המשתמש.
- פעולות: הדרכים שבהן אפליקציות ל-Chat יכולות להגיב לאינטראקציות, כמו שליחת הודעות או החזרת ממשק משתמש שמבוסס על כרטיסים.
אפליקציות צ'אט יכולות ליצור ולהציג ממשקים בדרכים הבאות:
- הודעות שיכולות להכיל טקסט, כרטיסים סטטיים או אינטראקטיביים, ולחצני עזר.
- דפי בית (דף הבית של האפליקציה) שמופיעים בכרטיסייה דף הבית בצ'אטים האישיים עם האפליקציה ל-Chat.
- תיבות דו-שיח, שהן כרטיסים שנפתחים בחלון חדש ובדרך כלל מבקשים מהמשתמשים לשלוח מידע.
- תצוגות מקדימות של קישורים, שהן כרטיסים שמציגים מידע על שירות חיצוני.
דרישות מוקדמות
- חשבון Business או Enterprise ב-Google Workspace עם גישה ל-Google Chat.
- יוצרים פרויקט ב-Google Cloud.
- מגדירים את מסך ההסכמה ל-OAuth.
- מפעילים ומגדירים את Google Chat API.
איך פועלות האינטראקציות של המשתמשים
כשמשתמש יוצר אינטראקציה עם אפליקציה ל-Chat, Google Chat מפעיל טריגר שהוגדר ושולח אובייקט מסוג אירוע לנקודת הקצה או לפונקציה של האפליקציה ל-Chat. האפליקציה ל-Chat מעבדת את אובייקט האירוע ויכולה להחזיר פעולה באופן סינכרוני תוך 30 שניות, או להגיב באופן אסינכרוני באמצעות Chat API.
בתרשים הבא אפשר לראות איך אפליקציות ל-Google Chat מעבדות אינטראקציות של משתמשים ומגיבות להן:
טריגרים
טריגרים הם הדרכים הספציפיות שבהן המשתמשים מפעילים אפליקציה ל-Chat באמצעות ממשק המשתמש של Chat, כמו תיוגים או פקודות לאפליקציה.
בטבלה הבאה מוצגים טריגרים של Chat, תיאור ואיך אפליקציות ל-Chat בדרך כלל מגיבות:
| טריגר | תיאור | תשובה אופיינית |
|---|---|---|
| נוסף למרחב |
משתמש מוסיף את אפליקציית הצ'אט למרחב משותף, או שאדמין ב-Google Workspace מתקין את אפליקציית הצ'אט במרחבים משותפים של צ'אטים אישיים בשביל המשתמשים בארגון. כדי לקבל מידע על אפליקציות ל-Chat שהותקנו על ידי אדמינים, אפשר לעיין במאמר התקנת אפליקציות מ-Marketplace בדומיין במסמכי העזרה לאדמינים ב-Google Workspace. |
האפליקציה ל-Chat שולחת הודעת היכרות שמסבירה מה היא עושה ואיך המשתמשים במרחב יכולים להשתמש בה. |
| Message |
משתמש יוצר אינטראקציה עם אפליקציית הצ'אט בהודעה באחת מהדרכים הבאות:
|
האפליקציה ל-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 כשהם פותחים צ'אט אישי ריק עם האפליקציה. אפשר להגדיר עד שלוש הצעות לפרומפט.
כדי להוסיף ולהגדיר הצעות לפרומפט:
במסוף Google Cloud, נכנסים לדף Configuration של Chat API:
בקטע תכונות אינטראקטיביות, מאתרים את האפשרות הצעות לפרומפטים ולוחצים על הוספת הצעה לפרומפט או פקודה כברירת מחדל.
בשדה Rank (1-3), מזינים מספר מ-
1עד3כדי לציין את סדר התצוגה. לכל הנחיה מוגדרת צריך להיות דירוג ייחודי.בקטע בחירת סוג, בוחרים את אופן הפעולה של ההנחיה:
- פרומפט טקסטואלי: מאכלס את שורת הכתיבה בטקסט מוגדר מראש כשהמשתמש לוחץ על הצעה לפרומפט.
- פקודה: מריצה פקודה רשומה דרך שורת הפקודות או פקודה מהירה כשלוחצים עליה. אי אפשר למפות פעולות בהודעות להצעות לפרומפט.
מגדירים את ההנחיה בהתאם לסוג שנבחר:
אם בחרתם באפשרות "פרומפט טקסטואלי":
- בשדה כותרת, מזינים את הכותרת של ההנחיה שמוצגת בצ'יפ, עד 30 תווים. הכותרת לא יכולה להכיל קווים נטויים או לוכסנים הפוכים.
- בשדה טקסט ההנחיה, מזינים את הטקסט שיופיע בשורת הכתיבה, עד 60 תווים. טקסט ההנחיה לא יכול להכיל לוכסנים או לוכסנים הפוכים.
- אופציונלי: מוסיפים שמות וטקסטים מקומיים למשתמשים בשפות אחרות:
- בקטע הנחיות מותאמות לשוק המקומי, לוחצים על הוספת שפה.
- בקטע שפה, בוחרים שפה נתמכת מהתפריט.
- בשדה כותרת מותאמת לשוק המקומי, מזינים את הכותרת המותאמת לשוק המקומי, עד 30 תווים.
- בשדה Localized text, מזינים את הטקסט המותאם לשוק המקומי של ההנחיה, עד 60 תווים.
- חוזרים על הפעולה כדי להוסיף עוד שפות לפי הצורך.
אם בחרתם באפשרות "פקודה":
- בשדה מזהה פקודה, בוחרים את הפקודה מהתפריט.
לוחצים על סיום ואז על שמירה בתחתית הדף.
טיפול בניסיונות חוזרים של קריאות 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:
|
האובייקט chat מוגדר ברמה הבסיסית (root) של המניפסט:
|
| אפליקציות אחרות בודקים את דף ההגדרות של 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 או מוסיפים אותה למרחב משותף.
- טריגרים של פקודות לאפליקציה, למשל כשמשתמשים מפעילים פקודה דרך שורת הפקודות או פקודה מהירה.
- קליקים על כפתורים בכרטיסים בהודעות או בתיבות דו-שיח. לדוגמה, כשמשתמשים מזינים מידע ולוחצים על "שליחה".
ההודעות של אפליקציות הצ'אט יכולות לכלול:
- טקסט שמכיל היפר-קישורים, תיוגים עם @ ואמוג'י. איך מעצבים הודעות
- כרטיס אחד או יותר, שיכולים להופיע בהודעה או להיפתח בחלון חדש כתיבת דו-שיח. איך יוצרים כרטיסים לאפליקציות ל-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`.'
}}}}};
}
דוגמת הקוד מחזירה את הודעת ה-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.
נושאים קשורים
- הגדרת Google Chat API
- אני רוצה לשלוח הודעה
- מענה לפקודות
- פתיחת תיבות דו-שיח אינטראקטיביות
- קריאת נתונים שהמשתמשים הזינו בטפסים בכרטיסים
- תצוגה מקדימה של קישורים
- איך יוצרים דף בית לאפליקציה ל-Chat
- ארגון השיחות בסשנים
- אימות בקשות מ-Chat
- בדיקת תכונות אינטראקטיביות באפליקציות ל-Google 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 יכולה לבצע. |
| משתמש מוסיף אפליקציה ל-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 שהיא לא תוסף כדי לקבל אירועי אינטראקציה
במסוף Google Cloud, נכנסים לדף Configuration של Chat API:
בקטע 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.
לוחצים על שמירה.
איך עונים להודעות באפליקציות ל-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`.'
};
}