總結

本文涵蓋了有關使用 Wati 的 API 和 Webhook 的常見問題，包括如何透過 API 新增聯絡人、在哪裡找到您的 API 金鑰、如何使用 Webhook 事件啟用已讀回條，以及如何透過 API 管理 Webhook。

重要提示：全域 Webhook 僅支援 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 端點網址。

針對 v3 端點，請建立具有適當範圍 (Scope) 的金鑰：

範圍 (Scope)	用途
`contactsv3:*`	聯絡人操作
`conversationsv3:*`	對話操作
`messagetemplatev3:write`	發送範本

3. 如何啟用已讀回條？

啟用 sentMessageREAD_v2 Webhook 事件，即可在您發送的訊息被接收者讀取時收到回呼 (Callback)。

設定步驟：

前往您 Wati 帳戶中的 Connector > Webhooks。
新增您的 Webhook 網址。
啟用 sentMessageREAD_v2 事件。

Wati Webhook 可透過回呼網址針對下列事項通知您：

已接收的訊息
已發送的訊息（範本與對話）
訊息狀態更新（已發送 / 已送達 / 已讀）

sentMessageREAD_v2 — 範例負載 (Sample Payload)

{
  "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 管理 Webhook？

您可以透過程式設計的方式建立、列出、更新和刪除 Webhook。

建立 Webhook (v2)：

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

列出、取得、更新與刪除 Webhook (v3 — 建議使用)：

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

v3 Webhook 管理路徑中不包含 /{tenantId}/。建議所有新的整合都使用 v3。

詳細資訊請參閱 Wati Webhook 文件。

一般常見問題：Wati API 與 Webhooks

總結