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

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

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

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

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

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

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

אירוע אינטראקציה עם אפליקציית 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.

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

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

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

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

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

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

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

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

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

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

בדוגמה הזו, אפליקציית 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`.'
  }
}

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

דוגמה להודעה למשתמשים חדשים.

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

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

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