概要

Wati 提供了应用程序编程接口 (API)，让您可以将 Wati 与现有系统连接，实现消息自动发送、管理联系人、运行营销活动，并以编程方式使用其他 Wati 功能。

本指南概述了可用的 Wati API，包括其端点、支持的 API 版本以及指向其他开发者资源的链接。

重要提示：建议所有新的集成均使用 v3 版本。旧版 v1 和 v2 端点在支持的情况下仍可继续使用。

操作指南

1. 了解 Wati API 版本和端点

Wati API 端点根据 API 版本的不同使用不同的 URL 格式。

基础 URL： https://live-mt-server.wati.io

API 版本	URL 路径格式	路径中是否需要租户 ID？
v3	`/api/ext/v3/...`	否
v1	`/{tenantId}/api/v1/...`	是
v2	`/{tenantId}/api/v2/...`	是

对于 v1 和 v2 端点，请将 {tenantId} 替换为您的 Wati 租户 ID。对于 v3 端点，URL 路径中不包含租户 ID。

如果所需操作支持，请在新的集成中使用 v3 版本。如果 v3 中不提供所需操作，则使用旧版端点。

2. 创建 API 令牌

您需要一个 API 令牌来对 Wati API 端点的请求进行身份验证。

创建 API 令牌的步骤：

登录您的 Wati 账户。
前往 Connector (连接器) > API。
选择 Create API Token (创建 API 令牌)。
创建一个具有您想要执行的 API 操作所需权限的令牌。

对于 v3 端点，请选择所需的令牌范围 (scope)：

令牌范围	用途
`contactsv3:*`	联系人操作
`conversationsv3:*`	会话操作
`messagetemplatev3:write`	发送消息模板

请确保您的令牌具有您要使用的端点所需的权限范围。

3. 探索可用的 Wati API

以下章节按功能对 Wati API 进行了分组。每个表格列出了可用的操作及其文档化的端点路径。

3.1 频道 API (Channels API)

使用频道 API 获取有关您已连接的 WhatsApp 号码的信息。

操作	方法	v3 端点	v1 端点
列出已连接的 WhatsApp 号码	GET	`/api/ext/v3/channels`	`/{tenantId}/api/v1/whatsApp/phoneNumbers`

3.2 消息 API (Messaging API)

使用消息 API 发送消息、检索会话历史记录并管理会话。

操作	方法	v3 端点	v1 端点
获取联系人的消息历史记录	GET	`/api/ext/v3/conversations/{target}/messages`	`/{tenantId}/api/v1/getMessages/{target}`
发送会话文本消息	—	v3 可用	`/{tenantId}/api/v1/sendSessionMessage/{whatsappNumber}`
发送会话文件	—	v3 可用	`/{tenantId}/api/v1/sendSessionFile/{whatsappNumber}`
通过 URL 发送会话文件	—	v3 可用	`/{tenantId}/api/v1/sendSessionFileViaUrl/{whatsappNumber}`
发送模板消息	—	v3 可用	`/{tenantId}/api/v1/sendTemplateMessage`
批量发送模板消息	—	v3 可用	`/{tenantId}/api/v1/sendTemplateMessages`
使用 CSV 文件发送模板消息	POST	—	`/{tenantId}/api/v1/sendTemplateMessageCSV`
发送交互式按钮消息	—	v3 可用	`/{tenantId}/api/v1/sendInteractiveButtonsMessage/{whatsappNumber}`
发送交互式列表消息	—	v3 可用	`/{tenantId}/api/v1/sendInteractiveListMessage/{whatsappNumber}`
发送交互式行动号召 (CTA) URL 消息	POST	—	`/{tenantId}/api/v1/sendInteractiveCtaUrlMessage`
更新会话状态	PUT	`/api/ext/v3/conversations/{target}/status`	`/{tenantId}/api/v1/updateChatStatus`
为会话分配座席	PUT	`/api/ext/v3/conversations/{target}/operator`	`/{tenantId}/api/v1/assignOperator`

重要说明：

“获取消息历史记录” API 用于检索特定联系人的会话历史记录。它不会检索您 WhatsApp 号码收到的所有消息。
来自消息发送 API 的 HTTP 200 响应表示请求已被接受，并不代表消息已送达收件人。
使用 sentMessageDELIVERED_v2 Webhook 事件来跟踪消息送达情况。templateMessageFailed 事件用于报告消息发送失败。

