این صفحه انواع رویدادهای تعاملی را که برنامه Google Chat شما میتواند از Google Chat دریافت کند، توضیح میدهد.
برای پیکربندی برنامه چت برای دریافت رویدادهای تعامل، به دریافت و پاسخ به تعاملات با برنامه چت خود مراجعه کنید.
قالبهای رویدادهای تعاملی
کاربران می توانند به طرق مختلف با برنامه های چت تعامل داشته باشند. برای هر نوع تعامل، Google Chat نوع متفاوتی از رویداد تعاملی را ارسال میکند:
- پیام: یک کاربر به برنامه چت شما پیامی ارسال می کند یا برنامه چت شما را در یک فاصله فراخوانی می کند.
- به فضا اضافه شد: کاربر برنامه چت شما را به یک فضا اضافه می کند.
- حذف شده از فضا: یک کاربر برنامه چت شما را از یک فضا حذف می کند.
- کارت کلیک شده: کاربر روی کارت تعاملی یا گفتگوی ارسال شده توسط برنامه چت شما کلیک می کند.
- پیام صفحه اصلی برنامه : کاربر یک پیام مستقیم را با یک برنامه چت باز می کند و یک پیام اصلی برنامه چت را دریافت می کند.
- فرم ارسال : کاربر اطلاعات فرم را از طریق پیام اصلی برنامه چت ارسال می کند
هر بار که کاربر با برنامه چت شما تعامل می کند، Google Chat یک رویداد تعاملی را با یک بدنه درخواست ارسال می کند که یک بار JSON است که تعامل را نشان می دهد. این بار رویداد حاوی عناصری است که برای همه انواع رویدادهای تعامل مشترک هستند و همچنین عناصری که مختص نوع رویداد هستند.
برای کسب اطلاعات بیشتر در مورد فیلدها در یک رویداد تعاملی، به مستندات مرجع Event
Google Chat API مراجعه کنید.
زمینه های مشترک
فیلدهای زیر همیشه در محموله یک رویداد تعاملی ارائه می شوند:
رشته | شرح |
---|---|
type | نوع رویدادی که برنامه گپ دریافت میکند، مانند MESSAGE یا ADDED_TO_SPACE . |
eventTime | مهر زمانی که نشان دهنده زمان ارسال رویداد است. |
common | نشان دهنده اطلاعات مربوط به مشتری کاربر، مانند محل یا پلت فرم است. |
فیلدها بر اساس نوع رویداد تعامل
بسته به نوع رویداد، payload ممکن است حاوی فیلدهای اضافی زیر باشد:
رشته | شرح | نوع رویداد |
---|---|---|
message | پیام مربوط به مراسم | MESSAGE ، ADDED_TO_SPACE ، CARD_CLICKED . |
space | فضای مربوط به رویداد. | MESSAGE ، ADDED_TO_SPACE ، REMOVED_FROM_SPACE ، CARD_CLICKED . |
user | کاربر مرتبط با رویداد. کاربر همیشه یک شخص است (نه یک برنامه چت). | MESSAGE ، ADDED_TO_SPACE ، REMOVED_FROM_SPACE ، CARD_CLICKED . |
action | عملکردی که کاربر هنگام کلیک کردن روی کارت تعاملی یا گفتگو فعال می کند. | CARD_CLICKED . |
نمونه بارهای رویداد
این بخش آنچه را که یک رویداد تعاملی را راهاندازی میکند توضیح میدهد و یک نمونه بارگیری JSON برای هر یک از انواع رویداد زیر ارائه میکند:
- پیام (
MESSAGE
) - به فضا اضافه شد (
ADDED_TO_SPACE
) - از فضا حذف شد (
REMOVED_FROM_SPACE
) - کارت کلیک شده (
CARD_CLICKED
)
پیام
این رویداد تعامل نشان دهنده زمانی است که شخصی پیامی را به برنامه چت ارسال می کند، مانند:
- هر پیامی در فضای پیام مستقیم (DM) با برنامه چت.
- پیامی در فضای چند نفره که در آن شخصی @ از برنامه 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"
}
}
به فضا اضافه شد
این رویداد تعاملی نشان میدهد که برنامه چت شما به یک فضا اضافه شده است. برنامه ها معمولاً با ارسال نوعی پیام خوش آمدگویی در یک رشته جدید در فضا به این رویداد تعامل پاسخ می دهند.
مثال JSON زیر بدنه درخواست یک رویداد تعاملی ADDED_TO_SPACE
را هنگامی که کاربر یک برنامه چت را به یک فضا اضافه میکند نشان میدهد:
{
"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 برنامه چت شما را برای کاربری در سازمان خود نصب کرده است.
مدیران فقط میتوانند یک برنامه چت را برای پیامهای مستقیم بین برنامه چت و کاربر نصب کنند. برنامه نصب شده در پنل پیام مستقیم کاربران ظاهر می شود. وقتی سرپرستان برنامههای چت را نصب میکنند، کاربران نمیتوانند آنها را حذف نصب کنند. برای آشنایی با برنامههای گپ نصبشده توسط سرپرستان، به اسناد راهنمای Google Workspace Admin مراجعه کنید، برنامههای Marketplace را در دامنه خود نصب کنید .
مثال JSON زیر بدنه درخواست یک رویداد تعاملی ADDED_TO_SPACE
را هنگامی که یک سرپرست Google Workspace یک برنامه چت را برای یک کاربر نصب میکند، نشان میدهد. از آنجایی که یک سرپرست برنامه 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"
}
}
از فضا حذف شد
این رویداد تعاملی نشان میدهد که برنامه چت شما از یک فضا حذف شده است. برنامههای گپ با پیام به این رویداد پاسخ نمیدهند، زیرا قبلاً حذف شدهاند.
مثال JSON زیر بدنه درخواست یک رویداد تعاملی REMOVED_FROM_SPACE
را هنگامی که کاربر یک برنامه چت را از یک فضا حذف میکند نشان میدهد:
{
"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 رویداد تعاملی 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 رویداد تعاملی 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
}
}
کلیک کارت برای گفتگوها
هنگامی که کاربر با یک گفتگو تعامل می کند، بارگذاری برای رویداد تعامل CARD_CLICKED
شامل فیلدهای اضافی زیر است:
-
isDialogEvent
: برای رویدادهای تعاملی که شامل دیالوگ ها می شوند، رویtrue
تنظیم کنید. -
DialogEventType
: نوع تعامل با دیالوگ، از جمله اگر کاربر یک گفتگو را باز کند، ارسال کند یا لغو کند.
مثال JSON زیر بخشی از بدنه درخواست را برای یک رویداد تعاملی CARD_CLICKED
نشان میدهد. در این مثال، کاربر روی دکمه ای در یک گفتگو کلیک کرده است که اطلاعات را به برنامه چت ارسال می کند:
{
"type": "CARD_CLICKED",
...
"isDialogEvent": true,
"dialogEventType": "SUBMIT_DIALOG",
}
پیام خانه برنامه
این رویداد تعاملی نشان میدهد که کاربر یک پیام مستقیم با برنامه چت شما باز کرده و یک پیام اصلی برنامه چت دریافت کرده است.
مثال 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"
}
}
فرم را در یک پیام خانه برنامه ارسال کنید
این رویداد تعاملی نشان میدهد که کاربر اطلاعات فرم را از طریق پیام اصلی برنامه چت ارسال کرده است.
مثال 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"
}
}
}
مطالب مرتبط
برای یادگیری نحوه پردازش محموله های رویدادهای تعامل و بازگرداندن پاسخ، به راهنماهای زیر مراجعه کنید:
- پیام کارت ارسال کنید
- پیامک بفرستید
- ارسال پیام کارت خانه برنامه
- گفتگوهای تعاملی را باز کنید
- پیش نمایش لینک ها
- اطلاعات ورودی فرم توسط کاربران را روی کارت بخوانید
- دستورات اسلش را تنظیم کنید