摘要

本文涵盖了关于使用 Wati API 和 webhooks 的常见问题，包括如何通过 API 添加联系人、在哪里查找 API 令牌、如何通过 webhook 事件启用已读回执，以及如何通过 API 管理 webhooks。

重要提示： 全局 Webhooks 仅支持 WhatsApp 消息。若要接收 Instagram 或 Facebook Messenger 消息的提醒或触发操作，请在聊天机器人流程中使用 Webhook 节点。

常见问题解答 (FAQs)

1. 我可以通过 API 添加联系人吗？

可以。请使用以下端点之一：

v3（推荐）： POST https://live-mt-server.wati.io/api/ext/v3/contacts
旧版 v1： POST https://live-mt-server.wati.io/{tenantId}/api/v1/addContact/{whatsappNumber}

建议所有新集成使用 v3。v1 为旧版，但仍受支持。

2. 我在哪里可以找到我的 Wati API 令牌？

请前往您 Wati 账户中的 Connector > API > Create API Token。您可以在此处找到您的访问令牌（Access Token）和 API 端点 URL。

对于 v3 端点，请创建具有适当作用域（Scope）的令牌：

作用域	用途
`contactsv3:*`	联系人操作
`conversationsv3:*`	对话操作
`messagetemplatev3:write`	发送模板

3. 如何启用已读回执？

启用 sentMessageREAD_v2 webhook 事件，以便在您发送的消息被接收方阅读时接收回调。

设置步骤：

前往您 Wati 账户中的 Connector > Webhooks。
添加您的 webhook URL。
启用 sentMessageREAD_v2 事件。

Wati webhooks 可以通过回调 URL 为以下情况通知您：

接收消息
发送消息（模板和会话消息）
消息状态更新（已发送 / 已送达 / 已读）

sentMessageREAD_v2 — 示例负载

{
  "eventType": "sentMessageREAD_v2",
  "statusString": "Read",
  "id": "1a2b3b4d5e6f7g8h9i10j",
  "localMessageId": "...",
  "whatsappMessageId": "abcdefghi_jklmnop",
  "conversationId": "a1b2c3d4e5f6g7h8i9j10",
  "ticketId": "m1n2o3p4q5r6s7t8u9v10",
  "channelId": "...",
  "channelPhoneNumber": "85264318722",
  "text": null,
  "type": "template",
  "timestamp": "1665645642",
  "assigneeId": null,
  "operatorEmail": "[email protected]",
  "bsuid": "...",
  "parentBsuid": "...",
  "username": "..."
}

BSUID 事件变体

Wati 支持 webhook 事件的 _bsuid 变体。这些负载包含 bsuid、parentBsuid 和 username 字段，用于按 BSUID 识别联系人——当您的系统中通过 BSUID 而非电话号码来引用联系人时，这非常有用。

4. 如何通过 API 管理 webhooks？

您可以以编程方式创建、列出、更新和删除 webhooks。

创建 webhook (v2)：

POST https://live-mt-server.wati.io/{tenantId}/api/v2/webhookEndpoints

列出、获取、更新和删除 webhooks (v3 — 推荐)：

https://live-mt-server.wati.io/api/ext/v3/webhooks

v3 webhook 管理路径中不包含 /{tenantId}/。建议所有新集成使用 v3。

有关详细信息，请参阅 Wati Webhooks 文档。

常规常见问题解答：Wati API 和 Webhooks

摘要