مشترک شدن در رویدادهای Google Chat

این صفحه رویدادهای Chat را که برنامه Chat می‌تواند بااستفاده از Google Workspace Events API در آن‌ها مشترک شود شرح می‌دهد. پس‌از اینکه تصمیم گرفتید به چه نوع رویدادهایی نیاز دارید، اشتراکی ایجاد کنید تا دریافت رویدادها را از Chat شروع کنید.

علاوه‌بر مشترک شدن در رویدادها، می‌توانید با فراخوانی Google Chat API، رویدادها را جستجو کنید. فراخوانی Chat API به شما امکان می‌دهد رویدادها را به‌صورت دوره‌ای بازیابی کنید یا رویدادهایی را که ممکن است به‌دلیل قطعی از اشتراک ازدست داده باشید، جبران کنید. برای آشنایی با روش‌های دریافت و پاسخ دادن به رویدادهای Chat، به کار با رویدادهای Chat در اسناد Chat مراجعه کنید.

رویدادهای پشتیبانی‌شده Chat

اشتراک‌های Google Workspace به شما امکان می‌دهد رویدادهای مربوط به انواع تغییرات زیر را در Chat دریافت کنید:

منابعی که می‌توانید برای رویدادها پایش کنید

برای دریافت رویدادها، منبع Chat را برای نظارت مشخص می‌کنید، که به آن منبع هدف اشتراک می‌گویند.

Google Workspace Events API از منابع هدف زیر برای Chat پشتیبانی می‌کند:

منبع هدف قالب محدودیت‌ها
فاصله

//chat.googleapis.com/spaces/SPACE

که SPACE شناسه در نام منبع منبع Chat API space است. می‌توانید شناسه را از نشانی وب فضا یا بااستفاده از روش spaces.list() دریافت کنید.

کاربر Chat یا برنامه Chat که اشتراک را مجاز می‌کند باید ازطریق Google Workspace یا «حساب Google» خود عضو فضا باشد. پشتیبانی از:
همه فضاهای کاربر

//chat.googleapis.com/spaces/-

اشتراک فقط رویدادهای فضاهایی را دریافت می‌کند که کاربر ازطریق «حساب Google» یا Google Workspace خود عضو آن‌ها است. فقط از اصالت‌سنجی کاربر پشتیبانی می‌کند.
کاربر

//cloudidentity.googleapis.com/users/USER

که USER شناسه در نام منبع منبع Chat API user است. برای جزئیات، به شناسایی و مشخص کردن کاربران Google Chat مراجعه کنید.

اشتراک فقط رویدادهای مربوط به کاربری را دریافت می‌کند که اشتراک را مجاز کرده است. کاربر نمی‌تواند ازطرف کاربران دیگر اشتراکی را مجاز کند. فقط از اصالت‌سنجی کاربر پشتیبانی می‌کند.

مشتری

//admin.googleapis.com/customers/CUSTOMER

که CUSTOMER شناسه مشتری است. همچنین می‌توانید از نام مستعار my_customer برای دامنه مشتری برنامه Chat استفاده کنید.

اشتراک رویدادها را برای همه فضاها و کاربران تحت مدیریت دامنه مشتری دریافت می‌کند. فقط از اصالت‌سنجی برنامه با تأیید سرپرست پشتیبانی می‌کند.

انواع رویداد برای ایجاد اشتراک

وقتی اشتراکی ایجاد می‌کنید، از فیلد 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.message.v1.created

space.message

پیامی به‌روز شود.

google.workspace.chat.message.v1.updated

space.message

پیامی حذف شده است.

google.workspace.chat.message.v1.deleted

space.message

واکنشی ایجاد شده است.

google.workspace.chat.reaction.v1.created

space.message.reaction

واکنشی حذف شود.

google.workspace.chat.reaction.v1.deleted

space.message.reaction

عضوی به فضا اضافه می‌شود.

google.workspace.chat.membership.v1.created

space.membership

عضوی در فضا به‌روز می‌شود.

google.workspace.chat.membership.v1.updated

space.membership

عضوی از فضا برداشته شود.

google.workspace.chat.membership.v1.deleted

space.membership

فضا به‌روز می‌شود.

google.workspace.chat.space.v1.updated

space

فضا حذف می‌شود.

google.workspace.chat.space.v1.deleted

space

اشتراک‌ها به کاربران  
کاربر عضو فضا می‌شود.

همه اعضای جدید رویدادها را راه‌اندازی نمی‌کنند. برای جزئیات، محدودیت‌ها را ببینید

google.workspace.chat.membership.v1.created

space.membership

عضویت کاربر در فضا به‌روز شده است.

google.workspace.chat.membership.v1.updated

space.membership

کاربر به‌عنوان عضو مستقیم فضا برداشته می‌شود.

google.workspace.chat.membership.v1.deleted

space.membership

وضعیت خوانده شدن فضا برای کاربر به‌روز می‌شود.

google.workspace.chat.spaceReadState.v1.updated

spaceReadState

