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

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

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

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

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

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

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

אפליקציית 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.

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

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