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

يتلقّى الوكيل أحداث 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".

في ما يلي مثال على حمولة 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 الذي يدير هذه المحادثة، تقع على عاتقك مسؤولية الاستجابة لطلب المستخدم بإلغاء الاشتراك.
  • إذا تعذّر إلغاء الاشتراك من داخل سلسلة الرسائل، عليك إرسال رسالة تأكيد على الفور تتضمّن رابطًا مباشرًا إلى الموقع الإلكتروني أو التطبيق الذي يمكن للمستخدمين من خلاله إدارة إعداداتهم المفضّلة بشأن الاشتراك.
  • بعد إلغاء المستخدم للاشتراك، يُحظر إرسال رسائل غير ضرورية.
  • سيظل مسموحًا بإرسال الرسائل الأساسية. وتشمل هذه الأسباب ما يلي:
    • عمليات المصادقة، مثل كلمات المرور الصالحة لمرة واحدة (OTP)
    • إشعارات حول خدمة معيّنة طلبها المستخدم ووافق عليها
    • تأكيد على طلب المستخدم إلغاء الاشتراك، مع معلومات تتيح له إدارة إعدادات تلقّي الرسائل

مثال

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

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

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

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

تظهر أسباب إلغاء الاشتراك في نظرة عامة على "إحصاءات 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.

إعدادات الرد التلقائي على الويب

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

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

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

يتم تسليم 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 في حمولة الحدث إلى حالة التشغيل الجديدة للعامل. في ما يلي القيم المحتمَلة:

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

يحتوي حقل البيانات على عنصر 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 TERMINATED تم إنهاء الوكيل المعلق.
TERMINATED LAUNCHED تم إطلاق وكيل تم إنهاؤه.

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

يشير هذا الحدث إلى أنّ مدة بقاء الرسالة (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 في خدمة الويب الخاصة بك.
  • إذا لم يتم تسليم الرسالة، استخدِم واجهة برمجة التطبيقات للإبطال من أجل إرسال طلب إبطال.

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

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