الأحداث

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

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

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

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

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

انتهت صلاحية الرسالة وتم إبطالها بنجاح. سيكون هذا الحدث مشغّلاً جيدًا لاستراتيجية المراسلة الاحتياطية.

{
  "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" ضمن الردّ التلقائي على الويب.
  • في حال عدم تسليم الرسالة، استخدِم واجهة برمجة تطبيقات الإلغاء لإرسال طلب إبطال.

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

الأحداث من إنشاء المستخدمين

كما هو الحال مع رسائل المستخدم وعمليات التحقّق من الإمكانيات، يتلقّى الوكيل أحداث المستخدم بتنسيق 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"
  }
}

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

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

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

يُرسِل الوكيل حدث READ.

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

يرسل الرمز التالي حدث READ لرسالة تحتوي على messageId مطابق.

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentEvents?eventId=EVENT_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('../libs/rbm_api_helper');

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

Java

import com.google.rbm.samples.lib.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" \
-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('../libs/rbm_api_helper');

// 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.samples.lib.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.