تبلغ إيصالات استلام الرسالة المُرسِل أن رسائله قد تم استلامها أو قراءتها. وباستخدام الإيصالات، يمكن للمستخدمين معرفة الوقت الذي قرأ فيه الوكيل رسائلهم، وبذلك يتوقع أن يتوقعوا ردًا. يمكن للوكيل أيضًا تحديد الوقت الذي يتلقى فيه المستخدمون الرسائل ويقرأونها، لذلك يمكنك تتبع مقاييس الإيصالات للحصول على تصميمات تفاعلية أفضل.
يتلقى الوكلاء الإيصالات في الرد التلقائي على الويب. يمكنك تلقي الإيصالات ومعالجتها بنفس طريقة تلقي الرسائل.
إذا أرسل أحد المستخدمين إيصالات متعددة في آنٍ واحد، تحتوي حمولة واحدة على جميع إيصالات استلام الرسائل، عن طريق استلام رسائل متعددة أو قراءتها في آنٍ واحد. تحقق من كل إيصال للرسالة المقترنة به.
أنواع الإيصالات
توفّر ميزة "الرسائل التجارية" إيصالات التسليم وإيصالات الاستلام.
الإيصالات من المستخدمين
يمكن للوكلاء تلقّي الإيصالات التالية من المستخدمين:
- تشير إيصالات التسليم (
DELIVERED
) إلى أن المستخدم استلم رسالة من الوكيل. - تشير إيصالات الاستلام (
READ
) إلى أن المستخدم قرأ رسالة من الوكيل.
يمكن للمستخدمين إيقاف إرسال إيصالات الاستلام. وفي حال إيقاف هذا الإعداد، سيستمرون في تلقّي إيصالات استلام من الوكلاء.
الإيصالات من الوكلاء
يمكن للمستخدمين تلقّي إيصالات استلام من الوكلاء.
تشير إيصالات الاستلام (READ
) إلى أنّ الوكيل قرأ رسالة من المستخدم.
إذا كان هناك أكثر من وكيل مباشر واحد يدير المحادثة، يعني إيصال الاستلام أنّ هناك وكيلاً واحدًا على الأقل يقرأ رسالة المستخدم.
الشكل
الإيصالات من المستخدمين
تكون إيصالات التسليم من المستخدمين بالتنسيق التالي:
{ "agent": "brands/BRAND_ID/agents/AGENT_ID", "conversationId": "CONVERSATION_ID", "customAgentId": "CUSTOM_AGENT_ID", "sendTime": "SEND_TIME", "receipts" : { "receipts": [ { "message": "conversations/CONVERSATION_ID/messages/MESSAGE_ID", "receiptType": "DELIVERED", } ], "createTime": "RECEIPTS_CREATION_TIME", }, }
تكون إيصالات الاستلام من المستخدمين بالتنسيق التالي:
{ "agent": "brands/BRAND_ID/agents/AGENT_ID", "conversationId": "CONVERSATION_ID", "customAgentId": "CUSTOM_AGENT_ID", "sendTime": "SEND_TIME", "receipts" : { "receipts": [ { "message": "conversations/CONVERSATION_ID/messages/MESSAGE_ID", "receiptType": "READ", } ], "createTime": "RECEIPTS_CREATION_TIME", }, }
للتعرّف على خيارات التنسيق والقيمة، راجِع
UserMessage
وReceipts
.
الإيصالات من الوكلاء
يرسل الرمز التالي إيصالاً بالقراءة من الوكيل:
cURL
curl -X PATCH \ -H "`./oauth2l header --json 'PATH_TO_SERVICE_ACCOUNT_KEY' businessmessages`" \ -H "Content-Type: application/json" \ -d '{ "receiptType": "READ" }' \ "https://businessmessages.googleapis.com/v1/conversations/CONVERSATION_ID/messages/MESSAGE_ID/receipt"
Node.js
const businessmessages = require('businessmessages'); const uuidv4 = require('uuid/v4'); const {google} = require('googleapis'); // Initialize the Business Messages API let bmApi = new businessmessages.businessmessages_v1.Businessmessages({}); // Set the scope that we need for the Business Messages API const scopes = [ 'https://www.googleapis.com/auth/businessmessages', ]; // Set the private key to the service account file const privatekey = require('PATH_TO_SERVICE_ACCOUNT_KEY'); /** * Initializes the Google credentials for calling the * Business Messages API. */ async function initCredentials() { // Configure a JWT auth client let authClient = new google.auth.JWT( privatekey.client_email, null, privatekey.private_key, scopes, ); return new Promise(function(resolve, reject) { // Authenticate request authClient.authorize(function(err, tokens) { if (err) { reject(false); } else { resolve(authClient); } }); }); } /** * Sends a read receipt to a specific messageId. * * @param {string} conversationId The unique id for this user and agent. * @param {string} messageId The unique id for this message. */ async function sendReadReceipt(conversationId, messageId) { let authClient = await initCredentials(); // Create the payload for sending a read receipt let apiParams = { auth: authClient, name: 'conversations/' + conversationId + '/messages/' + messageId + '/receipt', resource: { receiptType:'READ' } }; // Call the updateReceipt create function using the // Business Messages client library bmApi.conversations.messages.updateReceipt(apiParams, {auth: authClient}, (err, response) => { console.log(err); console.log(response); }); } sendReadReceipt('CONVERSATION_ID', 'MESSAGE_ID');يستند هذا الرمز إلى مكتبة برامج "الرسائل التجارية" Node.js.
لغة Java
import com.google.api.client.googleapis.services.AbstractGoogleClientRequest; import com.google.api.client.http.HttpBackOffUnsuccessfulResponseHandler; import com.google.api.client.http.HttpRequest; import com.google.api.client.googleapis.auth.oauth2.GoogleCredential; import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport; import com.google.api.client.http.HttpTransport; import com.google.api.client.json.jackson2.JacksonFactory; import com.google.api.client.util.ExponentialBackOff; import com.google.api.services.businessmessages.v1.Businessmessages; import com.google.api.services.businessmessages.v1.model.BusinessMessagesReceipt; import com.google.api.services.businessmessages.v1.model.*; import java.io.FileInputStream; import java.util.Arrays; import java.util.UUID; public class ReadReceiptSample { /** * Initializes credentials used by the Business Messages API. */ private static Businessmessages.Builder getBusinessMessagesBuilder() { Businessmessages.Builder builder = null; try { GoogleCredential credential = GoogleCredential .fromStream(new FileInputStream("PATH_TO_SERVICE_ACCOUNT_KEY")); credential = credential.createScoped(Arrays.asList( "https://www.googleapis.com/auth/businessmessages")); credential.refreshToken(); HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport(); JacksonFactory jsonFactory = JacksonFactory.getDefaultInstance(); // Create instance of the Business Messages API builder = new Businessmessages .Builder(httpTransport, jsonFactory, null) .setApplicationName("Sample Application"); // Set the API credentials and endpoint builder.setHttpRequestInitializer(credential); } catch (Exception e) { e.printStackTrace(); } return builder; } public static void main(String args[]) { try{ String conversationId = "CONVERSATION_ID"; String messageId = "MESSAGE_ID"; // Create client library reference Businessmessages.Builder builder = getBusinessMessagesBuilder(); // Create a new read receipt Businessmessages.Conversations.Messages.UpdateReceipt request = builder.build().conversations().messages() .updateReceipt("conversations/" + conversationId + "/messages/" + messageId + "/receipt", new BusinessMessagesReceipt().setReceiptType("READ")); // Set up retries with exponential backoff HttpRequest httpRequest = ((AbstractGoogleClientRequest) request).buildHttpRequest(); httpRequest.setUnsuccessfulResponseHandler(new HttpBackOffUnsuccessfulResponseHandler( new ExponentialBackOff())); // Execute request httpRequest.execute(); } catch (Exception e) { e.printStackTrace(); } } }تستند هذه الشفرة إلى مكتبة عميل "الرسائل التجارية في جافا".
لغة Python
from oauth2client.service_account import ServiceAccountCredentials from businessmessages import businessmessages_v1_client as bm_client from businessmessages.businessmessages_v1_messages import ( BusinessMessagesReceipt) credentials = ServiceAccountCredentials.from_json_keyfile_name( 'PATH_TO_SERVICE_ACCOUNT_KEY', scopes=['https://www.googleapis.com/auth/businessmessages']) client = bm_client.BusinessmessagesV1(credentials=credentials) conversation_id = 'CONVERSATION_ID' message_id = 'MESSAGE_ID' read_receipt = BusinessMessagesReceipt( name=f"conversations/{conversation_id}/messages/{message_id}/receipt", receiptType=BusinessMessagesReceipt.ReceiptTypeValueValuesEnum.READ ) # Send the message bm_client.BusinessmessagesV1.ConversationsMessagesService( client=client).UpdateReceipt(request=read_receipt)تستند هذه الشفرة إلى مكتبة عميل Python Business Messages.
للتعرُّف على خيارات التنسيق والقيمة، يُرجى الاطّلاع على
ReceiptType
.