در رویدادهای چت Google مشترک شوید

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

علاوه بر اشتراک در رویدادها، می‌توانید با فراخوانی API چت گوگل، رویدادها را جستجو کنید. فراخوانی API چت به شما امکان می‌دهد رویدادها را به صورت دوره‌ای بازیابی کنید، یا رویدادهایی را که ممکن است به دلیل قطعی اشتراک از دست داده باشید، دریافت کنید. برای کسب اطلاعات در مورد روش‌های دریافت و پاسخ به رویدادهای چت، به بخش «کار با رویدادها از چت» در مستندات چت مراجعه کنید.

رویدادهای چت پشتیبانی شده

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

• پیام‌های جدید، به‌روزرسانی‌شده یا حذف‌شده در این فضا.
• واکنش‌های جدید یا حذف‌شده به یک پیام.
• اعضای جدید، به‌روزرسانی‌شده یا حذف‌شده در این فضا.
• تغییرات در فضایی که در آن مشترک شده‌اید، مانند به‌روزرسانی نام یا توضیحات فضا.
• تغییرات در دسترس بودن کاربر.
• تغییرات در spaceReadState یا threadReadState کاربر.

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

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

رابط برنامه‌نویسی کاربردی رویدادهای فضای کاری گوگل (Google Workspace Events API) از منابع هدف زیر برای چت پشتیبانی می‌کند:

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

هنگام ایجاد اشتراک، از فیلد eventTypes[] برای مشخص کردن انواع رویدادهایی که می‌خواهید دریافت کنید، استفاده کنید. انواع رویدادها طبق مشخصات CloudEvents قالب‌بندی می‌شوند google.workspace. APPLICATION . RESOURCE . VERSION . ACTION

برای مثال، برای دریافت رویدادهای مربوط به پیوستن کاربران به یک فضای چت، فضا را به عنوان منبع هدف و نوع رویداد را google.workspace.chat.membership.v1.created مشخص کنید. برای دریافت رویدادهای مربوط به پیوستن یک کاربر خاص به هر فضایی، کاربر را به عنوان منبع هدف و نوع رویداد را google.workspace.chat.membership.v1.created مشخص کنید. برای کسب اطلاعات بیشتر در مورد نحوه عملکرد رویدادها، به ساختار رویدادهای Google Workspace مراجعه کنید.

جدول زیر انواع رویدادهایی را که برای اشتراک در فضاها و اشتراک در کاربران پشتیبانی می‌شوند، نشان می‌دهد. برای کسب اطلاعات در مورد استثنائات مربوط به آنچه یک رویداد را فعال می‌کند، به محدودیت‌ها مراجعه کنید.

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

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

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

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

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

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

این بخش داده‌های رویداد و نمونه‌هایی از بارهای داده برای رویدادها در چت را شرح می‌دهد.

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

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

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

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

{
    "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"
    }
}
      

{
    "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"
    }
}
      

{
    "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"
    }
}
      

{
    "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"
          }
        }
    ]
}
      

{
    "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"
    }
}
      

{
    "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",
        }
      }
    ]
}
      

{
  "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"
  }
}
      

{
  "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"
  }
}
      

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "ACTIVE"
    }
}
      

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
      

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "IDLE",
    }
}
      

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
      

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "AWAY",
    }
}
      

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
      

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "DO_NOT_DISTURB",
        "doNotDisturbMetadata": {
          "expirationTime": "2026-03-24T18:36:31.337Z"
        }
    }
}
      

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
      

{
    "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",
    }
}
      

محدودیت‌های کلی

• برای دریافت رویدادهای عضویت، کاربر یا برنامه چت باید عضو مستقیم آن فضا باشند. اگر آنها به طور غیرمستقیم از طریق یک گروه گوگل به یک فضا اضافه، به‌روزرسانی یا حذف شده باشند، اشتراک آن رویدادهای عضویت را دریافت نمی‌کند. برای درک نحوه عملکرد عضویت در گروه گوگل، به افزودن یک گروه گوگل به یک فضا مراجعه کنید.

اشتراک‌های کاربری

• برای اشتراک کاربران، رویدادهای مربوط به اعضای جدید در پیام‌های مستقیم یا چت‌های گروهی بدون نام ( google.workspace.chat.membership.v1.created )، فقط پس از ارسال اولین پیام فعال می‌شوند.

اشتراک‌های مشتری (پیش‌نمایش توسعه‌دهنده science )

برای اشتراک‌های مشتری، محدودیت‌های زیر اعمال می‌شود:

• سازمان Google Workspace باید حداقل یک مجوز Enterprise SKU داشته باشد. توجه داشته باشید که این الزام در مرحله برنامه پیش‌نمایش توسعه‌دهندگان به طور جدی اعمال نمی‌شود، اما در آینده (که جداگانه اعلام خواهد شد) اعمال خواهد شد.
• یک برنامه چت فقط می‌تواند یک اشتراک مشتری برای یک سازمان Google Workspace مشخص ایجاد کند. یک سازمان Google Workspace می‌تواند در مجموع تا پنج اشتراک مشتری (ایجاد شده توسط برنامه‌های چت مختلف) داشته باشد.

برای اشتراک‌های مشتری، تحویل رویداد از این قوانین کلی پیروی می‌کند:

• رویدادهای فضایی : فقط در صورتی ارائه می‌شود که رویداد در فضایی تحت مدیریت سازمان Google Workspace شما رخ دهد.
• رویدادهای کاربر : فقط در صورتی ارائه می‌شود که رویداد برای کاربری که متعلق به سازمان Google Workspace شما است، رخ دهد.

تنها استثنا برای این قوانین، رویدادهای عضویت است. اشتراک شما می‌تواند رویدادهای عضویت را هم از فضاهای مدیریت‌شده توسط سازمان شما و هم از فضاهای مدیریت‌شده توسط سازمان‌های خارجی دریافت کند، اما نحوه‌ی ارائه‌ی آن‌ها بستگی به این دارد که کدام سازمان فضا را مدیریت می‌کند:

فضاهای مدیریت‌شده توسط سازمان Google Workspace شما

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

نام منبع یک رویداد فضایی از قالب زیر استفاده می‌کند:

spaces/{spaceId}/spaceEvents/{spaceEventId}

فضاهایی که توسط سازمان‌های خارجی مدیریت می‌شوند

اگر عضویت کاربری که توسط سازمان Google Workspace شما مدیریت می‌شود، در فضایی که توسط یک سازمان خارجی مدیریت می‌شود (مثلاً یک فضای نامگذاری‌شده خارجی یا یک پیام مستقیم ایجاد شده توسط یک کاربر خارجی) تغییر کند، اشتراک شما این رویداد را به عنوان یک رویداد کاربری دریافت می‌کند.

نام منبع یک رویداد کاربر از قالب زیر استفاده می‌کند:

users/{userId}/userEvents/{userEventId}

مباحث مرتبط

• ساختار رویدادهای Google Workspace
• انتخاب محدوده‌های OAuth
• برای دریافت رویدادهای چت، اشتراک ایجاد کنید