وضعیت خوانده شدن رشته کاربر به‌روزرسانی شده است.

google.workspace.chat.threadReadState.v1.updated

threadReadState

اشتراک‌ها به مشتریان  
رویدادی برای هر فضا، پیام، واکنش، عضویت، یا وضعیت خواندن کاربر در سازمان Google Workspace شما رخ دهد.

از همه انواع رویدادهای فهرست‌شده برای اشتراک‌های فضا و کاربر پشتیبانی می‌کند.

به نوع رویداد بستگی دارد (برای مثال، space، space.message، space.membership، یا spaceReadState).

انواع رویداد دسته‌ای (فقط خروجی)

علاوه‌بر دریافت انواع رویدادهایی که در آن‌ها مشترک می‌شوید، برنامه Chat شما ممکن است رویدادهای دسته‌ای را نیز دریافت کند. رویداد دسته‌ای رویدادی است که نشان‌دهنده رویدادهای زیادی از یک نوع است که در مدت‌زمان کوتاهی رخ می‌دهند. بار داده رویداد دسته‌ای حاوی فهرستی از همه منابع تغییریافته است.

برای مثال، اگر کاربری ۲۰ کاربر را به‌طور هم‌زمان به فضایی اضافه کند، برنامه Chat شما ممکن است رویداد دسته‌ای (google.workspace.chat.membership.v1.batchCreated) دریافت کند. بار داده رویداد حاوی فهرستی از همه منابع جدید Membership است که وقتی کاربر اعضا را به فضا اضافه کرد ایجاد شده‌اند.

برای هر نوع رویدادی که مشترک می‌شوید، رویداد دسته‌ای دریافت می‌کنید، بنابراین هنگام ایجاد اشتراک نیازی به مشخص کردن رویدادهای دسته‌ای ندارید. برای مثال، اگر در واکنش‌های جدید (google.workspace.chat.reaction.v1.created) مشترک شوید، برنامه Chat شما به‌طور خودکار برای دریافت رویدادهای واکنش دسته‌ای (google.workspace.chat.reaction.v1.batchCreated) پیکربندی می‌شود.

جدول زیر رویدادهای دسته‌ای احتمالی را برای اشتراک نشان می‌دهد:

نوع رویداد دسته‌ای قالب
چند پیام پست شده است.

google.workspace.chat.message.v1.batchCreated

چندین پیام به‌روز شد.

google.workspace.chat.message.v1.batchUpdated

چند پیام حذف شده است.

google.workspace.chat.message.v1.batchDeleted

چندین واکنش ایجاد شده است.

google.workspace.chat.reaction.v1.batchCreated

چند واکنش حذف شد.

google.workspace.chat.reaction.v1.batchDeleted

چند عضو به فضای مشترک‌شده اضافه شده‌اند، یا کاربر مشترک‌شده به چند فضا اضافه شده است.

google.workspace.chat.membership.v1.batchCreated

چند عضویت در فضای مشترک‌شده یا برای کاربر مشترک‌شده به‌روزرسانی می‌شود.

google.workspace.chat.membership.v1.batchUpdated

چند عضو از فضای مشترک‌شده برداشته شده‌اند، یا کاربر مشترک‌شده از چند فضا برداشته شده است.

google.workspace.chat.membership.v1.batchDeleted

فضا چند به‌روزرسانی دارد.

google.workspace.chat.space.v1.batchUpdated

چند وضعیت خوانده شدن فضا برای کاربر مشترک‌شده به‌روز می‌شود.

google.workspace.chat.spaceReadState.v1.batchUpdated

چند وضعیت خواندن رشته برای کاربر مشترک‌شده به‌روزرسانی شده است.

google.workspace.chat.threadReadState.v1.batchUpdated

داده‌های رویداد

این بخش داده‌های رویداد و نمونه بار داده برای رویدادها را در Chat شرح می‌دهد.

وقتی اشتراک Google Workspace شما رویدادی را از Chat دریافت می‌کند، فیلد data حاوی بار مفید رویداد است. این بار داده حاوی اطلاعاتی درباره منبع Google Workspace است که تغییر کرده است. برای مثال، اگر در رویدادهای عضویت در فضایی مشترک شده باشید، بار داده برای این رویدادها حاوی اطلاعاتی درباره spaces.membership منبعی است که تغییر کرده است.

داده‌های منبع در بار داده رویداد

وقتی اشتراکی ایجاد می‌کنید، می‌توانید مشخص کنید که می‌خواهید پایه‌بار شامل جزئیات مربوط به منبع باشد یا فقط نام منبع را دربرگیرد. برای مثال، اگر می‌خواهید رویدادهای مربوط به اعضا را در فضای Chat دریافت کنید، مشخص کنید که کدام فیلدهای منبع عضویت را می‌خواهید در بار داده رویداد دریافت کنید.

جدول زیر نمونه‌هایی از بار JSON برای اشتراک در فضای Chat spaces/AAAABBBBBB ارائه می‌دهد. برای هر رویدادی که اشتراک دریافت می‌کند، بار مفید در فیلد data رویداد نشان داده می‌شود:

