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

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

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

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

פיתוח אפליקציה אינטראקטיבית ל-Chat בתור תוסף ל-Google Workspace

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

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

אפליקציית 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 תוכל להשיב מיד בהודעת פתיחה במרחב המשותף.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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