跳转到主要内容

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

更新于今天

摘要

当您使用 Wati 的 API 发送模板消息时，跟踪它们的状态（例如，已发送、已送达、已读、已回复或失败）非常重要。这有助于您了解消息性能、排除问题并更有效地管理客户互动。本指南介绍了如何发送模板消息并使用 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 发送的每条模板消息，并允许您根据状态更新（例如，已发送、已送达、已读、已回复或失败）采取操作。

相关文章
使用 Zapier 网页hooks 和 Wati 发送 WhatsApp 消息
将Wati连接到Eber：分步指南
如何使用订单状态模板 Wati API 通知客户
常规常见问题解答：Wati Apis和Webhooks
如何设置和使用 Wati 中的 Webhooks
这是否解答了您的问题？