الأحداث

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

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

ترسل منصة 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"
}

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

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