3.3 联系人 API (Contacts API)

使用联系人 API 在 Wati 中创建、检索、更新、删除和整理联系人。

操作	方法	v3 端点	v1 端点
列出联系人	GET	`/api/ext/v3/contacts`	`/{tenantId}/api/v1/getContacts`
添加联系人	POST	`/api/ext/v3/contacts`	`/{tenantId}/api/v1/addContact/{whatsappNumber}`
更新联系人属性	PUT	`/api/ext/v3/contacts`	`/{tenantId}/api/v1/updateContactAttributes/{whatsappNumber}`
更新多个联系人	POST	—	`/{tenantId}/api/v1/updateContactAttributesForMultiContacts`
获取联系人详情	GET	`/api/ext/v3/contacts/{target}`	—
获取联系人总数	GET	`/api/ext/v3/contacts/count`	—
删除联系人	—	v3 可用	—
将联系人分配给团队	PUT	`/api/ext/v3/contacts/teams`	—

计划要求：通过 v1 端点更新多个联系人需要 Business (商业版) 计划。

3.4 消息模板 API (Message Templates API)

使用消息模板 API 检索、创建和删除 WhatsApp 消息模板。

操作	方法	v3 端点	v1 端点
列出消息模板	GET	`/api/ext/v3/messageTemplates`	`/{tenantId}/api/v1/getMessageTemplates`
按 ID 获取模板	GET	`/api/ext/v3/messageTemplates/{template_id}`	—
创建模板	POST	—	`/{tenantId}/api/v1/whatsApp/templates`
删除模板	DELETE	—	`/{tenantId}/api/v1/whatsApp/templates/{wabaId}/{name}/{language}`

3.5 营销活动 API (Campaigns API)

使用营销活动 API 检索营销活动信息、估算营销活动成本并管理计划内的群发消息。

操作	方法	v3 端点	v1 端点
列出营销活动	GET	`/api/ext/v3/broadcasts`	—
获取营销活动详情	GET	`/api/ext/v3/broadcasts/{broadcast_id}`	—
获取营销活动收件人	GET	`/api/ext/v3/broadcasts/{broadcast_id}/recipients`	—
获取营销活动概览	GET	`/api/ext/v3/broadcasts/overview`	—
估算营销活动成本	POST	`/api/ext/v3/broadcasts/estimate-cost`	—
计划营销活动	POST	—	`/{tenantId}/api/v1/broadcast/scheduleBroadcast`
删除计划中的营销活动	DELETE	—	`/{tenantId}/api/v1/broadcast/deleteScheduledBroadcast/{broadcastId}`

3.6 标签 API (Tags API)

使用标签 API 通过添加或移除标签来整理会话。

操作	v3 可用性
为会话添加标签	可用
从会话中移除标签	可用

请参阅 Wati API 文档了解相关的端点路径和请求详情。

3.7 输入指示器 API (Typing Indicator API)

使用输入指示器 API 在活动消息会话期间向联系人显示“正在输入”状态。

操作	v3 可用性
发送输入指示器	可用

有关端点详情，请参阅 Wati API 文档。

3.8 通话 API (Calls API)

使用通话 API 检索通话记录、录音、转录文本和摘要。

操作	方法	v3 端点
获取通话记录	GET	`/api/ext/v3/calls`
获取通话录音	GET	`/api/ext/v3/calls/{call_id}/recording`
获取通话转录文本	GET	`/api/ext/v3/calls/{call_id}/transcript`
获取通话摘要	GET	`/api/ext/v3/calls/{call_id}/summary`
检索多个录音、转录文本或摘要	—	v3 可用

有关批量操作的请求详情，请参阅 Wati API 文档。

3.9 聊天机器人 API (Chatbots API)

使用聊天机器人 API 检索可用的聊天机器人并启动聊天机器人流程。

操作	方法	v3 端点	v1 端点
列出聊天机器人	GET	`/api/ext/v3/chatbots`	`/{tenantId}/api/v1/chatbots`
启动聊天机器人	POST	`/api/ext/v3/chatbots/start`	`/{tenantId}/api/v1/chatbots/start`

计划要求：聊天机器人 API 需要 Pro (专业版) 或 Business (商业版) 计划。

3.10 分段 API (Segments API)

使用分段 API 检索联系人分段、评估分段筛选器并创建自定义分段。

