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

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

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

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

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

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

איך פועלים אירועי אינטראקציה

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

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

דוגמה לאירוע של אינטראקציה תשובה אופיינית מאפליקציית Chat
משתמש מפעיל אפליקציית Chat אזכור באמצעות @ או שימוש בפקודת קו נטוי. אפליקציית Chat מעבדת את תוכן ההודעה יוצרים הודעה. לדוגמה, אפליקציית Chat משיבה ל: באמצעות הפקודה /about עם הודעה שמסבירה את המשימות אפליקציית Chat יכולה לעשות.
משתמש מוסיף אפליקציית Chat ל- מרחב משותף. אפליקציית Chat שולחת הדרכה למשתמשים חדשים הודעה שמסבירה מה הוא עושה ואיך משתמשים במרחב המשותף יכולים לקיים אינטראקציה את זה.
משתמש מסיר אפליקציית Chat ממרחב משותף. אפליקציית Chat מסירה את כל ההתראות הנכנסות שהוגדרו למרחב (למשל, מחיקת webhook) ומבטל את המחיקה ואחסון פנימי.
משתמש לוחץ על לחצן בכרטיס או בתיבת דו-שיח שנשלחו אפליקציית Chat. אפליקציית Chat מעבדת ושומרת כל או נתונים שהמשתמש שלח, או מחזיר כרטיס אחר או תיבת דו-שיח אחרת.

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

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

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

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

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

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

  1. במסוף Google Cloud, נכנסים לדף של Chat API ולוחצים על דף הגדרות אישיות:

    לדף ההגדרה של Chat API

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

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

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

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

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

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

איך מצטרפים למרחבים משותפים

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

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