總覽

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 (Tenant 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 Token

您需要 API Token 才能驗證對 Wati API 端點的請求。

建立 API Token 的步驟：

登入您的 Wati 帳戶。
前往 Connector > API。
選擇 Create API Token。
建立一個具有適當權限的 Token，以執行您想要的 API 操作。

對於 v3 端點，請選擇所需的 Token 範圍：

Token 範圍	用途
`contactsv3:*`	聯絡人操作
`conversationsv3:*`	對話操作
`messagetemplatev3:write`	傳送訊息範本

請確保您的 Token 具有您要使用的端點所需的範圍。

3. 探索可用的 Wati API

下列章節按功能對 Wati API 進行了分類。每個表格都列出了可用的操作及其記錄的端點路徑。

3.1 Channels API

使用 Channels API 來擷取有關您已連接的 WhatsApp 號碼的資訊。

操作	方法	v3 端點	v1 端點
列出已連接的 WhatsApp 號碼	GET	`/api/ext/v3/channels`	`/{tenantId}/api/v1/whatsApp/phoneNumbers`

3.2 Messaging API

使用 Messaging 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 Contacts API

使用 Contacts 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 Message Templates API

使用 Message Templates 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 Campaigns API

使用 Campaigns 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 Tags API

使用 Tags API 透過新增或移除標籤來組織對話。

操作	v3 可用性
將標籤新增至對話	可用
從對話中移除標籤	可用

請參閱 Wati API 文件以獲取相關端點路徑和請求詳細資訊。

3.7 Typing Indicator API

使用 Typing Indicator API 在訊息會話期間向聯絡人顯示輸入指示器。

操作	v3 可用性
傳送輸入指示器	可用

請參閱 Wati API 文件以獲取端點詳細資訊。

3.8 Calls API

使用 Calls 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 Chatbots API

使用 Chatbots API 來擷取可用的聊天機器人並啟動聊天機器人流程。

操作	方法	v3 端點	v1 端點
列出聊天機器人	GET	`/api/ext/v3/chatbots`	`/{tenantId}/api/v1/chatbots`
啟動聊天機器人	POST	`/api/ext/v3/chatbots/start`	`/{tenantId}/api/v1/chatbots/start`

方案要求： Chatbots API 需要 Pro 或 Business 方案。

3.10 Segments API

使用 Segments 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 Management API

Webhook 允許 Wati 將事件通知傳送到您設定的 URL。您可以使用 Webhook Management 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 Webhooks 文件。

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 Account Credits API

使用 Account Credits API 檢查您的 Wati 帳戶點數餘額。

操作	方法	v3 端點
取得帳戶點數	GET	`/api/ext/v3/account/credits`

3.14 Media and Token Management APIs

使用 Media API 擷取媒體檔案，並使用 Token Management API 封鎖 API Token。

操作	方法	v3 端點	v1 端點
透過檔名取得媒體	GET	—	`/{tenantId}/api/v1/getMedia`
透過訊息 ID 取得媒體	GET	`/api/ext/v3/conversations/messages/file/{message_id}`	—
封鎖 Token	POST	—	`/{tenantId}/api/v1/rotateToken`

重要提示： v1 的 rotateToken 端點會封鎖指定的 Token。它不會產生替代的 Token。若要建立新的 API Token，請在您的 Wati 帳戶中前往 Connector > API > Create API Token。

3.15 Model Context Protocol (MCP) Server

Wati 提供了一個 Model Context Protocol (MCP) 伺服器，讓 AI 工具和代理程式能夠直接連接到 Wati 的功能。

有關設定說明，請參閱 Wati 開發者文件。

4. 其他資源

使用下列資源來探索 API 端點、設定 Webhook 並測試 API 請求。

Wati API 文件 — 探索 API 端點和請求詳細資訊。
Wati Webhooks 文件 — 了解如何設定 Webhook 並處理事件通知。
Wati Postman 集合 — 尋找用於使用 Postman 測試 Wati API 請求的集合。

5. 重要 API 注意事項

在與 Wati 整合時，請記住以下幾點：

選擇正確的 API 版本： 若所需操作有支援，請務必針對新的整合使用 v3。舊版的 v1 和 v2 端點在有記錄的情況下仍可繼續使用。
使用正確的 URL 格式： v3 端點的路徑中不包含租戶 ID。記錄中的 v1 和 v2 端點包含 /{tenantId}/。
使用正確的 Token 範圍： 建立具有 v3 操作所需權限的 API Token。
分別檢查訊息送達狀態： 來自訊息傳送端點的成功 HTTP 200 回應並不能確認訊息已送達。請使用相關的 Webhook 事件來追蹤送達狀態或失敗原因。
了解 Token 輪替： v1 的 rotateToken 端點僅會封鎖 Token，而不會建立新 Token。

有關端點特定參數、請求格式、回應和範例，請參閱 Wati API 文件。

Wati API 概覽

總覽

說明