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

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

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

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

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

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

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

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

שדות משותפים

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

Field תיאור
type סוג האירוע שאפליקציית Chat מקבלת, למשל MESSAGE או ADDED_TO_SPACE.
eventTime חותמת הזמן שמציינת מתי האירוע נשלח.
common מייצג מידע על הלקוח של המשתמש, כמו הלוקאל או הפלטפורמה.

שדות לפי סוג אירוע האינטראקציה

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

Field תיאור סוג האירוע
message ההודעה שקשורה לאירוע. MESSAGE, ADDED_TO_SPACE, CARD_CLICKED.
space המרחב המשותף שקשור לאירוע. MESSAGE, ADDED_TO_SPACE, REMOVED_FROM_SPACE, CARD_CLICKED.
user המשתמש שקשור לאירוע. המשתמש הוא תמיד אדם (לא אפליקציה ל-Chat). MESSAGE, ADDED_TO_SPACE, REMOVED_FROM_SPACE, CARD_CLICKED.
action הפונקציה שמשתמש מפעיל כשהוא לוחץ על כרטיס אינטראקטיבי או תיבת דו-שיח. CARD_CLICKED.

דוגמאות למטענים ייעודיים (payloads) של אירועים

בקטע הזה מוסבר מה מפעיל אירוע אינטראקציה ומספק מטען ייעודי (payload) לדוגמה של JSON לכל אחד מסוגי האירועים הבאים:

מסר

אירוע האינטראקציה הזה מייצג מתי מישהו שולח הודעה לאפליקציית Chat, למשל:

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

בדוגמה הבאה ל-JSON מוצג אירוע אינטראקציה עם MESSAGE שבו משתמש מאזכר @ אפליקציית Chat במרחב משותף עם כמה אנשים:

