إرسال إيصالات الاستلام واستلامها

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

تتلقّى البرامج الوكيلة الإيصالات في ويب هوك. تلقّي الإيصالات ومعالجتها بالطريقة نفسها التي تتلقّى بها الرسائل

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

أنواع الإيصالات

تتيح ميزة "الرسائل التجارية" إيصالات التسليم وإيصالات الاستلام.

الإيصالات من المستخدمين

يمكن أن يتلقّى الوكلاء الإيصالات التالية من المستخدمين:

• تشير إيصالات التسليم (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 في Business Messages.

جافا

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();
    }
  }
}

يستند هذا الرمز إلى مكتبة برامج Java Business Messages.

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)

يستند هذا الرمز إلى مكتبة برامج Business Messages بلغة Python.

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