跳转到主要内容

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

一周前更新

摘要

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

在使用 API 发送营销活动后，您可以随时在 Wati 的营销活动概览中查看其效果。但是，您也可以使用 Wati Webhook 通过您自己的系统实时跟踪这些营销活动的消息状态和传送事件。

这种方法可以帮助您监控消息性能、排查传送问题以及通过您的应用程序管理客户互动。本指南介绍了如何发送模板消息以及如何使用 Webhook 跟踪其生命周期。

说明

发送模板消息

要使用 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 事件中跟踪消息的唯一标识符。保存此值，因为它会将消息的所有状态更新链接起来。

使用 Webhook 跟踪消息状态

发送消息后，Wati 会为每个状态更新发送 Webhook 事件。使用 localMessageId 将这些事件与原始消息匹配。

1. 模板消息已发送

  • 触发时间： 消息已从 Wati 成功发送

  • 事件： templateMessageSent_v2

  • 状态： SENT

Webhook Payload 示例

{
  "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. 消息已送达

  • 触发时间： 消息已发送给收件人

  • 事件： sentMessageDELIVERED_v2

  • 状态： Delivered

Webhook Payload 示例

{
  "eventType": "sentMessageDELIVERED_v2",
  "statusString": "Delivered",
  "localMessageId": "d38f0c3a-e833-4725-a894-53a2b1dc1af6",
  "id": "640c8fd48b67615f886237b8",
  "whatsappMessageId": "gBEGkXmJQZVJAgkRHwjjZsITS6M",
  "timestamp": "1678544854",
  "operatorEmail": "[email protected]"
}

3. 消息已读

  • 触发时间： 收件人已阅读消息

  • 事件： sentMessageREAD_v2

  • 状态： Read

Webhook Payload 示例

{
  "eventType": "sentMessageREAD_v2",
  "statusString": "Read",
  "localMessageId": "d38f0c3a-e833-4725-a894-53a2b1dc1af6",
  "id": "640c8fd48b67615f886237b8",
  "whatsappMessageId": "gBEGkXmJQZVJAgkRHwjjZsITS6M",
  "timestamp": "1678545043",
  "operatorEmail": "[email protected]"
}

4. 消息已回复

  • 触发时间： 收件人已回复消息

  • 事件： sentMessageREPLIED_v2

  • 状态： Replied

Webhook Payload 示例

{
  "eventType": "sentMessageREPLIED_v2",
  "statusString": "Replied",
  "localMessageId": "d38f0c3a-e833-4725-a894-53a2b1dc1af6",
  "id": "640c8fd48b67615f886237b8",
  "whatsappMessageId": "gBEGkXmJQZVJAgkRHwjjZsITS6M",
  "timestamp": "1678545074",
  "operatorEmail": "[email protected]"
}

5. 收到消息

  • 触发时间： 用户向您的 Wati 号码发送消息

  • 事件： messageReceived

  • 状态： Received

用例：

  • 跟踪用户的回复

  • 捕获来自模板消息的快速回复按钮点击

Webhook Payload 示例

{
  "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 Payload 示例

{
  "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]"
}

如何在 Wati 中设置 Webhook

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

  1. 登录到您的 Wati 仪表板

  2. 转到连接器 → Webhook

  3. 单击添加 Webhook

  4. 输入您的 Webhook URL

  5. 将状态设置为已启用

  6. 选择所需的事件：

    • 模板消息已发送

    • 已送达

    • 已读

    • 已回复

    • 失败

最终说明

  • 发送消息时，始终存储 localMessageId

  • 使用它将所有 Webhook 事件映射到同一条消息

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

通过正确设置 Webhook，您可以可靠地跟踪通过 Wati 发送的每条模板消息，并根据实时更新采取措施。

常见问题 (FAQ)

发送模板消息

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

您可以通过调用 sendTemplateMessage V2 端点并使用所需的标头和 JSON 正文（包括 template_name、broadcast_name 和 parameters 等字段）来使用 Wati 的 API 发送模板消息。

2. API 响应中 localMessageId 的目的是什么？

localMessageId 是 API 响应中返回的唯一标识符，用于在所有 Webhook 事件中跟踪消息。应存储此值，因为它会将所有状态更新链接到同一条消息。

使用 Webhook 跟踪消息状态

3. 如何在 Wati 中跟踪模板消息的生命周期？

您可以使用 Wati 在发送消息后发送的 Webhook 事件来跟踪模板消息的生命周期。每个 Webhook 事件都包含一个 localMessageId，使您可以将该事件与原始消息匹配起来并跟踪其状态更新。

4. 针对不同的模板消息状态触发哪些 Webhook 事件？

Wati 针对模板消息状态触发以下 Webhook 事件：

  • 消息成功发送时，触发 templateMessageSent_v2（状态：已发送）

  • 消息已送达时，触发 sentMessageDELIVERED_v2（状态：已送达）

  • 消息已读时，触发 sentMessageREAD_v2（状态：已读）

  • 收件人已回复时，触发 sentMessageREPLIED_v2（状态：已回复）

  • 用户向您的 Wati 号码发送消息时，触发 messageReceived（状态：已收到）

  • 消息发送失败时，触发 templateMessageFailed（状态：失败）

5. 何时触发 messageReceived Webhook 事件，其用途是什么？

当用户向您的 Wati 号码发送消息时，会触发 messageReceived Webhook 事件。它可用于跟踪用户的回复和捕获来自模板消息的快速回复按钮点击。

Webhook 设置

6. 如何在 Wati 中设置 Webhook 以接收消息状态事件？

要在 Wati 中设置 Webhook：

  • 登录到您的 Wati 仪表板。

  • 转到连接器 → Webhook。

  • 单击添加 Webhook。

  • 输入您的 Webhook URL。

  • 将状态设置为已启用。

  • 选择所需的事件，例如模板消息已发送、已送达、已读、已回复和失败。

消息跟踪的最佳实践

7. 为什么要发送消息时存储 localMessageId？

您应该存储 localMessageId，因为这是将所有 Webhook 事件映射到同一条消息并跟踪其完整生命周期所必需的。

8. 如何使用 Webhook 事件构建完整的消息生命周期？

您可以通过组合由同一 localMessageId 链接的多个 Webhook 事件来构建完整的消息生命周期，该生命周期提供单个模板消息的所有状态更新。

9. 为什么 Webhook 设置对于跟踪 Wati 中的模板消息非常重要？

Webhook 设置非常重要，因为它能够实时跟踪通过 Wati 发送的每条模板消息，并允许您根据状态更新（例如已发送、已送达、已读、已回复或失败）采取措施。

相关文章
整合 Wati 与 Klaviyo
使用 Zapier 网页hooks 和 Wati 发送 WhatsApp 消息
将Wati连接到Eber：分步指南
常规常见问题解答：Wati Apis和Webhooks
如何设置和使用 Wati 中的 Webhooks
这是否解答了您的问题？