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

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

//chat.googleapis.com/spaces/-

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

//cloudidentity.googleapis.com/users/USER

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

ينشر مستخدم رسالة في المساحة تقول "مرحبًا بالعالم".

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 SKU.
  • يمكن لتطبيق Chat إنشاء اشتراك عميل واحد فقط لمؤسسة معيّنة على Google Workspace. يمكن أن يكون لدى مؤسسة Google Workspace ما يصل إلى خمسة اشتراكات عملاء في المجمل (تم إنشاؤها بواسطة تطبيقات Chat مختلفة).

بالنسبة إلى اشتراكات العملاء، يتّبع تسليم الأحداث القواعد العامة التالية:

  • أحداث المساحة: يتم تسليمها فقط إذا حدث الحدث في مساحة تديرها مؤسستك على Google Workspace.
  • أحداث المستخدمين: يتم تسليمها فقط إذا حدث الحدث لمستخدم ينتمي إلى مؤسستك على Google Workspace.

الاستثناء الوحيد لهذه القواعد هو أحداث العضوية. يمكن أن يتلقّى اشتراكك أحداث العضوية من المساحات التي تديرها مؤسستك والمساحات التي تديرها مؤسسات خارجية، ولكن طريقة تسليمها تعتمد على المؤسسة التي تدير المساحة:

المساحات التي تديرها مؤسستك على Google Workspace

إذا حدث تغيير في العضوية في مساحة تديرها مؤسسة Google Workspace، يتم إرسالها كـ حدث مساحة.

يستخدم اسم المورد لحدث مساحة التنسيق التالي:

spaces/{spaceId}/spaceEvents/{spaceEventId}

المساحات التي تديرها مؤسسات خارجية

إذا تغيّرت عضوية مستخدم تديره مؤسستك على Google Workspace في مساحة تديرها مؤسسة خارجية (على سبيل المثال، مساحة خارجية مُسمّاة أو رسالة مباشرة أنشأها مستخدم خارجي)، يتلقّى اشتراكك هذا الحدث كـ حدث مستخدم.

يستخدم اسم المورد لحدث مستخدم التنسيق التالي:

users/{userId}/userEvents/{userEventId}