تلقّي الأحداث

يتلقّى الوكيل أحداث Webhook من منصة RBM، ما يتيح لك تلقّي إشعارات بشأن تفاعلات المستخدمين والتحديثات على مستوى المنصة.

يتم تصنيف هذه الأحداث حسب مصدرها:

أحداث المستخدم: الإشعارات المرسَلة من جهاز المستخدم إلى المساعد الرقمي، والتي تشير إلى تفاعل مع المساعد الرقمي أو رسائله.
أحداث النظام الأساسي: إشعارات حول التغييرات في حالة إطلاق الوكيل وانتهاء صلاحية الرسائل، يتم إرسالها من خلال منصة RBM.

للحصول على تفاصيل حول أحداث الحالة التي يرسلها البرنامج إلى جهاز المستخدم، يُرجى الاطّلاع على إرسال الأحداث.

أحداث المستخدم

أحداث المستخدم هي إشعارات من جهاز المستخدم تُبلغ عن حالة الرسالة أو تغييرات الاشتراك (أي أنّ المستخدم ألغى اشتراكه أو أعاد الاشتراك في تطبيق "رسائل Google").

للاطّلاع على خيارات التنسيق والقيم الكاملة، يُرجى الرجوع إلى مرجع UserEvent.

يتلقّى المستخدم رسالة من موظّف الدعم

يشير هذا الحدث إلى أنّه تم تسليم رسالة بنجاح إلى جهاز المستخدم.

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "DELIVERED",
  "eventId": "EVENT_ID",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID"
}

يقرأ المستخدم رسالة موظّف الدعم

يشير هذا الحدث إلى أنّه تم فتح رسالة أو تمّت الاستجابة لها.

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "READ",
  "eventId": "EVENT_ID",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID"
}

بدء المستخدم الكتابة

يشير هذا الحدث إلى أنّ المستخدم يكتب ردًا.

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "IS_TYPING",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

يرسل المستخدم رسالة نصية

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "text": "Hi",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

يرسل المستخدم ملفًا

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "userFile": {
    "payload": {
      "mimeType": "image/gif",
      "fileSizeBytes": 127806,
      "fileUri": "https://storage.googleapis.com/copper_test/77ddb795-24ad-4607-96ae-b08b4d86406a/d2dcc67ab888d34ee272899c020b13402856f81597228322079eb007e8c9",
      "fileName": "4_animated.gif"
    }
  },
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

ينقر المستخدم على ردّ مقترَح

عندما ينقر المستخدم على ردّ مقترَح، يتلقّى وكيلك حدثًا يتضمّن بيانات الردّ النصية وبيانات postback.

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID",
  "suggestionResponse": {
    "postbackData": "postback_1234",
    "text": "Hello there!"
  }
}

ينقر المستخدم على إجراء مقترَح

عندما ينقر المستخدم على إجراء مقترَح، يتلقّى وكيلك حدثًا يتضمّن بيانات الردّ التلقائي الخاصة بالإجراء.

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID",
  "suggestionResponse": {
    "postbackData": "postback_1234"
  }
}

إلغاء المستخدم الاشتراك في المحادثة

يشير هذا الحدث إلى أنّ المستخدم قد ألغى الاشتراك في تلقّي رسائل غير ضرورية، مثل الرسائل الترويجية، من برنامج الدردشة والمؤسسة التي يمثّلها. يبدأ المستخدمون هذا الحدث من خلال إلغاء الاشتراك في محادثة RBM في تطبيق "رسائل Google".

ملاحظة مهمة: لمساعدة المطوّرين في الانتقال إلى أحداث UNSUBSCRIBE وSUBSCRIBE الجديدة على الويب، يرسل تطبيق "رسائل Google" أيضًا رسائل "إيقاف" و"بدء" إلى جانب أحداث الويب. على الرغم من أنّه يمكنك الاعتماد على منطق الإيقاف/البدء الحالي في الوقت الحالي، ننصحك بشدة بتعديل منطقك للتعامل مع حدثَي UNSUBSCRIBE وSUBSCRIBE، لأنّهما سيصبحان إلزاميين بما يتوافق مع مواصفات GSMA.

في ما يلي مثال على حمولة JSON:

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "UNSUBSCRIBE",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

طريقة عمل ميزة إلغاء الاشتراك

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

يؤدي النقر على إلغاء الاشتراك إلى تنفيذ إجراءَين متزامنين: يرسل تطبيق "رسائل Google" كلمة رئيسية خاصة بالبلد (مثل "إيقاف") إلى وكيلك، وترسل منصة RBM حدث UNSUBSCRIBE إلى رابط الويب الخاص بك.

