狀態和定價通知
WhatsApp Business API 用戶端會傳送您與用戶間往來訊息 status 的相關通知。這些通知會透過 statuses 物件傳送。
狀態更新
貴企業傳送每則訊息時，您都將收到有關訊息狀態的通知。在下表中，點擊左欄中的箭號以取得 WhatsApp 應用程式對應每種狀態的通知（如果有的話）。
| 名稱 | 說明 |
|---|---|
| 用戶已刪除由該用戶傳送的訊息。收到此通知時，如已從伺服器下載訊息，請務必自系統中刪除該則訊息。 |
| 貴企業傳送的訊息已送達用戶的裝置。 |
| 貴企業傳送的訊息無法傳送。回呼中將包含失敗的原因。請查看錯誤訊息文件以協助偵錯： |
| 用戶已讀取貴企業傳送的訊息。 |
| 貴企業傳送的訊息正在我們的系統內傳輸中。 內部部署 API 用戶：欲接收 |
| 貴企業傳送的訊息包含目錄中不可用或不存在的項目。 |
這些通知在您應用程式內的順序不一定會反映訊息狀態的確切時間。如有需要，請檢視時間戳記以判斷時間。
若要使狀態變成 read，必須先成為 delivered。在某些情況下，例如用戶在聊天室畫面中有訊息送達時，訊息會幾乎同時成為 delivered 和 read 狀態。在這類情況下，不會傳回 delivered 通知，因為訊息已經讀取，當然表示已送達。此行為是內部最佳化的結果。
定價更新
自 2022 年 2 月 1 日起，出站通知中的 statuses 物件會包括兩種新的巢狀物件：conversation 和 pricing。conversation 和 pricing 物件元件會因對話開啟的位置而不同。對話可能是用戶開啟的對話、商家主動開啟對話，或是從免費進入點開始的對話。詳情請見以下資訊：
範例
在下列範例中，recipient_id 可能改為 group_id 欄位。其取決於訊息是傳送給個人或群組。
狀態：已傳送訊息
當商家在用戶主動開啟對話（如果該對話不是源自免費進入點）中傳送訊息時，會收到下列 Webhook：
{
"statuses": [{
"id": "ID",
"recipient_id": "WHATSAPP_ID",
"status": "sent",
"timestamp": "TIMESTAMP",
"type": "message",
"message": {
"recipient_id":"WHATSAPP_ID"
},
"conversation": {
"id": "CONVERSATION_ID",
"expiration_timestamp": TIMESTAMP,
"origin": {
"type": "user_initiated"
}
},
"pricing": {
"pricing_model": "CBP",
"billable": true,
"category": "user_initiated"
}
}]
}
當商家在用戶主動開啟對話（如果該對話不是源自免費進入點）中針對媒體訊息傳送訊息時，會收到下列 Webhook：
{
"statuses": [{
"id": "ID",
"recipient_id": "WHATSAPP_ID",
"status": "sent",
"timestamp": "TIMESTAMP",
"type": "message",
"message": {
"media_id": "98d14c8e-0310-4061-8f99-2d148274c286",
"recipient_id":"WHATSAPP_ID"
},
"conversation": {
"id": "CONVERSATION_ID",
"expiration_timestamp": TIMESTAMP,
"origin": {
"type": "user_initiated"
}
},
"pricing": {
"pricing_model": "CBP",
"billable": true,
"category": "user_initiated"
}
}]
}
當商家在商家主動開啟對話中傳送訊息時，會收到下列 Webhook：
{
"statuses": [{
"id": "ID",
"recipient_id": "WHATSAPP_ID",
"status": "sent",
"timestamp": "TIMESTAMP",
"type": "message",
"message": {
"recipient_id":"WHATSAPP_ID"
},
"conversation": {
"id": "CONVERSATION_ID",
"expiration_timestamp": TIMESTAMP,
"origin": {
"type": "business_initiated"
}
},
"pricing": {
"pricing_model": "CBP",
"billable": true,
"category": "business_initiated"
}
}]
}
當商家傳送訊息來回覆源自免費進入點的用戶開啟的對話時，會收到下列 Webhook：
{
"statuses": [{
"id": "ID",
"recipient_id": "WHATSAPP_ID",
"status": "sent",
"timestamp": "TIMESTAMP",
"type": "message",
"message": {
"recipient_id":"WHATSAPP_ID"
},
"conversation": {
"id": "CONVERSATION_ID",
"expiration_timestamp": TIMESTAMP,
"origin": {
"type": "referral_conversion",
}
},
"pricing": {
"pricing_model": "CBP",
"billable": false,
"category": "referral_conversion"
}
}]
}狀態：已送達訊息
當商家的訊息已送達，且該訊息是在用戶開啟的對話（如果該對話不是源自免費進入點）中時，會收到下列 Webhook：
{
"statuses": [{
"id": "ID",
"recipient_id": "WHATSAPP_ID",
"status": "delivered",
"timestamp": "TIMESTAMP",
"type": "message",
"message": {
"recipient_id":"WHATSAPP_ID"
},
"conversation": {
"id": "CONVERSATION_ID",
"origin": {
"type": "user_initiated"
}
},
"pricing": {
"pricing_model": "CBP",
"billable": true,
"category": "user_initiated"
}
}]
}
當商家的訊息已送達，且該訊息是在商家主動開啟對話中時，會收到下列 Webhook：
{
"statuses": [{
"id": "ID",
"recipient_id": "WHATSAPP_ID",
"status": "delivered",
"timestamp": "TIMESTAMP",
"type": "message",
"message": {
"recipient_id": "WHATSAPP_ID"
},
"conversation": {
"id": "CONVERSATION_ID",
"origin": {
"type": "business_initiated"
}
},
"pricing": {
"pricing_model": "CBP",
"billable": true,
"category": "business_initiated"
}
}]
}
當商家的訊息已送達，且該訊息是在源自免費進入點的用戶開啟的對話中時，會收到下列 Webhook：
{
"statuses": [{
"id": "ID",
"recipient_id": "WHATSAPP_ID",
"status": "delivered",
"timestamp": "TIMESTAMP",
"type": "message",
"message": {
"recipient_id": "WHATSAPP_ID"
},
"conversation": {
"id": "CONVERSATION_ID",
"origin": {
"type": "referral_conversion",
}
},
"pricing": {
"pricing_model": "CBP",
"billable": false,
"category": "referral_conversion"
}
}]
}
狀態：已讀取訊息
已讀取訊息的標準回呼：
{
"statuses":[{
"id": "ID",
"recipient_id": "WHATSAPP_ID",
"status": "read",
"timestamp": "TIMESTAMP",
"type": "message",
"message": {
"recipient_id": "WHATSAPP_ID"
}
}]
}
狀態：訊息失敗
錯誤代碼 470
{
"statuses": [{
"errors": [{
"code": 470,
"title": "Failed to send message because you are outside the support window for freeform messages to this user. Please use a valid HSM notification or reconsider."
}],
"id": "ID",
"recipient_id": "WHATSAPP_ID",
"status": "failed",
"timestamp": "TIMESTAMP"
}]
}
錯誤代碼 480
{
"statuses": [{
"errors": [{
"code": 480,
"title": "Failed to send message since we detect an identity change of the contact"
}],
"id": "ID",
"recipient_id": "WHATSAPP_ID",
"status": "failed",
"timestamp": "TIMESTAMP"
}]
}
如果訊息傳送失敗，回呼中將不會包含對話子區段。此案例不涉及計費或對話啟用。
狀態：已刪除訊息
已刪除訊息的標準回呼：
{
"statuses": [{
"id": "ID",
"recipient_id": "WHATSAPP_ID",
"status": "deleted",
"timestamp": "TIMESTAMP",
"type": "message",
"message": {
"recipient_id": "WHATSAPP_ID"
}
}]
}如果訊息已刪除，回呼中將不會包含對話子區段。此案例不涉及計費或對話啟用。
所有可能的訊息狀態
如需詳細資訊，請參閱總覽：訊息。
常見問題
Yes, there is a specific scenario where you can get pricing information on your webhook alert for read messages. For each sent message, there can be 3 scenarios:
| Scenario | When it Happens |
|---|---|
| You get a webhook alert when the message is delivered (including pricing information) and another webhook alert when the message is read (not including pricing information). | This is the most common scenario. |
| You get a webhook alert when the message is delivered (including pricing information). You do not get a webhook alert that the message has been read. | Common when a customer has turned off the feature that lets people know they have read a message. |
| You get a webhook alert when the message is read (including pricing information). You do not get a webhook alert that the message has been delivered. | Only triggered when the user is already reading the thread with the business when the message comes in. |