跳至主要內容

如何使用 Wati webhooks 追蹤範本訊息的發送與訊息狀態

摘要

當您使用 Wati API 發送範本訊息時，您可能希望使用 Webhook 來追蹤其狀態（例如：已發送、已送達、已讀、已回覆或失敗），而不是僅依賴 Wati 內建的行銷活動分析。

透過 API 發送行銷活動後，您可以隨時在 Wati 的行銷活動總覽 (Campaign Overview) 中查看其成效。此外，您也可以使用 Wati Webhook，透過您自己的系統即時追蹤這些行銷活動的訊息狀態與送達事件。

此方法有助於您監控訊息成效、排解送達問題，並透過您的應用程式管理客戶互動。本指南說明如何發送範本訊息並使用 Webhook 追蹤其生命週期。

注意：有關 Wati Webhook 的更多資訊，請參閱 Wati 開發人員說明文件。

操作說明

發送範本訊息

若要使用 Wati 的 API 發送範本訊息，請使用 sendTemplateMessage V2 端點。

cURL 請求範例

curl --location 'https://live-mt-server.wati.io/{tenant_id}/api/v2/sendTemplateMessage?whatsappNumber=<whatsappNumber>' \
--header 'Authorization: Bearer <Token>' \
--header 'Content-Type: application/json' \
--data '{
  "template_name": "update_for_you",
  "broadcast_name": "JPTestBroadcast",
  "parameters": []
}'

API 回應範例

{
  "result": true,
  "error": null,
  "templateName": "update_for_you",
  "receivers": [
    {
      "localMessageId": "d38f0c3a-e833-4725-a894-53a2b1dc1af6",
      "waId": "<whatsappNumber>",
      "isValidWhatsAppNumber": true,
      "errors": []
    }
  ],
  "parameters": []
}

關鍵欄位

  • localMessageId：用於跨 Webhook 事件追蹤訊息的唯一識別碼。請儲存此值，因為它能將該訊息的所有狀態更新關聯起來。

使用 Webhook 追蹤訊息狀態

訊息發送後，Wati 會針對每次狀態更新發送 Webhook 事件。請使用 localMessageId 將這些事件與原始訊息進行配對。

1. 範本訊息已發送

  • 觸發時機：訊息已從 Wati 成功發送

  • 事件： templateMessageSent_v2

  • 狀態： SENT

Webhook 負載範例

{
  "eventType": "templateMessageSent_v2_bsuid",
  "localMessageId": "84689938-5e2-877821d672c2",
  "id": "693fd8ee21f81",
  "whatsappMessageId": "wamid.HBgNODEYEjQ3RDMzQzM2QjM3QjU1ODQ4RQA=",
  "templateId": "6929b",
  "templateName": "test_jm4",
  "created": "2025-12-15T09:46:23.4083984Z",
  "conversationId": "68b68470e93cc",
  "ticketId": "693fd6ab545f82",
  "text": "Make your messages personal using variables like name and get more replies!",
  "operatorEmail": "[email protected]",
  "waId": "86151285",
  "type": "template",
  "statusString": "SENT",
  "sourceType": "WEB",
  "headerLink": null,
  "headerType": null,
  "channelId": null,
  "channelPhoneNumber": "174742",
  "bsuid": "HK.xxxxxxxxxxxxx",
  "parentBsuid": "HK.ENT.xxxxxxxxxxxxx",
  "username": "@bob"
}

「範本已發送」Webhook 現在包含按鈕資訊

「範本已發送」Webhook 現在包含 WhatsApp 範本中設定的按鈕資訊。這讓您可以識別與已發送範本訊息相關聯的按鈕文字。

此功能適用於 Pro、Business 與 Enterprise 方案的客戶。

包含哪些按鈕資訊？

Webhook 負載可包含來自 WhatsApp 範本的以下按鈕資訊：

  • 快速回覆按鈕文字

  • 連結按鈕文字

