跳转到主要内容

如何使用 Wati webhooks 跟踪模板消息的发送和消息状态

摘要

当您使用 Wati API 发送模板消息时，您可能希望使用 webhook 来追踪其状态（例如：已发送、已送达、已读、已回复或失败），而不是仅仅依赖 Wati 内置的营销活动分析。

通过 API 发送营销活动后，您始终可以在 Wati 的营销活动概览 (Campaign Overview) 中查看其表现。此外，您还可以使用 Wati webhooks，通过您自己的系统实时追踪这些营销活动的消息状态和送达事件。

此方法有助于您监控消息表现、排查送达问题，并通过您的应用程序管理客户互动。本指南介绍了如何发送模板消息并使用 webhook 追踪其生命周期。

注意：有关 Wati webhooks 的更多信息，请参考 Wati 开发人员文档。

说明

发送模板消息

要使用 Wati API 发送模板消息，请使用 sendTemplateMessage V2 端点。

cURL 请求示例

curl --location 'https://live-mt-server.wati.io/{tenant_id}/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：用于在 webhook 事件中追踪消息的唯一标识符。请保存此值，因为它会将该消息的所有状态更新关联起来。

使用 webhooks 追踪消息状态

消息发送后，Wati 会针对每次状态更新发送 webhook 事件。请使用 localMessageId 将这些事件与原始消息进行匹配。

1. 模板消息已发送

  • 触发条件：消息已从 Wati 成功发送

  • 事件： templateMessageSent_v2

  • 状态： SENT

Webhook 有效负载示例

{
  "eventType": "templateMessageSent_v2_bsuid",
  "localMessageId": "84689938-5e2-877821d672c2",
  "id": "693fd8ee21f81",
  "whatsappMessageId": "wamid.HBgNODEYEjQ3RDMzQzM2QjM3QjU1ODQ4RQA=",
  "templateId": "6929b",
  "templateName": "test_jm4",
  "created": "2025-12-15T09:46:23.4083984Z",
  "conversationId": "68b68470e93cc",
  "ticketId": "693fd6ab545f82",
  "text": "Make your messages personal using variables like name and get more replies!",
  "operatorEmail": "[email protected]",
  "waId": "86151285",
  "type": "template",
  "statusString": "SENT",
  "sourceType": "WEB",
  "headerLink": null,
  "headerType": null,
  "channelId": null,
  "channelPhoneNumber": "174742",
  "bsuid": "HK.xxxxxxxxxxxxx",
  "parentBsuid": "HK.ENT.xxxxxxxxxxxxx",
  "username": "@bob"
}

模板发送 webhook 现在包含按钮信息

模板发送 webhook (Template Sent webhook) 现在包含 WhatsApp 模板中配置的按钮信息。这使您可以识别与已发送模板消息相关联的按钮文本。

此功能适用于 Pro、Business 和 Enterprise 套餐的用户。

包含哪些按钮信息？

Webhook 有效负载可以包含来自 WhatsApp 模板的以下按钮信息：

  • 快速回复按钮文本

  • 链接按钮文本

当您通过 API 获取模板信息时，响应中也会包含为模板配置的按钮文本。

2. 消息已送达

  • 触发条件：消息已送达给接收者

  • 事件： sentMessageDELIVERED_v2

  • 状态： Delivered

Webhook 有效负载示例

{
  "eventType": "sentMessageDELIVERED_v2",
  "statusString": "Delivered",
  "localMessageId": "16bf77ae-79e8-691eb4b",
  "id": "693fd65f99391640",
  "whatsappMessageId": "wamid.HBgNODYxMzEzMzg4Nzg2MDU0OEM0NTYxRTlBMwA=",
  "conversationId": "68cba32b3349e",
  "ticketId": "693f7a0a8545f54",
  "text": "hello",
  "type": "text",
  "timestamp": "1765791326",
  "assigneeId": "65a105b5cf65262",
  "operatorEmail": "derre.ai",
  "channelId": null,
  "channelPhoneNumber": "17742"
}

3. 消息已读

  • 触发条件：接收者已阅读消息

  • 事件： sentMessageREAD_v2

  • 状态： Read

Webhook 有效负载示例

{
  "eventType": "sentMessageREAD_v2",
  "statusString": "Read",
  "localMessageId": "16bf77ae-79e691eb4b",
  "id": "693fd65f961dc81779391640",
  "whatsappMessageId": "wamid.HBgNODYxMzEABEYEjVCNzg2MDU0OEM0NTYxRTlBMwA=",
  "conversationId": "68cba3db12b3349e",
  "ticketId": "693fd64d1d45f54",
  "text": "hello",
  "type": "text",
  "timestamp": "17651326",
  "assigneeId": "65a10905cf65262",
  "operatorEmail": "[email protected]",
  "channelId": null,
  "channelPhoneNumber": "174742"
}

4. 消息已回复

  • 触发条件：接收者已回复消息

  • 事件： sentMessageREPLIED_v2

  • 状态： Replied

Webhook 有效负载示例

