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

يتلقّى الوكيل أحداث ويب هوك من منصة 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"
  }
}

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

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

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

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

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

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

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

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

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

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

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

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

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

مثال

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

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

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

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

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

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

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

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

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

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

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

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

    البلد (رمز البلد) كلمة رئيسية للاشتراك
    ألمانيا (DE) والمملكة المتحدة (GB) والهند (IN) وهولندا (NL) والولايات المتحدة (US) البدء
    إسبانيا (ES) والمكسيك (MX) ALTA
    فرنسا (FR) Démarrer
    البرازيل (BR) 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 إرسالها للمراجعة
PENDING UNLAUNCHED إلغاء طلب إطلاق في انتظار المراجعة
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 في عنوان URL الخاص بخدمة الويب.
  • إذا لم يتم تسليم الرسالة، استخدِم واجهة برمجة التطبيقات للإبطال من أجل إرسال طلب إبطال.

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

السابق
إرسال الأحداث
التالي
عمليات التحقق من الإمكانية