Message receipts inform the sender that their messages were received or read. With receipts, users can see when an agent has read their messages, so they know to expect a response. Your agent can also determine when users receive and read messages, so you can track receipt metrics for better interaction designs.
Agents receive receipts at their webhook. Receive and process receipts the same way you receive messages.
If a user sends multiple receipts at once, by receiving or reading multiple messages at the same time, a single payload contains all the message receipts. Check each receipt for the message it's associated with.
Receipt types
Business Messages supports delivery receipts and read receipts.
Receipts from users
Agents can receive the following receipts from users:
- Delivery receipts (
DELIVERED) indicate that the user received a message from the agent. - Read receipts (
READ) indicate that the user read a message from the agent.
Users can opt out of sending read receipts. If they opt out, they still receive read receipts from agents.
Receipts from agents
Users can receive read receipts from agents.
Read receipts (READ) indicate that the agent read a message from the user.
If more than one live agent is managing the conversation, a read receipt
means that at least one agent read the user's message.
Format
Receipts from users
Delivery receipts from users have the following format:
{ "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", }, }
Read receipts from users have the following format:
{ "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", }, }
For formatting and value options, see
UserMessage
and
Receipts.
Receipts from agents
The following code sends a read receipt from the agent:
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');
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)
For formatting and value options, see
ReceiptType.