يتم تحديد الكلمة الرئيسية من خلال رمز البلد المكوّن من حرفَين لرقم هاتف المستخدم. يسرد الجدول التالي الكلمات الرئيسية لكل بلد يتوفّر فيه التطبيق.

البلد (رمز البلد)	كلمة رئيسية لإلغاء الاشتراك
الولايات المتحدة (US) والهند (IN) والمملكة المتحدة (GB) وألمانيا (DE)	إيقاف
إسبانيا (ES) والمكسيك (MX)	BAJA
فرنسا	إيقاف
البرازيل	parar

بعد إلغاء الاشتراك، تبقى المحادثة في البريد الوارد للمستخدم ما لم يتم الإبلاغ عنها كرسالة غير مرغوب فيها، وفي هذه الحالة يتم نقلها إلى مجلد المحادثات غير المرغوب فيها والمحظورة.
لتحديد انتهاكات السياسات وقواعد النشاط التجاري، تراقب Google أنماط الرسائل بعد إلغاء المستخدم اشتراكه.

قواعد النشاط التجاري

بصفتك شريك RBM الذي يدير هذه المحادثة، تقع على عاتقك مسؤولية الاستجابة لطلب المستخدم بإلغاء الاشتراك.
إذا تعذّر إلغاء الاشتراك ضمن سلسلة الرسائل، عليك إرسال رسالة تأكيد على الفور تتضمّن رابطًا مباشرًا إلى الموقع الإلكتروني أو التطبيق حيث يمكن للمستخدمين إدارة إعداداتهم المفضّلة بشأن الاشتراكات.
بعد إلغاء المستخدم للاشتراك، يُحظر إرسال رسائل غير ضرورية.
سيظل مسموحًا بإرسال الرسائل الأساسية. وتشمل هذه الأذونات ما يلي:
- عمليات المصادقة، مثل كلمات المرور الصالحة لمرة واحدة
- إشعارات حول خدمة معيّنة طلبها المستخدم ووافق عليها
- تأكيد على طلب المستخدم إلغاء الاشتراك، مع معلومات تتيح له إدارة إعدادات تلقّي الرسائل بشكل أكبر

مثال

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

أسباب إلغاء الاشتراك

عندما يلغي المستخدم اشتراكه في وكيلك، يمكنه اختيار سبب من الخيارات التالية:

محتوى غير مرغوب فيه
لم يتم الاشتراك مطلقًا
رسائل كثيرة للغاية
لم تعُد المزايا تهمّني
غير ذلك

تظهر أسباب إلغاء الاشتراك في نظرة عامة على "إحصاءات Google" لمساعدة الشركاء في فهم أسباب إلغاء المستخدمين لاشتراكاتهم.

يعيد المستخدم الاشتراك في المحادثة

يشير هذا الحدث إلى أنّ المستخدم يريد تلقّي رسائل من برنامجك الآلي مرة أخرى، بما في ذلك المحتوى غير الأساسي، مثل العروض الترويجية. يمكن للمستخدمين بدء هذا الحدث من خلال إعادة الاشتراك في محادثة سبق لهم إلغاء الاشتراك فيها في تطبيق "رسائل Google".

في ما يلي مثال على حمولة JSON:

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "SUBSCRIBE",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

طريقة عمل إعادة الاشتراك

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

يؤدي النقر على اشتراك إلى تنفيذ إجراءَين متزامنين: ترسل "رسائل Google" كلمة رئيسية خاصة بالبلد (مثل "بدء") إلى وكيلك، وترسل منصة RBM حدث SUBSCRIBE إلى رابط الويب الخاص بك. يتم تحديد الكلمة الرئيسية المحددة من خلال رمز البلد المكوّن من حرفين لرقم هاتف المستخدم. يسرد الجدول التالي الكلمات الرئيسية لكل بلد متاح.

البلد (رمز البلد)	كلمة رئيسية للاشتراك
الولايات المتحدة (US) والهند (IN) والمملكة المتحدة (GB) وألمانيا (DE)	البدء
إسبانيا (ES) والمكسيك (MX)	ALTA
فرنسا	Démarrer
البرازيل	começar

قواعد النشاط التجاري

