בדף הזה מתוארים הסוגים של אירועי האינטראקציה שאפליקציית 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 לכל אחד מסוגי האירועים הבאים:
- הודעה (
MESSAGE
) - התווסף למרחב המשותף (
ADDED_TO_SPACE
) - הוסר מהמרחב המשותף (
REMOVED_FROM_SPACE
) - לחצו על הכרטיס (
CARD_CLICKED
)
מסר
אירוע האינטראקציה הזה מייצג מתי מישהו שולח הודעה לאפליקציית 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) של אירועי אינטראקציה ולהחזיר תגובה:
- שליחת הודעה לגבי כרטיס
- שליחה של הודעת טקסט
- שליחת הודעת כרטיס דף הבית של אפליקציה
- פתיחה של תיבות דו-שיח אינטראקטיביות
- תצוגה מקדימה של קישורים
- איך קוראים נתוני טפסים שמשתמשים מזינים בכרטיסים
- איך מגדירים פקודות שאפשר להשתמש בהן דרך שורת הפקודות