操作	方法	v3 端点	v1 端点
列出分段	GET	`/api/ext/v3/segments`	—
获取分段	GET	`/api/ext/v3/segments/{segmentId}`	—
评估分段筛选器	—	v3 可用	—
创建自定义分段	POST	—	`/{tenantId}/api/v1/createCustomSegment`

计划要求：通过 v1 端点创建自定义分段需要 Pro (专业版) 或 Business (商业版) 计划。

3.11 Webhook 管理 API (Webhook Management API)

Webhook 允许 Wati 向您配置的 URL 发送事件通知。您可以使用 Webhook 管理 API 以编程方式管理 Webhook 订阅。

操作	方法	v3 端点	v2 端点
列出 Webhook 订阅	GET	`/api/ext/v3/webhooks`	—
获取 Webhook 订阅	GET	`/api/ext/v3/webhooks/{id}`	—
更新 Webhook 订阅	PUT	`/api/ext/v3/webhooks/{id}`	—
删除 Webhook 订阅	DELETE	`/api/ext/v3/webhooks/{id}`	—
列出可用的 Webhook 事件类型	—	v3 可用	—
创建 Webhook 订阅	POST	—	`/{tenantId}/api/v2/webhookEndpoints`

有关配置和处理 Webhook 事件的说明，请参阅 Wati Webhook 文档。

3.12 Instagram API

使用 Instagram API 检索 Instagram 帖子和评论，并回复评论。

操作	方法	v3 端点
列出 Instagram 帖子	GET	`/api/ext/v3/posts`
获取 Instagram 帖子	GET	`/api/ext/v3/posts/{post_id}`
列出帖子评论	GET	`/api/ext/v3/posts/{post_id}/comments`
获取未读评论计数	GET	`/api/ext/v3/posts/{post_id}/unreadCount`
回复评论	POST	`/api/ext/v3/comments/{comment_id}/replies`
发送评论的私密回复	POST	`/api/ext/v3/comments/{comment_id}/privateReply`

3.13 账户额度 API (Account Credits API)

使用账户额度 API 检查您的 Wati 账户余额。

操作	方法	v3 端点
获取账户额度	GET	`/api/ext/v3/account/credits`

3.14 媒体和令牌管理 API

使用媒体 API 检索媒体文件，使用令牌管理 API 禁用 API 令牌。

操作	方法	v3 端点	v1 端点
按文件名获取媒体	GET	—	`/{tenantId}/api/v1/getMedia`
按消息 ID 获取媒体	GET	`/api/ext/v3/conversations/messages/file/{message_id}`	—
禁用令牌	POST	—	`/{tenantId}/api/v1/rotateToken`

重要提示：v1 rotateToken 端点用于禁用指定令牌，它不会生成替换令牌。若要创建新的 API 令牌，请在您的 Wati 账户中前往 Connector (连接器) > API > Create API Token (创建 API 令牌)。

3.15 模型上下文协议 (MCP) 服务器

Wati 提供了一个模型上下文协议 (MCP) 服务器，允许 AI 工具和代理直接连接到 Wati 的功能。

有关设置说明，请参阅 Wati 开发者文档。

4. 其他资源

使用以下资源探索 API 端点、配置 Webhook 并测试 API 请求。

Wati API 文档 — 探索 API 端点和请求详情。
Wati Webhook 文档 — 了解如何配置 Webhook 并处理事件通知。
Wati Postman 集合 — 查找用于通过 Postman 测试 Wati API 请求的集合。

5. 重要 API 注意事项

在与 Wati 进行集成时，请记住以下几点：

选择正确的 API 版本：在所需操作支持的情况下，请为新的集成使用 v3 版本。旧版 v1 和 v2 端点在文档标注处仍可用。
使用正确的 URL 格式：v3 端点的路径中不包含租户 ID。文档化的 v1 和 v2 端点包含 /{tenantId}/。
使用正确的令牌范围：为您的 v3 操作创建具有所需权限的 API 令牌。
单独检查消息送达情况：来自消息发送端点的 HTTP 200 响应并不确认送达。请使用相关的 Webhook 事件来跟踪送达或失败情况。
了解令牌轮换：v1 rotateToken 端点用于禁用令牌，而不是创建新令牌。

有关端点特定的参数、请求格式、响应和示例，请参阅 Wati API 文档。

Wati API 概览

概要