بصفتك شريك RBM الذي يدير هذه المحادثة، تقع على عاتقك مسؤولية الاستجابة لطلب المستخدم بإعادة الاشتراك.
ينطبق خيار إعادة الاشتراك على جميع أنواع الرسائل، بما في ذلك المحتوى غير الأساسي، مثل العروض الترويجية.
إذا أرسل مستخدم رسالة إلى نشاطك التجاري بعد إلغاء الاشتراك، يمكن اعتبار ذلك طلبًا بإعادة الاشتراك.
إذا أعاد المستخدم الاشتراك خارج قناة المراسلة (على سبيل المثال، على موقعك الإلكتروني)، تقع على عاتقك كشريك في RBM مسؤولية تعديل حالته واستئناف إرسال الرسائل وفقًا لذلك.

أحداث المنصّة

ترسل منصة RBM أحداث المنصة لإعلام الوكيل بالتغييرات التي تطرأ على حالة إطلاق الوكيل أو انتهاء صلاحية الرسائل.

تغيّرت حالة إطلاق الوكيل

ترسل منصة RBM إشعارًا AgentLaunchEvent عند إجراء أي تغيير على حالة إطلاق الوكيل. على سبيل المثال، عندما تتغيّر حالة الوكيل من PENDING إلى LAUNCHED. يتم تسليم الحدث كرسالة Pub/Sub. لتمييز هذا الحدث عن الأحداث الأخرى، تحقّق من المسار message.attributes.type بحثًا عن القيمة agent_launch_event.

إعدادات الويب هوك

يمكنك استخدام الويب هوك على مستوى الشريك أو الوكيل لتلقّي هذه الإشعارات.

المتطلبات الأساسية

إعداد الويب هوك للمراسلة عبر RBM (هذا شرط أساسي لتلقّي رسائل المستخدمين وأحداثهم)
للتفريق بين أحداث المستخدم وأحداث حالة تشغيل الوكيل، تحقّق من المسار message.attributes.type بحثًا عن القيمة agent_launch_event.

بنية حمولة الحدث

يتم تسليم AgentLaunchEvent كرسالة Pub/Sub. وفي ما يلي مثال لذلك:

{
  "message": {
    "attributes": {
      "business_id": "rbm-chatbot-id@rbm.goog",
      "event_type": "REJECTED",
      "product": "RBM",
      "project_number": "3338881441851",
      "type": "agent_launch_event"
    },
    "data": "....BASE64-encoded-JSON-with-notification...",
    "messageId": "14150481888479752",
    "message_id": "14150481888479752",
    "publishTime": "2025-03-05T18:50:21.88Z",
    "publish_time": "2025-03-05T18:50:21.88Z"
  },
  "subscription": "projects/rbm-partner-gcp/subscriptions/rbm-sub"
}

يشير الحقل AgentLaunchEvent.LaunchState في حمولة الحدث إلى حالة التشغيل الجديدة للعامل. في ما يلي القيم المحتملة:

القيمة	حالة إطلاق الوكيل	التفاصيل
`PENDING`	في انتظار المراجعة	تم إرسال الطلب إلى مشغّل شبكة الجوّال لمراجعته.
`LAUNCHED`	تم طرح الميزة.	يُسمح بالرسائل على مشغّل شبكة جوّال معيّن.
`REJECTED`	تم رفضها على مشغّل شبكة جوّال معيّن	يتم تحديد سبب الرفض في التعليق.
`SUSPENDED`	تم تعليقها على مشغّل شبكة جوّال معيّن	يتم تحديد سبب التعليق في التعليق.
`UNLAUNCHED`	لم يتم إطلاقه	يُسمح بالتعديل للوكلاء الذين تم إيقافهم من جميع مشغّلي شبكات الجوّال.

يحتوي حقل البيانات على عنصر JSON بترميز Base64 يتضمّن تفاصيل حالة التشغيل. في ما يلي مثال على ملف JSON الذي تم فك ترميزه:

    {
      "eventId": "rbm-chatbot-id/0a7ed168-676e-4a56-b422-b23434",
      "agentId": "rbm-chatbot-id@rbm.goog",
      "botDisplayName": "RBM Welcome Bot 7 - RBM Chatbot name",
      "brandId": "bd38fbff-392a-437b-a6f2-7f2e43745b56",
      "brandDisplayName": "Chatbots brand",
      "regionId": "/v1/regions/fi-rcs",
      "oldLaunchState": "PENDING",
      "newLaunchState": "REJECTED",
      "actingParty": "rbm-support@google.com",
      "comment": "Carrier has rejected the launch: policy violation",
      "sendTime": "2025-03-05T18:50:19.386436Z"
    }

