摘要
在使用 WATI 的 发送模板消息 API 发送模板消息时，跟踪它们的状态——已发送、已投递、已阅读、已回复或失败至关重要。这可以确保更好地了解并管理客户交互的情况。
说明
发送模板消息
要使用 WATI 的 API 发送模板消息，请使用 sendTemplateMessage V2 端点。
示例 cURL 请求
curl --location 'https://live-server-123.wati.io/api/v2/sendTemplateMessage?whatsappNumber=<whatsappNumber>' \
--header 'Authorization: Bearer <Token>' \
--header 'Content-Type: application/json' \
--data '{
"template_name": "update_for_you",
"broadcast_name": "JPTestBroadcast",
"parameters": []
}'示例 API 响应
{
"result": true,
"error": null,
"templateName": "update_for_you",
"receivers": [
{
"localMessageId": "d38f0c3a-e833-4725-a894-53a2b1dc1af6",
"waId": "<whatsappNumber>",
"isValidWhatsAppNumber": true,
"errors": []
}
],
"parameters": []
}关键字段：
localMessageId– 通过 webhooks 跟踪消息状态的唯一标识符。
通过 Webhooks 跟踪消息状态
1. 模板消息已发送
触发条件： 成功发送模板消息时。
Webhook 事件：
templateMessageSent_v2关键字段：
localMessageId状态字符串：
"SENT"
示例 Webhook 有效负载
{
"eventType": "templateMessageSent_v2",
"localMessageId": "d38f0c3a-e833-4725-a894-53a2b1dc1af6",
"id": "640c8fd48b67615f886237b8",
"whatsappMessageId": "gBEGkXmJQZVJAgkRHwjjZsITS6M",
"templateId": "63766ae83b2e064905789c63",
"templateName": "update_for_you",
"created": "2023-03-11T14:27:32.9655388Z",
"statusString": "SENT",
"sourceType": "API"
}2. 消息已投递
触发条件： 消息已成功发送至收件人。
Webhook 事件：
sentMessageDELIVERED_v2状态字符串：
"Delivered"
示例 Webhook 有效负载
{
"eventType": "sentMessageDELIVERED_v2",
"statusString": "Delivered",
"localMessageId": "d38f0c3a-e833-4725-a894-53a2b1dc1af6",
"id": "640c8fd48b67615f886237b8",
"whatsappMessageId": "gBEGkXmJQZVJAgkRHwjjZsITS6M",
"timestamp": "1678544854",
"operatorEmail": "[email protected]"
}3. 消息已阅读
触发条件： 收件人已阅读消息。
Webhook 事件：
sentMessageREAD_v2状态字符串：
"Read"
示例 Webhook 有效负载
{
"eventType": "sentMessageREAD_v2",
"statusString": "Read",
"localMessageId": "d38f0c3a-e833-4725-a894-53a2b1dc1af6",
"id": "640c8fd48b67615f886237b8",
"whatsappMessageId": "gBEGkXmJQZVJAgkRHwjjZsITS6M",
"timestamp": "1678545043",
"operatorEmail": "[email protected]"
}4. 消息已回复
触发条件： 收件人回复了消息。
Webhook 事件：
sentMessageREPLIED_v2状态字符串：
"Replied"
示例 Webhook 有效负载
{
"eventType": "sentMessageREPLIED_v2",
"statusString": "Replied",
"localMessageId": "d38f0c3a-e833-4725-a894-53a2b1dc1af6",
"id": "640c8fd48b67615f886237b8",
"whatsappMessageId": "gBEGkXmJQZVJAgkRHwjjZsITS6M",
"timestamp": "1678545074",
"operatorEmail": "[email protected]"
}5. 收到消息
触发条件： 用户将消息发送到您的 WATI 号码。
Webhook 事件：
messageReceived使用情况： 可用于跟踪与 模板消息已发送 一起使用以跟踪快速回复按钮点击情况。
示例 Webhook 有效负载
{
"eventType": "messageReceived",
"statusString": "Received",
"localMessageId": "fd29c1f-9033-59b2-7d72-5ac964c4c8a7",
"whatsappMessageId": "wamid.HBgMOAE4NjY4NDkzNjAxFAIAERgSOTEENzFCNjEwMkNDNENGQUJGAA==",
"text": "Hello, I need help!",
"timestamp": "1665645642",
"operatorEmail": "[email protected]"
}
6. 模板消息失败
触发条件： 模板消息发送失败。
Webhook 事件：
templateMessageFailed失败详细信息： 包括失败代码和错误消息。
示例 Webhook 有效负载
{
"eventType": "templateMessageFailed",
"statusString": "Failed",
"localMessageId": "fd29c1f-9033-59b2-7d72-5ac964c4c8a7",
"failedCode": "131026",
"failedDetail": "Message undeliverable",
"id": "66b2531d4931581381944612",
"whatsappMessageId": "wamid.HBgMOAE4NjY4NDkzNjAxFAIAERgSOTEENzFCNjEwMkNDNENGQUJGAA==",
"timestamp": "1665645642",
"operatorEmail": "[email protected]"
}
如何设置 Webhooks
登录 WATI 仪表板
导航到 Webhooks
点击“添加 Webhook”
输入您的 webhook URL
将状态 설정为“启用”
选择所需事件（例如，模板消息已发送、已投递、已阅读等）。
通过遵循这些步骤，您可以有效地跟踪并管理通过 WATI API 发送的所有模板消息。
常见问题 (FAQ)
发送模板消息
1. 如何使用 WATI 的 API 发送模板消息？
→ 要发送模板消息，请使用 sendTemplateMessage V2 端点。您需要在请求中包含 WhatsApp 号码、模板名称和授权令牌。有关详细信息，请参考文档中的示例 cURL 请求。
2. 在 API 请求中需要包含哪些参数？
→ 必须包含的参数为 whatsappNumber、template_name、broadcast_name 和 parameters（如果适用）。请确保提供有效的授权令牌。
跟踪消息状态
3. 如何跟踪已发送消息的状态？
→ 每个 API 响应都包含 localMessageId，它可以通过 webhooks 用于跟踪消息状态。Webhooks 提供已发送、已投递、已阅读、已回复和失败的实时更新。
4. 哪个 webhook 事件跟踪消息已发送？
→ templateMessageSent_v2 webhook 事件跟踪消息已发送。它包含 localMessageId、whatsappMessageId 和其他元数据。
5. 如何知道消息已投递？
→ sentMessageDELIVERED_v2 webhook 事件表示消息已投递。statusString 字段的值为 Delivered。
6. 如何跟踪消息已阅读？
→ 当收件人阅读消息时触发 sentMessageREAD_v2 webhook 事件。statusString 字段的值为 Read。
7. 能否跟踪用户是否回复消息？
→ 可以，当收件人回复消息时触发 sentMessageREPLIED_v2 webhook 事件。
处理失败情况
8. 模板消息发送失败会发生什么？
→ 如果消息发送失败，templateMessageFailed webhook 事件会被触发。它会提供 failedCode 和 failedDetail，说明失败原因。
9. 可以在哪里找到有关失败代码的详细信息？
→ 失败代码包含在 templateMessageFailed webhook 有效负载中。您可以参考 Meta 的文档，获取对每个错误代码的详细说明。
配置 Webhooks
10. 如何在 WATI 中启用 webhooks？
→ 要启用 webhooks：
登录 WATI 仪表板。
导航到
Webhooks。点击
添加 Webhook。输入您的 webhook URL。
将状态设置为
Enabled。选择您想要跟踪的 webhook 事件。
11. 要完成消息跟踪，应该启用哪些 webhook 事件？
→ 要跟踪整个消息生命周期，请启用以下事件：
templateMessageSent_v2sentMessageDELIVERED_v2sentMessageREAD_v2sentMessageREPLIED_v2messageReceivedtemplateMessageFailed