الاشتراك في أحداث Google Chat

توضّح هذه الصفحة أحداث 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:

المورد المستهدف التنسيق القيود
مسافة

//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 وتحديدهم.

لا يتلقّى الاشتراك سوى أحداث حول المستخدم الذي منح الإذن بالاشتراك. لا يمكن للمستخدم تفويض اشتراك نيابةً عن مستخدمين آخرين. يتيح مصادقة المستخدم فقط.
العميل ( معاينة المطور)

//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 أيضًا أحداثًا مجمّعة. حدث مجمّع هو حدث يمثّل العديد من الأحداث من النوع نفسه التي تحدث خلال فترة زمنية قصيرة. تحتوي حمولة حدث الدفعات على قائمة بجميع الموارد التي تم تغييرها.

على سبيل المثال، إذا أضاف مستخدم 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",
    }
}

القيود وسلوكيات التسليم

القيود العامة

  • لتلقّي أحداث العضوية، يجب أن يكون المستخدم أو تطبيق 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}