當您透過 API 檢索範本資訊時，回應內容也會包含為該範本設定的按鈕文字。

2. 訊息已送達

  • 觸發時機：訊息已送達給收件者

  • 事件： sentMessageDELIVERED_v2

  • 狀態： Delivered

Webhook 負載範例

{
  "eventType": "sentMessageDELIVERED_v2",
  "statusString": "Delivered",
  "localMessageId": "16bf77ae-79e8-691eb4b",
  "id": "693fd65f99391640",
  "whatsappMessageId": "wamid.HBgNODYxMzEzMzg4Nzg2MDU0OEM0NTYxRTlBMwA=",
  "conversationId": "68cba32b3349e",
  "ticketId": "693f7a0a8545f54",
  "text": "hello",
  "type": "text",
  "timestamp": "1765791326",
  "assigneeId": "65a105b5cf65262",
  "operatorEmail": "derre.ai",
  "channelId": null,
  "channelPhoneNumber": "17742"
}

3. 訊息已讀

  • 觸發時機：收件者已讀取訊息

  • 事件： sentMessageREAD_v2

  • 狀態： Read

Webhook 負載範例

{
  "eventType": "sentMessageREAD_v2",
  "statusString": "Read",
  "localMessageId": "16bf77ae-79e691eb4b",
  "id": "693fd65f961dc81779391640",
  "whatsappMessageId": "wamid.HBgNODYxMzEABEYEjVCNzg2MDU0OEM0NTYxRTlBMwA=",
  "conversationId": "68cba3db12b3349e",
  "ticketId": "693fd64d1d45f54",
  "text": "hello",
  "type": "text",
  "timestamp": "17651326",
  "assigneeId": "65a10905cf65262",
  "operatorEmail": "[email protected]",
  "channelId": null,
  "channelPhoneNumber": "174742"
}

4. 訊息已回覆

  • 觸發時機：收件者已回覆訊息

  • 事件： sentMessageREPLIED_v2

  • 狀態： Replied

Webhook 負載範例

{
  "eventType": "sentMessageREPLIED_v2",
  "statusString": "Replied",
  "localMessageId": "16bf77ae-79e691eb4b",
  "id": "693fd65f961dc81779391640",
  "whatsappMessageId": "wamid.HBgNODYxMzEABEYEjVCNzg2MDU0OEM0NTYxRTlBMwA=",
  "conversationId": "68cba3db12b3349e",
  "ticketId": "693fd64d1d45f54",
  "text": "hello",
  "type": "text",
  "timestamp": "17651326",
  "assigneeId": "65a10905cf65262",
  "operatorEmail": "[email protected]",
  "channelId": null,
  "channelPhoneNumber": "174742"
}

5. 訊息已接收

  • 觸發時機：使用者發送訊息至您的 Wati 號碼

  • 事件： messageReceived

  • 狀態： Received

使用情境：

  • 追蹤使用者的回覆

  • 擷取範本訊息中的快速回覆按鈕點擊事件

Webhook 負載範例

{
  "eventType": "messageReceived",
  "statusString": "Received",
  "localMessageId": "fd29c1f-9033-59b2-7d72-5ac964c4c8a7",
  "whatsappMessageId": "wamid.HBgMOAE4NjY4NDkzNjAxFAIAERgSOTEENzFCNjEwMkNDNENGQUJGAA==",
  "text": "Hello, I need help!",
  "timestamp": "1665645642",
  "operatorEmail": "[email protected]"
}

6. 範本訊息失敗

  • 觸發時機：訊息發送失敗

  • 事件： templateMessageFailed

  • 狀態： Failed

Webhook 負載範例

