דף זה תורגם על ידי Cloud Translation API.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

שדה	תיאור
פונקציונליות	חובה. קבוצה של שדות שקובעים איך אפליקציית Chat יכולה לקיים אינטראקציה עם משתמשים. כברירת מחדל, המשתמשים יכולים למצוא את אפליקציית Chat ולשלוח לה הודעות ישירות ב-Google Chat. הצטרפות למרחבים ולשיחות קבוצתיות: המשתמשים יכולים להוסיף את אפליקציית Chat למרחבים ולשיחות קבוצתיות.
הגדרות חיבור	חובה. נקודת הקצה של אפליקציית Chat, שהיא אחת מהאפשרויות הבאות: כתובת ה-URL של נקודת הקצה ב-HTTP: נקודת קצה ב-HTTPS שמארחת את ההטמעה של אפליקציית Chat. ‫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 עם הצוות. מידע נוסף מופיע במאמר בנושא בדיקת תכונות אינטראקטיביות.

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

לכל אירוע אינטראקציה, אפליקציות ל-Chat מקבלות גוף בקשה, שהוא מטען ייעודי (payload) של JSON שמייצג את האירוע. אפשר להשתמש במידע כדי לעבד תשובה. דוגמאות למטענים ייעודיים (payloads) של אירועים מופיעות במאמר סוגי אירועים של אינטראקציה עם אפליקציות ל-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.
 */
exports.cymbalApp = function cymbalApp(req, res) {
  // 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`.'
    });
  }
};

Python

from flask import Flask, request, json
app = Flask(__name__)

@app.route('/', methods=['POST'])
def cymbal_app():
  """Sends an onboarding message when the Chat app is added to a space.

  Returns:
    Mapping[str, Any]: The response object from the Chat app.
  """
  event = request.get_json()
  if event['type'] == 'ADDED_TO_SPACE':
    return json.jsonify({
      '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`.'
    })
  return json.jsonify({})

Java

@SpringBootApplication
@RestController
public class App {
  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  /*
   * Sends an onboarding message when the Chat app is added to a space.
   *
   * @return The response object from the Chat app.
   */
  @PostMapping("/")
  @ResponseBody
  public Message onEvent(@RequestBody JsonNode event) {
    switch (event.get("type").asText()) {
      case "ADDED_TO_SPACE":
        return new Message().setText(
          "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`.");
      default:
        return new Message();
    }
  }
}

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.
 */
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.