我们将于 2024 年 7 月 31 日逐步淘汰 Google Business Messages。点击
此处了解详情。
发送和接收消息回执
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
消息回执会告知发件人他们已收到或
阅读。借助回执,用户可以看到代理已经阅读完消息的时间,
他们知道等待回复您的代理还可以决定用户何时收到
和阅读消息,以便跟踪收据指标,从而更好地进行互动
设计。
代理在 webhook 中收到收据。以相同的方式接收和处理收据
接收的方式
消息。
如果用户接收或阅读多个收据,
则单个载荷包含所有消息回执。
检查每个相关邮件的回执。
收据类型
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 商务
信息客户端库。
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 商务版
信息客户端库。
如需了解格式设置和值选项,请参阅 ReceiptType
。
如未另行说明,那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可,并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情,请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC):2024-10-14。
[null,null,["最后更新时间 (UTC):2024-10-14。"],[[["\u003cp\u003eMessage receipts allow users and agents to know when messages have been delivered and read, improving communication transparency.\u003c/p\u003e\n"],["\u003cp\u003eAgents receive receipts at their webhook, requiring them to be processed similarly to incoming messages, and can contain multiple receipts within a single payload.\u003c/p\u003e\n"],["\u003cp\u003eBusiness Messages supports two types of receipts: delivery receipts (\u003ccode\u003eDELIVERED\u003c/code\u003e) and read receipts (\u003ccode\u003eREAD\u003c/code\u003e), providing insight into message status.\u003c/p\u003e\n"],["\u003cp\u003eUsers retain the ability to receive read receipts from agents even if they opt out of sending them, ensuring they are aware of agent engagement.\u003c/p\u003e\n"],["\u003cp\u003eAgents can programmatically send read receipts to users using the Business Messages API, signaling their acknowledgment of user messages.\u003c/p\u003e\n"]]],[],null,["# Send and receive message receipts\n\nMessage receipts inform the sender that their messages were received or\nread. With receipts, users can see when an agent has read their messages, so\nthey know to expect a response. Your agent can also determine when users receive\nand read messages, so you can track receipt metrics for better interaction\ndesigns.\n\nAgents receive receipts at their webhook. Receive and process receipts the same\nway you [receive\nmessages](/business-communications/business-messages/guides/build/receive).\n\nIf a user sends multiple receipts at once, by receiving or reading multiple\nmessages at the same time, a single payload contains all the message receipts.\nCheck each receipt for the message it's associated with.\n\nReceipt types\n-------------\n\nBusiness Messages supports delivery receipts and read receipts.\n\n### Receipts from users\n\nAgents can receive the following receipts from users:\n\n- Delivery receipts (`DELIVERED`) indicate that the user received a message from the agent.\n- Read receipts (`READ`) indicate that the user read a message from the agent.\n\nUsers can opt out of sending read receipts. If they opt out, they still receive\nread receipts from agents.\n\n### Receipts from agents\n\nUsers can receive read receipts from agents.\n\nRead receipts (`READ`) indicate that the agent read a message from the user.\nIf more than one live agent is managing the conversation, a read receipt\nmeans that at least one agent read the user's message.\n\nFormat\n------\n\n### Receipts from users\n\nDelivery receipts from users have the following format: \n\n```component-pascal\n{\n \"agent\": \"brands/\u003cvar translate=\"no\"\u003eBRAND_ID\u003c/var\u003e/agents/\u003cvar translate=\"no\"\u003eAGENT_ID\u003c/var\u003e\",\n \"conversationId\": \"\u003cvar translate=\"no\"\u003eCONVERSATION_ID\u003c/var\u003e\",\n \"customAgentId\": \"\u003cvar translate=\"no\"\u003eCUSTOM_AGENT_ID\u003c/var\u003e\",\n \"sendTime\": \"\u003cvar translate=\"no\"\u003eSEND_TIME\u003c/var\u003e\",\n \"receipts\" : {\n \"receipts\": [\n {\n \"message\": \"conversations/\u003cvar translate=\"no\"\u003eCONVERSATION_ID\u003c/var\u003e/messages/\u003cvar translate=\"no\"\u003eMESSAGE_ID\u003c/var\u003e\",\n \"receiptType\": \"DELIVERED\",\n }\n ],\n \"createTime\": \"\u003cvar translate=\"no\"\u003eRECEIPTS_CREATION_TIME\u003c/var\u003e\",\n },\n}\n```\n\nRead receipts from users have the following format: \n\n```component-pascal\n{\n \"agent\": \"brands/\u003cvar translate=\"no\"\u003eBRAND_ID\u003c/var\u003e/agents/\u003cvar translate=\"no\"\u003eAGENT_ID\u003c/var\u003e\",\n \"conversationId\": \"\u003cvar translate=\"no\"\u003eCONVERSATION_ID\u003c/var\u003e\",\n \"customAgentId\": \"\u003cvar translate=\"no\"\u003eCUSTOM_AGENT_ID\u003c/var\u003e\",\n \"sendTime\": \"\u003cvar translate=\"no\"\u003eSEND_TIME\u003c/var\u003e\",\n \"receipts\" : {\n \"receipts\": [\n {\n \"message\": \"conversations/\u003cvar translate=\"no\"\u003eCONVERSATION_ID\u003c/var\u003e/messages/\u003cvar translate=\"no\"\u003eMESSAGE_ID\u003c/var\u003e\",\n \"receiptType\": \"READ\",\n }\n ],\n \"createTime\": \"\u003cvar translate=\"no\"\u003eRECEIPTS_CREATION_TIME\u003c/var\u003e\",\n },\n}\n```\n\nFor formatting and value options, see\n[`UserMessage`](/business-communications/business-messages/reference/rest/v1/UserMessage)\nand\n[`Receipts`](/business-communications/business-messages/reference/rest/v1/Receipts).\n\n### Receipts from agents\n\nThe following code sends a read receipt from the agent: \n\n### cURL\n\n```console\ncurl -X PATCH \\\n-H \"`./oauth2l header --json '\u003cvar translate=\"no\"\u003ePATH_TO_SERVICE_ACCOUNT_KEY\u003c/var\u003e' businessmessages`\" \\\n-H \"Content-Type: application/json\" \\\n-d '{\n \"receiptType\": \"READ\"\n}' \\\n\"https://businessmessages.googleapis.com/v1/conversations/\u003cvar translate=\"no\"\u003eCONVERSATION_ID\u003c/var\u003e/messages/\u003cvar translate=\"no\"\u003eMESSAGE_ID\u003c/var\u003e/receipt\"\n```\n\n### Node.js\n\n```javascript\nconst businessmessages = require('businessmessages');\nconst uuidv4 = require('uuid/v4');\nconst {google} = require('googleapis');\n\n// Initialize the Business Messages API\nlet bmApi = new businessmessages.businessmessages_v1.Businessmessages({});\n\n// Set the scope that we need for the Business Messages API\nconst scopes = [\n 'https://www.googleapis.com/auth/businessmessages',\n];\n\n// Set the private key to the service account file\nconst privatekey = require('\u003cvar translate=\"no\"\u003ePATH_TO_SERVICE_ACCOUNT_KEY\u003c/var\u003e');\n\n/**\n * Initializes the Google credentials for calling the\n * Business Messages API.\n */\nasync function initCredentials() {\n // Configure a JWT auth client\n let authClient = new google.auth.JWT(\n privatekey.client_email,\n null,\n privatekey.private_key,\n scopes,\n );\n\n return new Promise(function(resolve, reject) {\n // Authenticate request\n authClient.authorize(function(err, tokens) {\n if (err) {\n reject(false);\n } else {\n resolve(authClient);\n }\n });\n });\n}\n\n/**\n * Sends a read receipt to a specific messageId.\n *\n * @param {string} conversationId The unique id for this user and agent.\n * @param {string} messageId The unique id for this message.\n */\nasync function sendReadReceipt(conversationId, messageId) {\n let authClient = await initCredentials();\n\n // Create the payload for sending a read receipt\n let apiParams = {\n auth: authClient,\n name: 'conversations/' + conversationId + '/messages/' + messageId + '/receipt',\n resource: {\n receiptType:'READ'\n }\n };\n\n // Call the updateReceipt create function using the\n // Business Messages client library\n bmApi.conversations.messages.updateReceipt(apiParams,\n {auth: authClient}, (err, response) =\u003e {\n console.log(err);\n console.log(response);\n });\n}\n\nsendReadReceipt('\u003cvar translate=\"no\"\u003eCONVERSATION_ID\u003c/var\u003e', '\u003cvar translate=\"no\"\u003eMESSAGE_ID\u003c/var\u003e');\n```\nThis code is based on the [Node.js\nBusiness Messages client library](https://github.com/google-business-communications/nodejs-businessmessages).\n\n### Java\n\n```java\nimport com.google.api.client.googleapis.services.AbstractGoogleClientRequest;\nimport com.google.api.client.http.HttpBackOffUnsuccessfulResponseHandler;\nimport com.google.api.client.http.HttpRequest;\nimport com.google.api.client.googleapis.auth.oauth2.GoogleCredential;\nimport com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;\nimport com.google.api.client.http.HttpTransport;\nimport com.google.api.client.json.jackson2.JacksonFactory;\nimport com.google.api.client.util.ExponentialBackOff;\nimport com.google.api.services.businessmessages.v1.Businessmessages;\nimport com.google.api.services.businessmessages.v1.model.BusinessMessagesReceipt;\n\nimport com.google.api.services.businessmessages.v1.model.*;\nimport java.io.FileInputStream;\nimport java.util.Arrays;\nimport java.util.UUID;\n\npublic class ReadReceiptSample {\n /**\n * Initializes credentials used by the Business Messages API.\n */\n private static Businessmessages.Builder getBusinessMessagesBuilder() {\n Businessmessages.Builder builder = null;\n try {\n GoogleCredential credential = GoogleCredential\n .fromStream(new FileInputStream(\"\u003cvar translate=\"no\"\u003ePATH_TO_SERVICE_ACCOUNT_KEY\u003c/var\u003e\"));\n\n credential = credential.createScoped(Arrays.asList(\n \"https://www.googleapis.com/auth/businessmessages\"));\n\n credential.refreshToken();\n\n HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();\n JacksonFactory jsonFactory = JacksonFactory.getDefaultInstance();\n\n // Create instance of the Business Messages API\n builder = new Businessmessages\n .Builder(httpTransport, jsonFactory, null)\n .setApplicationName(\"Sample Application\");\n\n // Set the API credentials and endpoint\n builder.setHttpRequestInitializer(credential);\n } catch (Exception e) {\n e.printStackTrace();\n }\n\n return builder;\n }\n\n public static void main(String args[]) {\n try{\n String conversationId = \"\u003cvar translate=\"no\"\u003eCONVERSATION_ID\u003c/var\u003e\";\n String messageId = \"\u003cvar translate=\"no\"\u003eMESSAGE_ID\u003c/var\u003e\";\n\n // Create client library reference\n Businessmessages.Builder builder = getBusinessMessagesBuilder();\n\n // Create a new read receipt\n Businessmessages.Conversations.Messages.UpdateReceipt request\n = builder.build().conversations().messages()\n .updateReceipt(\"conversations/\" + conversationId + \"/messages/\" + messageId + \"/receipt\",\n new BusinessMessagesReceipt().setReceiptType(\"READ\"));\n\n // Set up retries with exponential backoff\n HttpRequest httpRequest =\n ((AbstractGoogleClientRequest) request).buildHttpRequest();\n\n httpRequest.setUnsuccessfulResponseHandler(new\n HttpBackOffUnsuccessfulResponseHandler(\n new ExponentialBackOff()));\n\n // Execute request\n httpRequest.execute();\n } catch (Exception e) {\n e.printStackTrace();\n }\n }\n}\n```\nThis code is based on the [Java Business\nMessages client library](https://github.com/google-business-communications/java-businessmessages).\n\n### Python\n\n```python\nfrom oauth2client.service_account import ServiceAccountCredentials\nfrom businessmessages import businessmessages_v1_client as bm_client\nfrom businessmessages.businessmessages_v1_messages import (\n BusinessMessagesReceipt)\n\ncredentials = ServiceAccountCredentials.from_json_keyfile_name(\n '\u003cvar translate=\"no\"\u003ePATH_TO_SERVICE_ACCOUNT_KEY\u003c/var\u003e',\n scopes=['https://www.googleapis.com/auth/businessmessages'])\n\nclient = bm_client.BusinessmessagesV1(credentials=credentials)\n\nconversation_id = '\u003cvar translate=\"no\"\u003eCONVERSATION_ID\u003c/var\u003e'\nmessage_id = '\u003cvar translate=\"no\"\u003eMESSAGE_ID\u003c/var\u003e'\n\nread_receipt = BusinessMessagesReceipt(\n name=f\"conversations/{conversation_id}/messages/{message_id}/receipt\",\n receiptType=BusinessMessagesReceipt.ReceiptTypeValueValuesEnum.READ\n)\n\n# Send the message\nbm_client.BusinessmessagesV1.ConversationsMessagesService(\n client=client).UpdateReceipt(request=read_receipt)\n```\nThis code is based on the [Python Business\nMessages client library](https://github.com/google-business-communications/python-businessmessages).\n\nFor formatting and value options, see\n[`ReceiptType`](/business-communications/business-messages/reference/rest/v1/ReceiptType)."]]