摘要

如果您正在使用 Wati 的「多個 WhatsApp 號碼」功能，本指南將說明如何跨不同的已連線號碼使用 Wati API。

說明

如果您的 Wati 帳戶連線了多個 WhatsApp 號碼，您可以使用這些號碼透過 API 發送和接收訊息。

為確保 API 請求使用正確的 WhatsApp 號碼，您可能需要在請求酬載 (payload) 或 URL 中包含額外的金鑰。所需的金鑰以及傳遞方式取決於您使用的 API 端點。

本指南列出了目前支援多個 WhatsApp 號碼的 Wati API，並說明如何為每個 API 請求指定 WhatsApp 號碼。

開始之前

身份驗證： 請前往 Connector > API > Create API Token 建立作用域 (scoped) API 權杖。

主機： https://live-mt-server.wati.io

v1 路徑在主機後包含 /{tenantId}/：https://live-mt-server.wati.io/{tenantId}/api/v1/...
v3 路徑不包含 /{tenantId}/：https://live-mt-server.wati.io/api/ext/v3/...

電話號碼格式： 使用包含國家代碼的數字，且不帶「+」符號。範例：85264318722。

注意：

所有新的整合皆建議使用 v3。 v1 為舊版，但仍受支援。

回傳 200 狀態碼代表您的請求已被接受，並不代表訊息已送達。訊息送達狀態由「已送達」、「已讀」或「已回覆」Webhooks 確認。失敗情況則由「範本訊息失敗」(Template Message Failed) Webhook 回報。

v1 API 端點

1. 發送範本訊息

端點： POST /{tenantId}/api/v1/sendTemplateMessage

參數	位置	備註
`channel_number`	Body	發送訊息的號碼
`target`	Body	收件人的電話號碼、ContactId 或 BSUID。提供此參數時，`whatsappNumber` 為選填。

2. 發送範本訊息（批次）

端點： POST /{tenantId}/api/v1/sendTemplateMessages

參數	位置	備註
`channel_number`	Body	發送訊息的號碼

3. 透過 CSV 發送範本訊息

端點： POST /{tenantId}/api/v1/sendTemplateMessageCSV

參數	位置	備註
`channelNumber`	Query	發送訊息的號碼

4. 更新對話狀態

端點： POST /{tenantId}/api/v1/updateChatStatus

參數	位置	備註
`channelPhoneNumber`	Body	您想要更新其對話狀態的號碼

5. 透過 WhatsApp 號碼取得訊息

端點： GET /{tenantId}/api/v1/getMessages/{whatsappNumber}

參數	位置	備註
`tenantId`	Path	您的 Wati 租戶 ID
`whatsappNumber`	Path	收件人的 WhatsApp 號碼
`channelPhoneNumber`	Query	要從中獲取訊息的已連線號碼

6. 接受 channelPhoneNumber 作為查詢參數的端點

以下端點使用 channelPhoneNumber 作為查詢參數來指定要使用哪個已連線號碼。對於 sendSessionMessage，messageText 也是一個查詢參數。

端點	方法
`/{tenantId}/api/v1/sendSessionMessage/{whatsappNumber}`	POST
`/{tenantId}/api/v1/sendSessionFile/{whatsappNumber}`	POST
`/{tenantId}/api/v1/sendSessionFileViaUrl/{whatsappNumber}`	POST
`/{tenantId}/api/v1/sendInteractiveButtonsMessage/{whatsappNumber}`	POST
`/{tenantId}/api/v1/sendInteractiveListMessage/{whatsappNumber}`	POST
`/{tenantId}/api/v1/assignOperator/{whatsappNumber}`	POST

對於上述所有端點：當提供 target 時，whatsappNumber (path) 為選填。

7. 無需指定號碼即可運作的 API

聯絡人資料在所有已連線號碼之間共享，因此這些端點不需要通道號碼：

API	端點
新增聯絡人	`POST /{tenantId}/api/v1/addContact/{whatsappNumber}`
更新聯絡人屬性	`POST /{tenantId}/api/v1/updateContactAttributes/{whatsappNumber}`
更新多個聯絡人的屬性	`POST /{tenantId}/api/v1/updateContactAttributesForMultiContacts` (僅限商業方案)
取得聯絡人清單	`GET /{tenantId}/api/v1/getContacts`

v3 API — 建議用於新的整合

v3 是所有新整合的推薦版本。它在路徑中不使用 /{tenantId}/。

權杖作用域 — 請前往 Connector > API > Create API Token 建立：

contactsv3:* — 聯絡人操作
conversationsv3:* — 對話操作
messagetemplatev3:write — 發送範本

列出已連線的號碼

端點： GET https://live-mt-server.wati.io/api/ext/v3/channels

傳回所有連線到您 Wati 帳戶的 WhatsApp 號碼。

發送範本訊息 (v3)

使用請求主體中的 channel 欄位來指定要從哪個號碼發送。

target 欄位接受：

電話號碼 — 85264318722
ContactId
BSUID
通道作用域格式 — Channel:85264318722

支援多個 WhatsApp 號碼的 API

API	是否支援多個號碼
發送範本訊息	是
發送範本訊息（批次）	是
透過 CSV 發送範本訊息	是
發送對話訊息	是
發送對話檔案	是
透過 URL 發送對話檔案	是
發送互動按鈕訊息	是
發送互動列表訊息	是
指派客服人員	是
更新對話狀態	是
透過 WhatsApp 號碼取得訊息	是
取得聯絡人清單	是
新增聯絡人	是
更新聯絡人屬性	是
更新多個聯絡人的屬性	是 (僅限商業方案)

有關 Wati API 的更多資訊，請參閱我們的官方開發者文件。

Wati 的 API 支援多個 WhatsApp 號碼

摘要

說明