{
  "eventType": "sentMessageREPLIED_v2",
  "statusString": "Replied",
  "localMessageId": "16bf77ae-79e691eb4b",
  "id": "693fd65f961dc81779391640",
  "whatsappMessageId": "wamid.HBgNODYxMzEABEYEjVCNzg2MDU0OEM0NTYxRTlBMwA=",
  "conversationId": "68cba3db12b3349e",
  "ticketId": "693fd64d1d45f54",
  "text": "hello",
  "type": "text",
  "timestamp": "17651326",
  "assigneeId": "65a10905cf65262",
  "operatorEmail": "[email protected]",
  "channelId": null,
  "channelPhoneNumber": "174742"
}

5. 消息已收到

  • 触发条件：用户向您的 Wati 号码发送了消息

  • 事件： messageReceived

  • 状态： Received

使用场景：

  • 追踪用户的回复

  • 捕获模板消息中的快速回复按钮点击事件

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. 模板消息失败

  • 触发条件：消息发送失败

  • 事件： templateMessageFailed

  • 状态： Failed

Webhook 有效负载示例

{
  "eventType": "templateMessageFailed",
  "statusString": "Failed",
  "localMessageId": "fd29c1f-9033-59b2-7d72-5ac964c4c8a7",
  "failedCode": "131026",
  "failedDetail": "Message undeliverable",
  "id": "66b2531d4931581381944612",
  "whatsappMessageId": "wamid.HBgMOAE4NjY4NDkzNjAxFAIAERgSOTEENzFCNjEwMkNDNENGQUJGAA==",
  "conversationId": "66b1fb044045cedb1f19538e",
  "ticketId": "66bdfba190194752bb7326d7",
  "text": null,
  "type": "template",
  "timestamp": "1665645642",
  "assigneeId": null,
  "operatorEmail": "[email protected]"
}

如何在 Wati 中设置 webhooks

请按照以下步骤开始接收 webhook 事件：

  • 登录您的 Wati 账户

  • 前往 Connectors（连接器） → Webhooks

  • 点击 Add Webhook（添加 Webhook）

  • 输入您的 webhook URL

  • 将状态设置为 Enabled（启用）

  • 选择所需的事件：

    • Template Message Sent（模板消息已发送）

    • Delivered（已送达）

    • Read（已读）

    • Replied（已回复）

    • Failed（失败）

最后说明

  • 发送消息时务必存储 localMessageId

  • 使用该 ID 将所有 webhook 事件映射到同一条消息

  • 结合多个 webhook 事件以构建完整的消息生命周期

通过正确设置 webhooks，您可以可靠地追踪每一条通过 Wati 发送的模板消息，并根据实时更新采取行动。

常见问题解答 (FAQs)

发送和追踪模板消息

1. 如何使用 Wati API 发送模板消息？

使用 sendTemplateMessage V2 端点通过 Wati API 发送模板消息。

2. 什么是 localMessageId，为什么要保存它？

localMessageId 是消息的唯一标识符。请保存它，因为 Wati 使用它将 webhook 事件与原始消息相关联，并在其整个生命周期内追踪其状态。

3. 如何使用 Wati webhooks 追踪模板消息状态？

配置 Wati webhooks 以接收模板消息的实时事件。使用 localMessageId 将每个 webhook 事件与原始消息匹配。

4. 哪些 webhook 事件可以追踪模板消息生命周期？

可用的 webhook 事件包括：

  • templateMessageSent_v2 — 消息已成功发送。

  • sentMessageDELIVERED_v2 — 消息已送达。

  • sentMessageREAD_v2 — 接收者已阅读消息。

  • sentMessageREPLIED_v2 — 接收者已回复消息。

  • templateMessageFailed — 消息发送失败。

  • messageReceived — 用户向您的 Wati 号码发送了消息。

5. messageReceived webhook 有什么用途？

messageReceived webhook 可用于追踪用户的回复，并捕获模板消息中的快速回复按钮点击事件。

6. “模板已发送” webhook 中包含哪些按钮信息？

“模板已发送” webhook 可以包含在 WhatsApp 模板中配置的快速回复按钮文本和链接按钮文本。模板信息的 API 响应中也包含了配置的按钮文本。

7. 哪些 Wati 套餐支持在“模板已发送” webhook 中包含按钮信息？

按钮信息功能适用于 Pro、Business 和 Enterprise 套餐的用户。

8. 如何在 Wati 中设置 webhooks 以追踪模板消息？

在您的 Wati 账户中前往 Connectors（连接器） → Webhooks，点击 Add Webhook（添加 Webhook），输入您的 webhook URL，将状态设置为 Enabled（启用），并选择所需的事件：Template Message Sent（模板消息已发送）、Delivered（已送达）、Read（已读）、Replied（已回复） 和 Failed（失败）。

9. 如何追踪模板消息的完整生命周期？

在发送消息时存储 localMessageId，并使用它来映射所有相关的 webhook 事件。结合这些事件，您可以追踪消息是已发送、已送达、已读、已回复还是失败。

相关文章
这是否解答了您的问题？