التغييرات في حالة التشغيل التي يبدأها مشغّل شبكة الجوّال

في ما يلي عمليات النقل المسموح بها التي تتعامل معها شركات النقل عادةً أثناء عملية المراجعة والتنفيذ:

حالة الإطلاق القديمة	حالة الإطلاق الجديدة	إجراء التشغيل
`PENDING`	`LAUNCHED`	الموافقة على طلب إطلاق
`PENDING`	`REJECTED`	رفض طلب إطلاق
`LAUNCHED`	`SUSPENDED`	تعليق الحساب لأسباب تتعلق بالتنفيذ أو الإدارة
`SUSPENDED`	`LAUNCHED`	استعادة حالة الوكيل إلى "نشط"
`SUSPENDED`	`UNLAUNCHED`	إنهاء وكيل

التغييرات على حالة الإطلاق التي يبدأها الشريك

في ما يلي عمليات الانتقال المسموح بها والتي يتولّاها الشركاء عادةً:

حالة الإطلاق القديمة	حالة الإطلاق الجديدة	إجراء التشغيل
`UNSPECIFIED`	`PENDING`	إرسالها للمراجعة
`UNLAUNCHED`	`PENDING`	إرسالها للمراجعة
`REJECTED`	`PENDING`	أعِد إرسالها للمراجعة.

انتهت صلاحية الرسالة؛ تم الإبطال بنجاح

يشير هذا الحدث إلى أنّ مدة بقاء الرسالة (TTL) قد انتهت وتم إبطال الرسالة بنجاح. وهذا مشغّل جيد لاستراتيجية الرسائل الاحتياطية.

للاطّلاع على خيارات التنسيق والقيم الكاملة، يُرجى الرجوع إلى مرجع ServerEvent.

{
  "phoneNumber": "[phone number]" ,
  "messageId": "[RCS message ID]",
  "agentId": [bot ID],
  "eventType": "TTL_EXPIRATION_REVOKED",
  "eventId": "[unique ID]",
  "sendTime": "[time stamp]"
}

انتهت صلاحية الرسالة، وتعذّر إبطالها

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

للاطّلاع على خيارات التنسيق والقيم الكاملة، يُرجى الرجوع إلى مرجع ServerEvent.

{
  "phoneNumber": "[phone number]",
  "messageId": "[RCS message ID]",
  "agentId": "[bot ID]",
  "eventType": "TTL_EXPIRATION_REVOKE_FAILED",
  "eventId": "[unique ID]",
  "sendTime": "[time stamp]"
}

لا نضمن تسليم الرسالة.

إذا تم تسليم الرسالة، ستتلقّى حدث DELIVERED في خدمة الويب هوك.
إذا لم يتم تسليم الرسالة، استخدِم واجهة برمجة التطبيقات للإبطال من أجل إرسال طلب إبطال.

إذا كانت الرسالة حساسة للوقت، مثل كلمة مرور صالحة لمرة واحدة أو تنبيه بشأن الاحتيال، من الأفضل إرسالها عبر قناة بديلة، مثل الرسائل القصيرة، حتى إذا أدى ذلك إلى إرسال رسائل مكررة إلى المستخدم.

إرسال الأحداث

عمليات التحقق من الإمكانية

تلقّي الأحداث تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

أحداث المستخدم

يتلقّى المستخدم رسالة من موظّف الدعم

يقرأ المستخدم رسالة موظّف الدعم

بدء المستخدم الكتابة

يرسل المستخدم رسالة نصية

يرسل المستخدم ملفًا

ينقر المستخدم على ردّ مقترَح

ينقر المستخدم على إجراء مقترَح

إلغاء المستخدم الاشتراك في المحادثة

طريقة عمل ميزة إلغاء الاشتراك

قواعد النشاط التجاري

مثال

أسباب إلغاء الاشتراك

يعيد المستخدم الاشتراك في المحادثة

طريقة عمل إعادة الاشتراك

قواعد النشاط التجاري

أحداث المنصّة

تغيّرت حالة إطلاق الوكيل

إعدادات الويب هوك

المتطلبات الأساسية

بنية حمولة الحدث

التغييرات في حالة التشغيل التي يبدأها مشغّل شبكة الجوّال

التغييرات على حالة الإطلاق التي يبدأها الشريك

انتهت صلاحية الرسالة؛ تم الإبطال بنجاح

انتهت صلاحية الرسالة، وتعذّر إبطالها

تلقّي الأحداث