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

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

בדף הזה נסביר איך לבצע את הפעולות הבאות:

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

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

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

• שירות HTTP באמצעות Google Cloud Functions
• Google Apps Script
• Google Cloud Dialogflow CX
• Google Cloud Pub/Sub

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

אירוע אינטראקציה באפליקציה ב-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 למרחב משותף, אפליקציית Chat מקבלת אירוע אינטראקציה מסוג ADDED_TO_SPACE, שבו היא מטפלת כדי לשלוח הודעת פתיחה במרחב המשותף.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

לכל אירוע אינטראקציה, אפליקציות ל-Chat מקבלות גוף בקשה, שהוא המטען הייעודי (payload) של JSON שמייצג את האירוע. תוכלו להשתמש במידע הזה כדי לעבד תשובה. דוגמאות לעומסי נתונים של אירועים מפורטות במאמר סוגים של אירועי אינטראקציה באפליקציית 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 שניות, או לבצע משימות מחוץ למרחב שבו נוצר אירוע האינטראקציה. לדוגמה, יכול להיות שאפליקציית צ'אט תצטרך להגיב למשתמש אחרי השלמת משימה ממושכת. במקרה כזה, אפליקציות צ'אט יכולות להשיב באופן אסינכרוני על ידי קריאה ל-Google Chat API.

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

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

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