نمونه نوع رویداد پایه‌بار JSON

کاربری پیامی در فضا پست می‌کند که می‌گوید «سلام دنیا».

google.workspace.chat.message.v1.created

شامل داده‌های منبع:

{
    "message":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID",
        "sender":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "createTime": "2023-09-07T21:37:36.260127Z",
        "text": "Hello world",
        "thread":
        {
            "name": "spaces/SPACE_ID/threads/THREAD_ID"
        },
        "space":
        {
            "name": "spaces/SPACE_ID"
        },
        "argumentText": "Hello world"
    }
}
      

داده‌های منبع را مستثنی می‌کند:

{
    "message":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID"
    }
}
      
کاربری مدیر فضا می‌شود.

google.workspace.chat.membership.v1.updated

شامل داده‌های منبع:

{
    "membership":
    {
        "name": "spaces/SPACE_ID/members/MEMBER_ID",
        "state": "JOINED",
        "member":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "createTime": "1970-01-01T00:00:00Z",
        "role": "ROLE_MANAGER"
    }
}
      

داده‌های منبع را مستثنی می‌کند:

{
    "membership":
    {
        "name": "spaces/SPACE_ID/members/MEMBER_ID"
    }
}
      
کاربری شرح فضا را به «تیم فروش Cymbal Labs» به‌روز می‌کند. google.workspace.chat.space.v1.updated

شامل داده‌های منبع:

{
    "space":
    {
        "name": "spaces/SPACE_ID",
        "displayName": "Cymbal Sales",
        "spaceThreadingState": "THREADED_MESSAGES",
        "spaceType": "SPACE",
        "spaceDetails":
        {
            "description": "Sales team for Cymbal Labs."
        },
        "spaceHistoryState": "HISTORY_ON"
    }
}
      

داده‌های منبع را مستثنی می‌کند:

{
    "space":
    {
        "name": "spaces/SPACE_ID"
    }
}
      
دو کاربر Chat به‌طور هم‌زمان به فضا اضافه شدند. google.workspace.chat.membership.v1.batchCreated

شامل داده‌های منبع:

{
    "memberships": [
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID",
            "state": "JOINED",
            "member":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "createTime": "1970-01-01T00:00:00Z",
            "role": "ROLE_MEMBER"
          }
        },
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID",
            "state": "JOINED",
            "member":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "createTime": "1970-01-01T00:00:00Z",
            "role": "ROLE_MEMBER"
          }
        }
    ]
}
      

داده‌های منبع را مستثنی می‌کند:

{
    "memberships": [
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID"
          }
        },
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID"
          }
        }
    ]
}
      
کاربری با اموجی 😊 به پیامی واکنش نشان می‌دهد. google.workspace.chat.reaction.v1.created

شامل داده‌های منبع:

{
    "reaction":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
        "user":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "emoji":
        {
            "unicode": "😊"
        }
    }
}
      

داده‌های منبع را مستثنی می‌کند:

{
    "reaction":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID"
    }
}
      
کاربران با اموجی 😊 و اموجی 😸 به پیام واکنش نشان می‌دهند. google.workspace.chat.reaction.v1.batchCreated

شامل داده‌های منبع:

{
    "reactions": [
        {
          "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
            "user":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "emoji":
            {
                "unicode": "😊"
            }
          }
        },
        {
          "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
            "user":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "emoji":
            {
                "unicode": "😸"
            }
          }
        }
    ]
}
      

داده‌های منبع را مستثنی می‌کند:

{
    "reactions": [
      {
        "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID"
        },
        "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
        }
      }
    ]
}
      
کاربری از فضای خوانده‌نشده‌ای بازدید می‌کند که وضعیت خوانده شدن فضای او را به‌روز می‌کند. google.workspace.chat.spaceReadState.v1.updated

شامل داده‌های منبع:

{
  "spaceReadState": {
    "name": "users/USER_ID/spaces/SPACE_ID/spaceReadState",
    "lastReadTime": "2026-04-14T14:03:46.431760Z"
  }
}
      

داده‌های منبع را مستثنی می‌کند:

{
  "spaceReadState": {
    "name": "users/USER_ID/spaces/SPACE_ID/spaceReadState"
  }
}
      
کاربری پیامی را در رشته‌ای می‌خواند که وضعیت خوانده شدن رشته او را به‌روز می‌کند. google.workspace.chat.threadReadState.v1.updated

شامل داده‌های منبع:

{
  "threadReadState": {
    "name": "users/USER_ID/spaces/SPACE_ID/threads/THREAD_ID/threadReadState",
    "lastReadTime": "2026-04-14T14:03:46.431760Z"
  }
}
      

داده‌های منبع را مستثنی می‌کند:

{
  "threadReadState": {
    "name": "users/USER_ID/spaces/SPACE_ID/threads/THREAD_ID/threadReadState"
  }
}
      
کاربری در 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}