שליחה וקבלה של הודעות

אישורי מסירה מודיעים לשולח שההודעות שלו התקבלו או נקראו. באמצעות אישורי קריאה, המשתמשים יכולים לראות מתי נציג תמיכה קרא את ההודעות שלהם, וכך הם יודעים שהם צפויים לקבל תשובה. הסוכן יכול גם לקבוע מתי המשתמשים מקבלים וקוראים את ההודעות, כך שתוכלו לעקוב אחרי מדדי הקבלה כדי לשפר את עיצוב האינטראקציות.

הסוכנים מקבלים קבלות ב-webhook שלהם. מקבלים ומעבדים קבלות באותו אופן שבו מקבלים הודעות.

אם משתמש שולח כמה אישורי קריאה בבת אחת, כי הוא קיבל או קרא כמה הודעות בו-זמנית, מטען ייעודי (payload) אחד יכיל את כל אישורי הקריאה של ההודעות. בודקים כל אישור קריאה כדי לראות לאיזו הודעה הוא משויך.

סוגי קבלות

ב-Business Messages יש תמיכה באישורי מסירה ובאישורי קריאה.

קבלות ממשתמשים

סוכנים יכולים לקבל מהמשתמשים את הקבלות הבאות:

• אישורי מסירה (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.

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

הקוד הזה מבוסס על ספריית הלקוח של 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)

הקוד הזה מבוסס על ספריית הלקוח של Python Business Messages.

אפשרויות העיצוב והערכים מפורטות במאמר בנושא ReceiptType.