קבלת אירועי אינטראקציה ושליחת תגובות אליהם

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

בדף הזה נסביר איך:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• הערך של isDialogEvent הוא true.
• ההגדרה DialogEventType מבהירה אם האינטראקציה מפעילה פתיחה של תיבת דו-שיח, שולחת מידע מתיבת דו-שיח או סוגרת תיבת דו-שיח.

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

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

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

קבלת אירועים של אינטראקציות עם אפליקציית Chat

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

הגדרת אפליקציית Chat לקבלת אירועי אינטראקציה

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

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

1. במסוף Google Cloud, עוברים לדף Chat API ולוחצים על Configuration:

   כניסה לדף ההגדרות של Chat API

2. בקטע תכונות אינטראקטיביות, בודקים את ההגדרות ומעדכנים אותן בהתאם לתכונות שרוצים ליצור:

   שדה	תיאור
   פונקציונליות	חובה. קבוצה של שדות שקובעים איך אפליקציית הצ'אט יכולה לקיים אינטראקציה עם משתמשים. כברירת מחדל, המשתמשים יכולים למצוא את אפליקציית Chat ולשלוח לה הודעות ישירות ב-Google Chat. הצטרפות למרחבים ולשיחות קבוצתיות: המשתמשים יכולים להוסיף את אפליקציית Chat למרחבים ולשיחות קבוצתיות.
   הגדרות חיבור	חובה. נקודת הקצה של אפליקציית Chat, שהיא אחת מהאפשרויות הבאות: כתובת ה-URL של נקודת הקצה ב-HTTP: נקודת קצה ב-HTTPS שמארחת את ההטמעה של אפליקציית הצ'אט. ‫Apps Script: מזהה פריסה של פרויקט Apps Script שמטמיע אפליקציית Chat. שם הנושא ב-Cloud Pub/Sub: נושא ב-Pub/Sub שאפליקציית Chat נרשמת אליו כמסוף. ‫Dialogflow: רישום אפליקציית Chat בשילוב עם Dialogflow. מידע נוסף זמין במאמר פיתוח אפליקציה ל-Google Chat באמצעות Dialogflow שמבינה שפה טבעית.
   פקודות	אופציונלי. פקודות סלאש ופקודות מהירות לאפליקציית Chat. הפקודות מאפשרות למשתמשים לבקש פעולה או להשתמש בתכונה ספציפית של אפליקציית Chat. מידע נוסף זמין במאמר איך מגיבים לפקודות של אפליקציות ל-Google Chat.
   תצוגות מקדימות לקישורים	אופציונלי. דפוסי כתובות URL שאפליקציית Chat מזהה ומספקת תוכן נוסף לגביהם כשמשתמשים שולחים קישורים. מידע נוסף זמין במאמר בנושא תצוגה מקדימה של קישורים.
   חשיפה	אופציונלי. עד חמישה אנשים, או קבוצה אחת או יותר ב-Google שאפשר להציג ולהתקין את אפליקציית Chat. אפשר להשתמש בשדה הזה כדי לבדוק את אפליקציית Chat או כדי לשתף את אפליקציית Chat עם הצוות. מידע נוסף זמין במאמר בנושא בדיקת תכונות אינטראקטיביות.

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

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

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

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

עיבוד או תגובה לאירועי אינטראקציה

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

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

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

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

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

הצגת התשובות באופן שוטף

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

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

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

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

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

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

כדי לשלוח הודעת טקסט כשמשתמש מוסיף את אפליקציית Chat שלכם למרחב, אפליקציית Chat מגיבה לADDED_TO_SPACE אירוע אינטראקציה. כדי להשיב לאירועי אינטראקציה של 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. An onboarding message that
 * introduces the app and helps people get started with it.
 */
exports.onMessage = function onMessage(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send(
      'Hello! This function is meant to be used in a Google Chat space.');
  }

  // 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`.'
    });
  }
};

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. An onboarding message that
 * introduces the app and helps people get started with it.
 */
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`.'
  }
}

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

מענה לא סינכרוני

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

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

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

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