این صفحه رویدادهای Chat را که برنامه Chat میتواند بااستفاده از Google Workspace Events API در آنها مشترک شود شرح میدهد. پساز اینکه تصمیم گرفتید به چه نوع رویدادهایی نیاز دارید، اشتراکی ایجاد کنید تا دریافت رویدادها را از Chat شروع کنید.
علاوهبر مشترک شدن در رویدادها، میتوانید با فراخوانی Google Chat API، رویدادها را جستجو کنید. فراخوانی Chat API به شما امکان میدهد رویدادها را بهصورت دورهای بازیابی کنید یا رویدادهایی را که ممکن است بهدلیل قطعی از اشتراک ازدست داده باشید، جبران کنید. برای آشنایی با روشهای دریافت و پاسخ دادن به رویدادهای Chat، به کار با رویدادهای Chat در اسناد Chat مراجعه کنید.
رویدادهای پشتیبانیشده Chat
اشتراکهای Google Workspace به شما امکان میدهد رویدادهای مربوط به انواع تغییرات زیر را در Chat دریافت کنید:
- پیامهای جدید، بهروزشده، یا حذفشده در فضا.
- واکنشهای جدید یا حذفشده به پیام.
- اعضای جدید، بهروزشده، یا برداشتهشده در فضا.
- تغییرات در فضایی که در آن مشترک هستید، مانند نام یا شرح بهروزشده فضا.
- تغییرات در دردسترس بودن کاربر.
- تغییرات در spaceReadState یا threadReadState کاربر.
منابعی که میتوانید برای رویدادها پایش کنید
برای دریافت رویدادها، منبع Chat را برای نظارت مشخص میکنید، که به آن منبع هدف اشتراک میگویند.
Google Workspace Events API از منابع هدف زیر برای Chat پشتیبانی میکند:
| منبع هدف | قالب | محدودیتها |
|---|---|---|
| فاصله |
که SPACE شناسه در
نام منبع منبع Chat API |
کاربر Chat یا برنامه Chat که اشتراک را مجاز میکند باید ازطریق Google Workspace یا «حساب Google» خود عضو فضا باشد. پشتیبانی از: |
| همه فضاهای کاربر |
|
اشتراک فقط رویدادهای فضاهایی را دریافت میکند که کاربر ازطریق «حساب Google» یا Google Workspace خود عضو آنها است. فقط از اصالتسنجی کاربر پشتیبانی میکند. |
| کاربر |
که USER شناسه در
نام منبع منبع Chat API |
اشتراک فقط رویدادهای مربوط به کاربری را دریافت میکند که اشتراک را مجاز کرده است. کاربر نمیتواند ازطرف کاربران دیگر اشتراکی را مجاز کند. فقط از اصالتسنجی کاربر پشتیبانی میکند. |
| مشتری |
که CUSTOMER شناسه مشتری است. همچنین میتوانید از نام مستعار |
اشتراک رویدادها را برای همه فضاها و کاربران تحت مدیریت دامنه مشتری دریافت میکند. فقط از اصالتسنجی برنامه با تأیید سرپرست پشتیبانی میکند. |
انواع رویداد برای ایجاد اشتراک
وقتی اشتراکی ایجاد میکنید، از فیلد
eventTypes[]
برای مشخص کردن نوع رویدادهایی که میخواهید دریافت کنید استفاده کنید. انواع رویدادها
مطابق با مشخصات CloudEvents قالببندی میشوند، مانند
google.workspace.APPLICATION.RESOURCE.VERSION.ACTION.
برای مثال، برای دریافت رویدادهای مربوط به کاربرانی که به فضای Chat میپیوندند، فضا را بهعنوان منبع هدف و نوع رویداد را بهعنوان google.workspace.chat.membership.v1.created مشخص کنید. برای دریافت رویدادهای مربوط به پیوستن کاربر مشخصی به هر فضا، کاربر را بهعنوان منبع هدف و نوع رویداد را بهعنوان google.workspace.chat.membership.v1.created مشخص کنید. برای کسب اطلاعات بیشتر درباره نحوه عملکرد رویدادها، به ساختار رویدادهای Google Workspace مراجعه کنید.
جدول زیر نشان میدهد که کدام نوع رویداد برای اشتراکهای فضاها و اشتراکهای کاربران پشتیبانی میشود. برای آشنایی با استثناهای مربوط به مواردی که رویداد را راهاندازی میکند، به محدودیتها مراجعه کنید.
| نوع رویداد | قالب | دادههای منبع | ||
|---|---|---|---|---|
| اشتراک در فضاها | ||||
| پیامی پست میشود. |
|
|
||
| پیامی بهروز شود. |
|
|
||
| پیامی حذف شده است. |
|
|
||
| واکنشی ایجاد شده است. |
|
|
||
| واکنشی حذف شود. |
|
|
||
| عضوی به فضا اضافه میشود. |
|
|
||
| عضوی در فضا بهروز میشود. |
|
|
||
| عضوی از فضا برداشته شود. |
|
|
||
| فضا بهروز میشود. |
|
|
||
| فضا حذف میشود. |
|
|
||
| اشتراکها به کاربران | ||||
| کاربر عضو فضا میشود.
همه اعضای جدید رویدادها را راهاندازی نمیکنند. برای جزئیات، محدودیتها را ببینید |
|
|
||
| عضویت کاربر در فضا بهروز شده است. |
|
|
||
| کاربر بهعنوان عضو مستقیم فضا برداشته میشود. |
|
|
||
| وضعیت خوانده شدن فضا برای کاربر بهروز میشود. |
|
|
||
| وضعیت خوانده شدن رشته کاربر بهروزرسانی شده است. |
|
|
||
| اشتراکها به مشتریان | ||||
| رویدادی برای هر فضا، پیام، واکنش، عضویت، یا وضعیت خواندن کاربر در سازمان Google Workspace شما رخ دهد. |
از همه انواع رویدادهای فهرستشده برای اشتراکهای فضا و کاربر پشتیبانی میکند. |
به نوع رویداد بستگی دارد (برای مثال، |
||
انواع رویداد دستهای (فقط خروجی)
علاوهبر دریافت انواع رویدادهایی که در آنها مشترک میشوید، برنامه Chat شما ممکن است رویدادهای دستهای را نیز دریافت کند. رویداد دستهای رویدادی است که نشاندهنده رویدادهای زیادی از یک نوع است که در مدتزمان کوتاهی رخ میدهند. بار داده رویداد دستهای حاوی فهرستی از همه منابع تغییریافته است.
برای مثال، اگر کاربری ۲۰ کاربر را بهطور همزمان به فضایی اضافه کند،
برنامه Chat شما ممکن است رویداد دستهای
(google.workspace.chat.membership.v1.batchCreated) دریافت کند. بار داده رویداد حاوی
فهرستی از همه منابع جدید Membership است که وقتی کاربر
اعضا را به فضا اضافه کرد ایجاد شدهاند.
برای هر نوع رویدادی که مشترک میشوید، رویداد دستهای دریافت میکنید، بنابراین
هنگام ایجاد اشتراک نیازی به مشخص کردن رویدادهای دستهای ندارید. برای
مثال، اگر در واکنشهای جدید
(google.workspace.chat.reaction.v1.created) مشترک شوید،
برنامه Chat شما بهطور خودکار برای دریافت رویدادهای واکنش
دستهای (google.workspace.chat.reaction.v1.batchCreated) پیکربندی میشود.
جدول زیر رویدادهای دستهای احتمالی را برای اشتراک نشان میدهد:
| نوع رویداد دستهای | قالب |
|---|---|
| چند پیام پست شده است. |
|
| چندین پیام بهروز شد. |
|
| چند پیام حذف شده است. |
|
| چندین واکنش ایجاد شده است. |
|
| چند واکنش حذف شد. |
|
| چند عضو به فضای مشترکشده اضافه شدهاند، یا کاربر مشترکشده به چند فضا اضافه شده است. |
|
| چند عضویت در فضای مشترکشده یا برای کاربر مشترکشده بهروزرسانی میشود. |
|
| چند عضو از فضای مشترکشده برداشته شدهاند، یا کاربر مشترکشده از چند فضا برداشته شده است. |
|
| فضا چند بهروزرسانی دارد. |
|
| چند وضعیت خوانده شدن فضا برای کاربر مشترکشده بهروز میشود. |
|
| چند وضعیت خواندن رشته برای کاربر مشترکشده بهروزرسانی شده است. |
|
دادههای رویداد
این بخش دادههای رویداد و نمونه بار داده برای رویدادها را در Chat شرح میدهد.
وقتی اشتراک Google Workspace شما رویدادی را از Chat دریافت میکند، فیلد data حاوی بار مفید رویداد است. این بار داده حاوی اطلاعاتی درباره
منبع Google Workspace است که تغییر کرده است. برای مثال، اگر
در رویدادهای عضویت در فضایی مشترک شده باشید، بار داده برای این رویدادها
حاوی اطلاعاتی درباره
spaces.membership
منبعی است که تغییر کرده است.
دادههای منبع در بار داده رویداد
وقتی اشتراکی ایجاد میکنید، میتوانید مشخص کنید که میخواهید پایهبار شامل جزئیات مربوط به منبع باشد یا فقط نام منبع را دربرگیرد. برای مثال، اگر میخواهید رویدادهای مربوط به اعضا را در فضای Chat دریافت کنید، مشخص کنید که کدام فیلدهای منبع عضویت را میخواهید در بار داده رویداد دریافت کنید.
جدول زیر نمونههایی از بار JSON برای اشتراک در
فضای Chat spaces/AAAABBBBBB ارائه میدهد. برای هر رویدادی که اشتراک دریافت میکند، بار مفید در فیلد data رویداد نشان داده میشود:
| نمونه | نوع رویداد | پایهبار JSON |
|---|---|---|
کاربری پیامی در فضا پست میکند که میگوید «سلام دنیا». |
|
شامل دادههای منبع:
{
"message":
{
"name": "spaces/دادههای منبع را مستثنی میکند:
{
"message":
{
"name": "spaces/ |
| کاربری مدیر فضا میشود. |
|
شامل دادههای منبع:
{
"membership":
{
"name": "spaces/دادههای منبع را مستثنی میکند:
{
"membership":
{
"name": "spaces/ |
| کاربری شرح فضا را به «تیم فروش Cymbal Labs» بهروز میکند. | google.workspace.chat.space.v1.updated |
شامل دادههای منبع:
{
"space":
{
"name": "spaces/دادههای منبع را مستثنی میکند:
{
"space":
{
"name": "spaces/ |
| دو کاربر Chat بهطور همزمان به فضا اضافه شدند. | google.workspace.chat.membership.v1.batchCreated |
شامل دادههای منبع:
{
"memberships": [
{
"membership": {
"name": "spaces/دادههای منبع را مستثنی میکند:
{
"memberships": [
{
"membership": {
"name": "spaces/ |
| کاربری با اموجی 😊 به پیامی واکنش نشان میدهد. | google.workspace.chat.reaction.v1.created |
شامل دادههای منبع:
{
"reaction":
{
"name": "spaces/دادههای منبع را مستثنی میکند:
{
"reaction":
{
"name": "spaces/ |
| کاربران با اموجی 😊 و اموجی 😸 به پیام واکنش نشان میدهند. | google.workspace.chat.reaction.v1.batchCreated |
شامل دادههای منبع:
{
"reactions": [
{
"reaction": {
"name": "spaces/دادههای منبع را مستثنی میکند:
{
"reactions": [
{
"reaction": {
"name": "spaces/ |
| کاربری از فضای خواندهنشدهای بازدید میکند که وضعیت خوانده شدن فضای او را بهروز میکند. | google.workspace.chat.spaceReadState.v1.updated |
شامل دادههای منبع:
{
"spaceReadState": {
"name": "users/دادههای منبع را مستثنی میکند:
{
"spaceReadState": {
"name": "users/ |
| کاربری پیامی را در رشتهای میخواند که وضعیت خوانده شدن رشته او را بهروز میکند. | google.workspace.chat.threadReadState.v1.updated |
شامل دادههای منبع:
{
"threadReadState": {
"name": "users/دادههای منبع را مستثنی میکند:
{
"threadReadState": {
"name": "users/ |
| کاربری در Chat دردسترس قرار میگیرد. | google.workspace.chat.availability.v1.updated |
شامل دادههای منبع:
{
"availability":
{
"name": "users/USER_ID/availability",
"state": "ACTIVE"
}
}
دادههای منبع را مستثنی میکند:
{
"availability":
{
"name": "users/USER_ID/availability",
}
}
|
| کاربری در Chat غیرفعال میشود. | google.workspace.chat.availability.v1.updated |
شامل دادههای منبع:
{
"availability":
{
"name": "users/USER_ID/availability",
"state": "IDLE",
}
}
دادههای منبع را مستثنی میکند:
{
"availability":
{
"name": "users/USER_ID/availability",
}
}
|
کاربری وضعیت دردسترس بودنش را در Chat روی Away تنظیم میکند. |
google.workspace.chat.availability.v1.updated |
شامل دادههای منبع:
{
"availability":
{
"name": "users/USER_ID/availability",
"state": "AWAY",
}
}
دادههای منبع را مستثنی میکند:
{
"availability":
{
"name": "users/USER_ID/availability",
}
}
|
کاربری وضعیت دردسترس بودنش را در Chat روی Do not disturb تنظیم میکند. |
google.workspace.chat.availability.v1.updated |
شامل دادههای منبع:
{
"availability":
{
"name": "users/USER_ID/availability",
"state": "DO_NOT_DISTURB",
"doNotDisturbMetadata": {
"expirationTime": "2026-03-24T18:36:31.337Z"
}
}
}
دادههای منبع را مستثنی میکند:
{
"availability":
{
"name": "users/USER_ID/availability",
}
}
|
| کاربری وضعیت سفارشی در Chat تنظیم میکند. | google.workspace.chat.availability.v1.updated |
شامل دادههای منبع:
{
"availability":
{
"name": "users/USER_ID/availability",
"state": "ACTIVE",
"customStatus": {
"text": "Be right back",
"emoji": {
"unicode": "👟"
},
"expireTime": "2026-03-24T18:38:05.583655Z"
}
}
}
دادههای منبع را مستثنی میکند:
{
"availability":
{
"name": "users/USER_ID/availability",
}
}
|
محدودیتها و رفتارهای تحویل
محدودیتهای عمومی
- برای دریافت رویدادهای عضویت، کاربر یا برنامه Chat باید عضو مستقیم فضا باشد. اگر بهطور غیرمستقیم ازطریق «گروه Google» به فضایی اضافه، بهروزرسانی، یا برداشته شده باشند، اشتراک آن رویدادهای عضویت را دریافت نمیکند. برای درک نحوه عملکرد عضویت در «گروه Google»، افزودن «گروه Google» به فضا را ببینید.
اشتراکهای کاربر
-
برای اشتراکهای کاربران، رویدادهای مربوط به اعضای جدید در پیامهای مستقیم یا گپهای گروهی بینام (
google.workspace.chat.membership.v1.created)، فقط پساز پست شدن اولین پیام راهاندازی میشوند.
اشتراکهای مشتری
برای اشتراکهای مشتری، محدودیتهای زیر اعمال میشود:
- سازمان Google Workspace باید حداقل یک پروانه «واحد نگهداری موجودی» Enterprise داشته باشد.
- برنامه Chat فقط میتواند یک اشتراک مشتری برای سازمان Google Workspace مشخص ایجاد کند. یک سازمان Google Workspace میتواند درمجموع حداکثر پنج اشتراک مشتری (ایجادشده توسط برنامههای Chat مختلف) داشته باشد.
برای اشتراکهای مشتری، تحویل رویداد از این قوانین کلی پیروی میکند:
- رویدادهای فضا: فقط درصورتی ارسال میشود که رویداد در فضایی که توسط سازمان Google Workspace شما مدیریت میشود رخ دهد.
- رویدادهای کاربر: فقط درصورتی ارسال میشود که رویداد برای کاربری اتفاق بیفتد که به سازمان Google Workspace شما تعلق دارد.
تنها استثنای این قوانین برای رویدادهای عضویت است. اشتراکتان میتواند رویدادهای عضویت را هم از فضاهای تحت مدیریت سازمانتان و هم از فضاهای تحت مدیریت سازمانهای خارجی دریافت کند، اما نحوه تحویل آنها به این بستگی دارد که کدام سازمان فضا را مدیریت میکند:
فضاهایی که توسط سازمان Google Workspace شما مدیریت میشود
اگر تغییری در عضویت در فضایی که توسط سازمان Google Workspace مدیریت میشود رخ دهد، بهعنوان رویداد فضا ارائه میشود.
نام منبع رویداد فضا از قالب زیر استفاده میکند:
spaces/{spaceId}/spaceEvents/{spaceEventId}
فضاهایی که توسط سازمانهای خارجی مدیریت میشوند
اگر عضویت کاربری که توسط سازمان Google Workspace شما مدیریت میشود در فضایی که توسط سازمان خارجی مدیریت میشود (برای مثال، فضای خارجی نامگذاریشده یا پیام مستقیمی که توسط کاربر خارجی ایجاد شده است) تغییر کند، اشتراک شما این رویداد را بهعنوان رویداد کاربر دریافت میکند.
نام منبع رویداد کاربر از قالب زیر استفاده میکند:
users/{userId}/userEvents/{userEventId}
موضوعات مرتبط
- ساختار رویدادهای Google Workspace
- انتخاب کردن دامنههای OAuth
- ایجاد اشتراک برای دریافت رویدادهای Chat