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

يتلقّى الوكيل أحداث الويب هوك من منصة مراسلة المؤسسات من خلال خدمات الاتصالات التفاعلية (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",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID",
  "suggestionResponse": {
    "postbackData": "postback_1234"
  }
}

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

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

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

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

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

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

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

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

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

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

• لتحديد انتهاكات السياسات وقواعد العمل، تراقب Google أنماط الرسائل بعد إلغاء اشتراك المستخدم.

قواعد العمل

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

مثال

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

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

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

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

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

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

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

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

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

كيفية عمل ميزة إعادة الاشتراك

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

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

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

قواعد العمل

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

أحداث المنصة

ترسل منصة "مراسلة الأنشطة التجارية من خلال خدمات الاتصالات التفاعلية (RCS)" أحداث المنصة لإعلام الوكيل بالتغييرات في حالة إطلاق الوكيل أو انتهاء صلاحية الرسائل.

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

ترسل منصة مراسلة المؤسسات من خلال خدمات الاتصالات التفاعلية (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 في حمولة الحدث إلى حالة الإطلاق الجديدة للوكيل. في ما يلي القيم المحتمَلة:

يحتوي حقل البيانات على عنصر 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"
}

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

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

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

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

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

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

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

{
  "phoneNumber": "PHONE_NUMBER",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID",
  "eventType": "TTL_EXPIRATION_REVOKED",
  "eventId": "EVENT_ID",
  "sendTime": "TIMESTAMP"
}

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

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

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

{
  "phoneNumber": "PHONE_NUMBER",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID",
  "eventType": "TTL_EXPIRATION_REVOKE_FAILED",
  "eventId": "EVENT_ID",
  "sendTime": "TIMESTAMP"
}

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

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

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