الاشتراك في أحداث 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. يمكنك الحصول على المعرّف من عنوان URL للمساحة أو باستخدام طريقة spaces.list().

يجب أن يكون مستخدم Chat أو تطبيق Chat الذي يمنح الإذن بالاشتراك عضوًا في المساحة من خلال حسابه على Google Workspace أو حسابه على Google. يتوافق مع:
جميع المساحات الخاصة بمستخدم

//chat.googleapis.com/spaces/-

لا يتلقّى الاشتراك سوى أحداث المساحات التي يكون المستخدم عضوًا فيها من خلال حسابه على Google Workspace أو حسابه على Google. يتيح مصادقة المستخدم فقط.
المستخدم

//cloudidentity.googleapis.com/users/USER

حيث USER هو المعرّف في اسم مورد مورد Chat API user. لمزيد من التفاصيل، يُرجى الاطّلاع على مقالة تحديد مستخدمي Google 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.chat.availability.v1.updated

user.availability

أنواع أحداث الدفعات (النتائج فقط)

بالإضافة إلى تلقّي أنواع الأحداث التي تشترك فيها، قد يتلقّى تطبيق Chat أيضًا أحداثًا مجمّعة. حدث مجمّع هو حدث يمثّل العديد من الأحداث من النوع نفسه التي تحدث خلال فترة زمنية قصيرة. تحتوي حمولة حدث الدفعات على قائمة بجميع الموارد التي تم تغييرها.

على سبيل المثال، إذا أضاف مستخدم 20 مستخدمًا إلى مساحة في الوقت نفسه، قد يتلقّى تطبيق 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

ينشر مستخدم رسالة في المساحة نصها "Hello world".

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",
    }
}
      
يضبط المستخدم حالة توفّره على Away في Chat. google.workspace.chat.availability.v1.updated

تتضمّن بيانات الموارد:

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

يستبعد بيانات الموارد:

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
      
يضبط المستخدم حالة توفّره على Do not disturb في Chat. 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",
    }
}
      

القيود

  • بالنسبة إلى الاشتراكات في حسابات المستخدمين، لا يتم تشغيل الأحداث المتعلقة بالأعضاء الجدد في الرسائل المباشرة أو المحادثات الجماعية بدون اسم (google.workspace.chat.membership.v1.created) إلا بعد نشر الرسالة الأولى.
  • لتلقّي أحداث العضوية، يجب أن يكون المستخدم أو تطبيق Chat عضوًا مباشرًا في المساحة. إذا تمت إضافة المستخدم أو تعديله أو إزالته بشكل غير مباشر إلى مساحة من خلال "مجموعة Google"، لن يتلقّى الاشتراك أحداث العضوية هذه. للتعرّف على طريقة عمل عضويات "مجموعة Google"، يمكنك الاطّلاع على إضافة "مجموعة Google" إلى مساحة.