{
  "type": "MESSAGE",
  "eventTime": {
      "seconds": 1691187414,
      "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "displayName": "Customer Support Superstars",
    "spaceType": "SPACE"
  },
  "message": {
    "name": "spaces/AAAAAAAAAAA/messages/CCCCCCCCCCC",
    "sender": {
      "name": "users/12345678901234567890",
      "displayName": "Izumi",
      "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
      "email": "izumi@example.com"
    },
    "createTime": {
      "seconds": 1691187386,
      "nanos": 954319000
    },
    "text": "@TestBot Create ticket.",
    "argumentText": " Create ticket.",
    "thread": {
      "name": "spaces/AAAAAAAAAAA/threads/BBBBBBBBBBB",
      "threadKey": "custom-thread-ID"
    },
    "annotations": [
      {
        "length": 8,
        "startIndex": 0,
        "userMention": {
          "type": "MENTION",
          "user": {
            "avatarUrl": "https://.../avatar.png",
            "displayName": "TestBot",
            "name": "users/1234567890987654321",
            "type": "BOT"
          }
        },
        "type": "USER_MENTION"
      }
    ],
    "attachment": [
      {
        "name": "spaces/5o6pDgAAAAE/messages/Ohu1LlUVcS8.Ohu1LlUVcS8/attachments/AATUf-Iz7d8kySEdRRZd-dznqBk3",
        "content_name": "solar.png",
        "content_type": "image/png",
        "drive_data_ref": {
          "drive_file_id": "H1HqaqRuH2Pfd_TOa1fF2_ltwDlV_yKRrr"
        },
        "source": "DRIVE_FILE"
      }
    ]
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

נוסף למרחב המשותף

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

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

{
  "type": "ADDED_TO_SPACE",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "displayName": "Customer Support Superstars",
    "spaceType": "SPACE",
    "adminInstalled": "false"
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

ההתקנה בוצעה על ידי אדמינים ב-Google Workspace

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

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

בדוגמה הבאה ל-JSON מוצג גוף הבקשה לאירוע אינטראקציה עם ADDED_TO_SPACE כשאדמין ב-Google Workspace מתקין אפליקציית Chat עבור משתמש. מכיוון שאדמין התקין את אפליקציית Chat, הערך של adminInstalled מוגדר ל-true:

{
  "type": "ADDED_TO_SPACE",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "displayName": "Customer Support Superstars",
    "spaceType": "DIRECT_MESSAGE",
    "adminInstalled": "true"
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

ההסרה מהמרחב המשותף בוצעה

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

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

{
  "type": "REMOVED_FROM_SPACE",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "spaceType": "SPACE",
    "adminInstalled": "false"
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

אדמינים ב-Google Workspace הוסרו

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

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

בדוגמה הבאה ל-JSON מוצג גוף הבקשה לאירוע אינטראקציה עם REMOVED_FROM_SPACE כשאדמין ב-Google Workspace מסיר אפליקציית Chat עבור משתמש. מכיוון שאפליקציית Chat הוסרה על ידי האדמין, הערך של adminInstalled מוגדר ל-true:

{
  "type": "REMOVED_FROM_SPACE",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "spaceType": "DIRECT_MESSAGE",
    "adminInstalled": "true"
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

בוצעה לחיצה על הכרטיס

אירוע האינטראקציה הזה מציין שמשתמש לחץ על לחצן בהודעה או בתיבת דו-שיח של כרטיס.

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

  • המשתמש לוחץ על הלחצן Send feedback בכרטיס, ונפתחת תיבת דו-שיח שבה הוא יכול להזין מידע.
  • המשתמש לוחץ על הלחצן Submit אחרי שמזינים מידע בכרטיס או בתיבת דו-שיח.

בדוגמה הבאה ל-JSON מוצג גוף הבקשה לאירוע אינטראקציה עם CARD_CLICKED כשמשתמש לוחץ על לחצן בהודעת כרטיס שמקצה לו כרטיס תמיכה נכנס:

{
  "type": "CARD_CLICKED",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "common": {
    "userLocale": "en",
    "hostApp": "CHAT",
    "invokedFunction": "doAssignTicket",
    "timeZone": {
      "offset": -25200000,
      "id": "America/Los_Angeles"
    }
  },
  "action": {
    "actionMethodName": "doAssignTicket"
  },
  "message": {
    "cards": [
      {
        "header": {
          "title": "Incoming support ticket."
        },
        "sections": [
          {
            "widgets": [
              {
                "textParagraph": {
                  "text": "Incoming support ticket #12345 is unassigned and needs your attention."
                }
              },
              {
                "buttons": [
                  {
                    "textButton": {
                      "onClick": {
                        "action": {
                          "actionMethodName": "doAssignTicket"
                        }
                      },
                      "text": "Assign to me"
                    }
                  }
                ]
              }
            ]
          }
        ]
      }
    ],
    "sender": {
      "avatarUrl": "https://www.example.com/images/chat-app-icon.png",
      "displayName": "Support Chat app",
      "name": "users/98765432109876543210",
      "type": "BOT"
    },
    "createTime": {
      "seconds": 1691187386,
      "nanos": 954319000
    },
    "retentionSettings": {
      "state": "PERMANENT"
    },
    "name": "spaces/AAAAAAAAAAA/messages/CCCCCCCCCCC",
    "thread": {
      "retentionSettings": {
        "state": "PERMANENT"
      },
      "name": "spaces/AAAAAAAAAAA/threads/BBBBBBBBBBB"
    },
    "messageHistoryState": "HISTORY_ON",
    "space": {
      "spaceThreadingState": "GROUPED_MESSAGES",
      "spaceType": "SPACE",
      "displayName": "Customer Support Superstars",
      "name": "spaces/AAAAAAAAAAA",
      "spaceHistoryState": "HISTORY_ON",
      "type": "ROOM",
      "threaded": true
    }
  },
  "user": {
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "displayName": "Izumi",
    "name": "users/12345678901234567890",
    "type": "HUMAN",
    "email": "izumi@example.com",
    "domainId": "ABCDEFG"
  },
  "space": {
    "spaceThreadingState": "GROUPED_MESSAGES",
    "spaceType": "SPACE",
    "displayName": "Customer Support Superstars",
    "name": "spaces/AAAAAAAAAAA",
    "spaceHistoryState": "HISTORY_ON",
    "type": "ROOM",
    "threaded": true
  }
}

קליקים על כרטיס לתיבות דו-שיח

כשמשתמש מנהל אינטראקציה עם תיבת דו-שיח, המטען הייעודי (payload) של אירוע האינטראקציה CARD_CLICKED כולל את השדות הנוספים האלה:

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

בדוגמה הבאה ל-JSON מוצג חלק מגוף הבקשה לאירוע אינטראקציה מסוג CARD_CLICKED. בדוגמה הבאה, המשתמש לחץ על לחצן בתיבת דו-שיח ששולח מידע לאפליקציית Chat:

{
  "type": "CARD_CLICKED",
  ...
  "isDialogEvent": true,
  "dialogEventType": "SUBMIT_DIALOG",
}

הודעת הבית של האפליקציה

אירוע האינטראקציה הזה מציין שמשתמש פתח צ'אט אישי עם אפליקציית Chat וקיבל הודעת דף בית מאפליקציית Chat.

בדוגמה הבאה ל-JSON מוצג גוף הבקשה לאירוע אינטראקציה עם APP_HOME:

{
  "chat": {
    "type": "APP_HOME",
    "user": {
      "name": "users/12345678901234567890",
      "type": "HUMAN",
      "email": "izumi@example.com",
      "domainId": "ABCDEFG"
    },
    "space": {
      "name": "spaces/AAAAAAAAAAA",
      "singleUserBotDm": true,
      "spaceType": "DIRECT_MESSAGE"
    }
  },
  "commonEventObject": {
    "invokedFunction": "onAppHome",
    "userLocale": "en",
    "hostApp": "CHAT"
  }
}

שליחת הטופס בהודעת הבית של האפליקציה

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

בדוגמה הבאה ל-JSON מוצג גוף הבקשה לאירוע אינטראקציה מסוג SUBMIT_FORM:

{
  "commonEventObject": {
    "userLocale": "en",
    "invokedFunction": "onSubmitFunction",
    "formInputs": {
      "username": {
        "": {
          "stringInputs": {
            "value": [
              "Ira"
            ]
          }
        }
      }
    },
    "hostApp": "CHAT"
  },
  "chat": {
    "type": "SUBMIT_FORM",
    "space": {
      "name": "spaces/AAAAAAAAAAA",
      "spaceType": "DIRECT_MESSAGE",
      "singleUserBotDm": true
    },
    "user": {
      "type": "HUMAN",
      "name": "123456789"
    }
  }
}

במדריכים הבאים מוסבר איך לעבד את המטען הייעודי (payloads) של אירועי אינטראקציה ולהחזיר תגובה: