الأحداث

الأحداث هي إشعارات يمكن أن يرسلها ويتلقّاها وكيلك. هناك ثلاثة أنواع من الأحداث:

الأحداث التي ينشئها الخادم

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

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

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

ترسل منصة RBM إشعارًا AgentLaunchEvent لكل تغيير في حالة إطلاق الوكيل. على سبيل المثال، عندما تتغيّر حالة وكيلك من PENDING إلى LAUNCHED بعد موافقة شركة الاتصالات، ستتلقّى حدث AgentLaunchEvent للإشارة إلى هذا التغيير. يتم إرسال هذه الأحداث إلى جميع وكلاء RBM، وذلك لجميع تغييرات حالة إطلاق مشغّل شبكة الجوّال.

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

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

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

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

يتم تسليم 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 تم إطلاق الوكيل الذي تم إنهاؤه.

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

انتهت صلاحية الرسالة وتم إبطالها بنجاح. سيكون هذا الحدث عاملاً جيدًا لتفعيل استراتيجية الرسائل الاحتياطية.

{
  "phoneNumber": [phone number of recipient that the original message was intended for] ,
  "messageId": [RCS message ID of the message],
  "agentId": [bot ID],
  "eventType": "TTL_EXPIRATION_REVOKED",
  "eventId": [unique ID generated by the RBM platform],
  "sendTime": [time at which the server sent this event]
}

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

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

{
  "phoneNumber": [phone number of recipient that the original message was intended for] ,
  "messageId": [RCS message ID of the message],
  "agentId": [bot ID],
  "eventType": "TTL_EXPIRATION_REVOKE_FAILED",
  "eventId": [unique ID generated by the RBM platform],
  "sendTime": [time at which the server sent this event]
}

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

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

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

الأحداث التي ينشئها المستخدمون

كما هو الحال مع رسائل المستخدمين وعمليات التحقّق من الإمكانات، يتلقّى الوكيل أحداث المستخدمين بتنسيق JSON.

للاطّلاع على خيارات التنسيق والقيمة، يُرجى الرجوع إلى 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"
}

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

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

{
  "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 إلى أنّ المستخدم قد ألغى اشتراكه في المحادثة مع وكيلك والنشاط التجاري الذي يمثّله. في ما يلي مثال على حمولة 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".

يشير الحدث SUBSCRIBE إلى أنّ المستخدم يريد تلقّي رسائل من وكيلك، بما في ذلك المحتوى غير الأساسي، مثل العروض الترويجية. في ما يلي مثال على حمولة 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 مسؤولية تعديل حالته واستئناف إرسال الرسائل وفقًا لذلك.

الأحداث التي ينشئها وكيل

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

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

يرسل موظف الدعم حدث READ

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

يرسل الرمز التالي حدث READ لرسالة تتضمّن messageId مطابقًا.

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentEvents?eventId=EVENT_ID&agentId=AGENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d "{
  'eventType': 'READ',
  'messageId': 'MESSAGE_ID'
}"

Node.js

// Reference to RBM API helper
const rbmApiHelper = require('@google/rcsbusinessmessaging');

// Send the device an event to indicate that messageId has been read
rbmApiHelper.sendReadMessage('+12223334444', messageId);
 هذا الرمز هو مقتطف من وكيل نموذجي في RBM.

Java

import com.google.rbm.RbmApiHelper;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper();

// Send the device an event to indicate that messageId has been read
rbmApiHelper.sendReadMessage(messageId, "+12223334444");
 هذا الرمز هو مقتطف من وكيل نموذجي في RBM.

Python

# Reference to RBM Python client helper and messaging object structure
from rcs_business_messaging import rbm_service

# Send the device an event to indicate that message_id was read
rbm_service.send_read_event('+12223334444', message_id)
 هذا الرمز هو مقتطف من وكيل نموذجي في RBM.

#C

using RCSBusinessMessaging;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation,
                                                 projectId);

// Send the device an event to indicate that messageId has been read
rbmApiHelper.SendReadMessage(messageId, "+12223334444");
 هذا الرمز هو مقتطف من وكيل نموذجي في RBM.

يرسل الوكيل حدث IS_TYPING

يظهر هذا الحدث للمستخدمين كمؤشر كتابة، ويُعلمهم بأنّ وكيلك يكتب رسالة. تنتهي صلاحية مؤشر الكتابة بعد فترة قصيرة (حوالي 20 ثانية) أو عندما يتلقّى جهاز المستخدم رسالة جديدة من الوكيل. يمكن أن يرسل برنامجك عدة أحداث IS_TYPING لإعادة ضبط مؤقّت انتهاء صلاحية مؤشر الكتابة.

يرسل الرمز التالي حدث IS_TYPING.

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentEvents?eventId=EVENT_ID&agentId=AGENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d "{
  'eventType': 'IS_TYPING',
}"

Node.js

// Reference to RBM API helper
const rbmApiHelper = require('@google/rcsbusinessmessaging');

// Send the device an event to indicate that the agent is typing
rbmApiHelper.sendIsTypingMessage('+12223334444', function() {
    console.log('Typing event sent!');
});
 هذا الرمز هو مقتطف من وكيل نموذجي في RBM.

Java

import com.google.rbm.RbmApiHelper;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper();

// Send the device an event to indicate that the agent is typing
rbmApiHelper.sendIsTypingMessage("+12223334444");
 هذا الرمز هو مقتطف من وكيل نموذجي في RBM.

Python

# Reference to RBM Python client helper and messaging object structure
from rcs_business_messaging import rbm_service

# Send the device an event to indicate that the agent is typing
rbm_service.send_is_typing_event('+12223334444')
 هذا الرمز هو مقتطف من وكيل نموذجي في RBM.

#C

using RCSBusinessMessaging;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation,
                                                 projectId);

// Send the device an event to indicate that the agent is typing
rbmApiHelper.SendIsTypingMessage(messageId, "+12223334444");
 هذا الرمز هو مقتطف من وكيل نموذجي في RBM.
السابق
تلقي الرسائل
التالي
عمليات التحقق من الإمكانية