{
  "eventType": "templateMessageFailed",
  "statusString": "Failed",
  "localMessageId": "fd29c1f-9033-59b2-7d72-5ac964c4c8a7",
  "failedCode": "131026",
  "failedDetail": "Message undeliverable",
  "id": "66b2531d4931581381944612",
  "whatsappMessageId": "wamid.HBgMOAE4NjY4NDkzNjAxFAIAERgSOTEENzFCNjEwMkNDNENGQUJGAA==",
  "conversationId": "66b1fb044045cedb1f19538e",
  "ticketId": "66bdfba190194752bb7326d7",
  "text": null,
  "type": "template",
  "timestamp": "1665645642",
  "assigneeId": null,
  "operatorEmail": "[email protected]"
}

如何在 Wati 中設定 Webhook

請按照下列步驟開始接收 Webhook 事件：

  • 登入您的 Wati 帳號

  • 前往 Connectors (連結器) → Webhooks

  • 點擊 Add Webhook (新增 Webhook)

  • 輸入您的 Webhook URL

  • 將狀態設為 Enabled (已啟用)

  • 選擇所需的事件：

    • Template Message Sent (範本訊息已發送)

    • Delivered (已送達)

    • Read (已讀)

    • Replied (已回覆)

    • Failed (失敗)

最終說明

  • 發送訊息時，請務必儲存 localMessageId

  • 使用該 ID 將所有 Webhook 事件對應到同一則訊息

  • 結合多個 Webhook 事件以建立完整的訊息生命週期

透過正確設定 Webhook，您可以可靠地追蹤透過 Wati 發送的每一則範本訊息，並根據即時更新採取相應行動。

常見問題集 (FAQs)

發送與追蹤範本訊息

1. 如何使用 Wati API 發送範本訊息？

使用 sendTemplateMessage V2 端點即可透過 Wati API 發送範本訊息。

2. 什麼是 localMessageId，為什麼我應該儲存它？

localMessageId 是訊息的唯一識別碼。請務必儲存它，因為 Wati 會利用此 ID 將 Webhook 事件與原始訊息關聯，並在整個生命週期中追蹤其狀態。

3. 我該如何使用 Wati Webhook 追蹤範本訊息狀態？

設定 Wati Webhook 以接收範本訊息的即時事件。使用 localMessageId 將每個 Webhook 事件與原始訊息進行配對。

4. 哪些 Webhook 事件可用於追蹤範本訊息生命週期？

可用的 Webhook 事件包括：

  • templateMessageSent_v2 — 訊息已成功發送。

  • sentMessageDELIVERED_v2 — 訊息已送達。

  • sentMessageREAD_v2 — 收件者已讀取訊息。

  • sentMessageREPLIED_v2 — 收件者已回覆訊息。

  • templateMessageFailed — 訊息發送失敗。

  • messageReceived — 使用者發送訊息至您的 Wati 號碼。

5. messageReceived Webhook 有什麼用途？

messageReceived Webhook 可用於追蹤使用者的回覆，以及擷取範本訊息中的快速回覆按鈕點擊事件。

6. 「範本已發送」Webhook 包含哪些按鈕資訊？

「範本已發送」Webhook 可包含在 WhatsApp 範本中設定的快速回覆按鈕文字與連結按鈕文字。API 對於範本資訊的回應內容也包含已設定的按鈕文字。

7. 哪些 Wati 方案支援「範本已發送」Webhook 中的按鈕資訊功能？

按鈕資訊功能適用於 Pro、Business 與 Enterprise 方案的客戶。

8. 如何在 Wati 中設定 Webhook 以追蹤範本訊息？

在您的 Wati 帳號中前往 Connectors (連結器) → Webhooks，點擊 Add Webhook (新增 Webhook)，輸入您的 Webhook URL，將狀態設為 Enabled (已啟用)，並選擇所需的事件：Template Message Sent (範本訊息已發送)、Delivered (已送達)、Read (已讀)、Replied (已回覆) 與 Failed (失敗)。

9. 如何追蹤範本訊息的完整生命週期？

在發送訊息時儲存 localMessageId，並使用它來對應所有相關的 Webhook 事件。結合這些事件，即可追蹤該訊息是否已發送、送達、已讀、已回覆或發送失敗。

相關文章
是否回答了您的問題？