訊息回調 API
最新更新:2023-03-07
概述
將「訊息狀態」和「訊息回響」的數據回調給企業的業務係統,可根據該信息進行統計、回複用戶等動作。
回調地址
企業需要設定接收「訊息狀態」以及「訊息回響」的回調地址,詳情參見 回呼設定。
回調格式
請求方式是 POST,請求體為 JSON,數據類型:"Content-Type: application/json"
一次請求將批量返回多條數據。
安全機製
待上線。目前回調暫未帶上鑒權信息,故開發者接收回調的接口請不要設定權限驗證。
應答機製
開發者服務接收到 Engagelab 的回調後,需要在 3 秒內按下述要求進行應答。
**接收成功:**HTTP 應答狀態碼需返回 200 ,無需返回應答報文。
重試機製
待上線。
請求參數
EngageLab 嚮業務係統的回調地址發起的請求參數如下:
字段 | 類型 | 選項 | 描述 |
---|---|---|---|
total | int | 必填 | 回調的數據量 |
rows | JSON Array | 必填 | 回調的詳細信息 |
rows 中的參數如下:
字段 | 類型 | 選項 | 描述 |
---|---|---|---|
message_id | string | 可選 | 訊息狀態以及訊息回響的時候返回。 |
from | string | 可選 | 傳送方,訊息狀態以及上行訊息的時候返回 |
to | string | 可選 | 接收方,訊息狀態以及上行訊息的時候返回 |
server | string | 必選 | 回調信息所屬的産品服務,固定取值 whatsapp |
channel | string | 可選 | 該狀態或者回響屬於哪一個通道,固定取值 whatsapp |
itime | int | 必選 | 回調數據真實産生的時間戳,與 message_status 字段相結合,可以得到:請求時間戳、傳送時間戳、送達時間戳、已讀時間戳 |
custom_args | JSON Object | 可選 | 在訊息傳送時自訂的可選字段,在訊息狀態回調中原樣返回。 |
status | JSON Object | 可選 | 訊息狀態字段 |
response | JSON Object | 可選 | 訊息回響字段 |
訊息狀態-status
回調參數
字段 | 類型 | 選項 | 描述 |
---|---|---|---|
message_status | string | 必選 | 訊息的狀態 |
status_data | JSON Object | 可選 | 該狀態下的詳細數據 |
error_code | int | 可選 | 錯誤碼,失敗時返回 |
error_detail | JSON Object | 可選 | 錯誤詳情,失敗時返回 |
loss | JSON Object | 可選 | 摺損階段和摺損來源 |
message_status
取值 | 描述 | 定義 |
---|---|---|
plan | 計畫傳送 | 該號碼在傳遞的「收件人號碼」內,即為該號碼記錄 1 個計劃傳送目標的狀態 |
target_valid | 目標有效 | 通過合法性校驗 1、該號碼被 EngageLab 判定為合法 2、該號碼被 Meta WhatsApp 服務判定為合法 |
sent | 傳送成功 | 該號碼由 EngageLab 提交給 Meta WhatsApp 服務後返回了成功 |
delivered | 送達成功 | 由 Meta WhatsApp 服務確認訊息已送達用戶 |
read | 已讀 | 由 Meta WhatsApp 服務確認用戶已讀訊息 |
target_invalid | 目標無效 | 1、該號碼被 EngageLab 判定為非法 2、該號碼被 Meta WhatsApp 服務判定為非法 |
sent_failed | 傳送失敗 | 該號碼提交給 Meta WhatsApp 服務後返回了失敗 |
delivered_failed | 送達失敗 | 該號碼提交給 Meta WhatsApp 服務成功,但 Meta 回調告知失敗。 |
delivered_timeout | 超時未送達 | 該號碼提交給 Meta WhatsApp 服務成功,但在 5 分鐘內 Meta 未回調告知是否成功/失敗,計為超時。 |
status_data
字段 | 類型 | 選項 | 描述 |
---|---|---|---|
msg_time | int | 必填 | 訊息下發時間,調用 API 請求傳送訊息成功的時間點 |
channel_message_id | String | 必填 | WhatsApp 官方返回的訊息 ID |
whatsapp_business_account_id | String | 必填 | 傳送號所屬的 WhatsApp 商業賬戶的編號 |
timezone | String | 必填 | 組織所在時區 |
plan_user_total | int | 可選 | 計劃目標總數,隻有當 message_status=plan 時這個才會有值 |
country_code | String | 必填 | 接收方手機號碼歸屬的國家/地區代碼 |
from_phone_id | String | 必填 | 傳送號碼(from)的 ID 標識 |
conversation | JSON Object | 可選 | 會話信息 |
pricing | JSON Object | 可選 | 價格信息 |
conversation
字段 | 類型 | 選項 | 描述 |
---|---|---|---|
id | String | 可選 | 該條訊息所屬的 Meta 對話 ID |
origin | JSON Object | 可選 | 表示是由誰發起的對話。由 type 指定。 示例:"origin":{"type":"business_initiated"},取值如下: |
pricing
字段 | 類型 | 選項 | 描述 |
---|---|---|---|
pricing_model | String | 可選 | 固定取值為 CBP |
category | String | 可選 | 對話定價類別,取值如下: |
error_detail
字段 | 類型 | 選項 | 描述 |
---|---|---|---|
message | String | 必填 | 錯誤原因 |
loss
字段 | 類型 | 選項 | 描述 |
---|---|---|---|
loss_step | int | 必填 | 摺損階段 |
loss_source | String | 必填 | 摺損來源,取值: |
回調示例
{
"total": 1,
"rows": [
{
"message_id": "1666165485030094861", // EngageLab 的訊息 id
"from": "", // 傳送方
"to": "", // 接收方
"server": "whatsapp",
"channel": "whatsapp",
"itime": 1640707579, // 訊息狀態産生的時間戳,如訊息已送達的時間
"custom_args": {}, // 這條訊息創建時提交的參數,將於此回調時原樣返回
"status": {
// 成功時回響這些字段
"message_status": "delivered" // 訊息狀態
"status_data": { // 自訂
"msg_time": 1663432355, // 訊息下發時間,曆史記錄上的訊息傳送時間,即用戶調用 API 傳送訊息-調用 API 成功的那個時間
"channel_message_id": "wamid.123321abcdefed==", // 可選,Meta 返回的 msgid
"whatsapp_business_account_id": "", //傳送號 from 對應的 Whatsapp 商業賬戶編碼
"timezone": "", //組織時區
"plan_user_total": 2007, //計劃目標總數,隻有當 message_status=plan 時這個才會有值
"country_code": "CN", //接收方手機號碼歸屬的國家/地區代碼
"from_phone_id": "111111" // 傳送號碼(from)的 ID 標識
"conversation": { // 可選,會話信息
"id": "ebe2398cdaa37a0899ca5268b987b0c8",
"origin": {
"type": "business_initiated"
}
},
"pricing": { // 可選,價格信息
"pricing_model": "CBP",
"category": "business_initiated"
}
},
// 失敗狀態下(無效目標、傳送失敗、送達失敗、未讀)返回這些字段
"error_code": 0, //錯誤碼
"error_detail": {
"message": "" //錯誤原因
},
"loss": {
"loss_step": 1,
"loss_source": "aa"
}
}
}
]
}
{
"total": 1,
"rows": [
{
"message_id": "1666165485030094861", // EngageLab 的訊息 id
"from": "", // 傳送方
"to": "", // 接收方
"server": "whatsapp",
"channel": "whatsapp",
"itime": 1640707579, // 訊息狀態産生的時間戳,如訊息已送達的時間
"custom_args": {}, // 這條訊息創建時提交的參數,將於此回調時原樣返回
"status": {
// 成功時回響這些字段
"message_status": "delivered" // 訊息狀態
"status_data": { // 自訂
"msg_time": 1663432355, // 訊息下發時間,曆史記錄上的訊息傳送時間,即用戶調用 API 傳送訊息-調用 API 成功的那個時間
"channel_message_id": "wamid.123321abcdefed==", // 可選,Meta 返回的 msgid
"whatsapp_business_account_id": "", //傳送號 from 對應的 Whatsapp 商業賬戶編碼
"timezone": "", //組織時區
"plan_user_total": 2007, //計劃目標總數,隻有當 message_status=plan 時這個才會有值
"country_code": "CN", //接收方手機號碼歸屬的國家/地區代碼
"from_phone_id": "111111" // 傳送號碼(from)的 ID 標識
"conversation": { // 可選,會話信息
"id": "ebe2398cdaa37a0899ca5268b987b0c8",
"origin": {
"type": "business_initiated"
}
},
"pricing": { // 可選,價格信息
"pricing_model": "CBP",
"category": "business_initiated"
}
},
// 失敗狀態下(無效目標、傳送失敗、送達失敗、未讀)返回這些字段
"error_code": 0, //錯誤碼
"error_detail": {
"message": "" //錯誤原因
},
"loss": {
"loss_step": 1,
"loss_source": "aa"
}
}
}
]
}
此代碼塊在浮窗中顯示
訊息回響
回調參數
字段 | 類型 | 選項 | 描述 |
---|---|---|---|
event | string | 可選 | 回響事件 |
response_data | JSON Object | 可選 | 上行回複/交互的訊息內容 |
event
取值 | 描述 | 詳細說明 |
---|---|---|
received | 收到用戶的訊息 | 用戶直接傳送了一條訊息 |
reply | 用戶回複了你的訊息 | 企業先傳送了訊息給用戶,用戶選擇對該條信息進行回複 |
order | 用戶下訂單 | - |
deleted | 用戶刪除了他的訊息 | 用戶將自己發出的訊息刪除了(待上線) |
response_data
字段 | 類型 | 選項 | 描述 |
---|---|---|---|
channel_message_id | String | 必填 | WhatsApp 官方返回的訊息 ID |
whatsapp_business_account_id | String | 必填 | 傳送號所屬的 WhatsApp 商業賬戶的編號 |
contact | JSON Object | 可選 | 傳送方信息 |
message | JSON Object | 必填 | 訊息內容 |
contact
字段 | 類型 | 選項 | 描述 |
---|---|---|---|
profile | JSON Object | 可選 | 傳送方(客戶)的資料,當前僅有 name 字段表示客戶的姓名。 示例:"profile": {"name": "bob"} |
wa_id | String | 可選 | 傳送方的號碼 |
message
字段 | 類型 | 選項 | 描述 |
---|---|---|---|
type | String | 必填 | 取值:text、image、audio、video、document、sticker、button、interactive、unknown、order |
text | JSON Object | 可選 | 詳見 text object 說明 |
image | JSON Object | 可選 | 詳見 image object 說明 |
audio | JSON Object | 可選 | 詳見 audio object 說明 |
video | JSON Object | 可選 | 詳見 video object 說明 |
document | JSON Object | 可選 | 詳見 document object 說明 |
sticker | JSON Object | 可選 | 詳見 sticker object 說明 |
回調示例
{
"total": 1,
"rows": [
{
"message_id": "1666165485030094861", // Engagelab側的訊息 id
"from": "", // 傳送方,即客戶的手機號碼
"to": "", // 接收方,即開發者的傳送號
"server": "whatsapp",
"channel": "whatsapp",
"itime": 1640707579, // 時間戳
"response": {
"event": "", // 回響事件
"response_data": { // 具體訊息內容
"channel_message_id": "wamid.123321abcdefed==", // 可選,Meta 返回的 msgid
"whatsapp_business_account_id": "123321", //開發者的傳送號 to 對應的 Whatsapp 商業賬戶編碼
"contact": { // 可選,傳送方信息
"profile": {
"name": "bob" // 傳送方的昵稱
},
"wa_id": "8613800138000" // 傳送方的號碼
},
"message": { // 具體訊息內容
"type": "text", // 訊息的類型,可以根據這個值來識別具體訊息字段,如 text 則內容為 text 字段
"text": { // 訊息內容
"body": "here is the message content text"
}
}
}
}
}
]
}
{
"total": 1,
"rows": [
{
"message_id": "1666165485030094861", // Engagelab側的訊息 id
"from": "", // 傳送方,即客戶的手機號碼
"to": "", // 接收方,即開發者的傳送號
"server": "whatsapp",
"channel": "whatsapp",
"itime": 1640707579, // 時間戳
"response": {
"event": "", // 回響事件
"response_data": { // 具體訊息內容
"channel_message_id": "wamid.123321abcdefed==", // 可選,Meta 返回的 msgid
"whatsapp_business_account_id": "123321", //開發者的傳送號 to 對應的 Whatsapp 商業賬戶編碼
"contact": { // 可選,傳送方信息
"profile": {
"name": "bob" // 傳送方的昵稱
},
"wa_id": "8613800138000" // 傳送方的號碼
},
"message": { // 具體訊息內容
"type": "text", // 訊息的類型,可以根據這個值來識別具體訊息字段,如 text 則內容為 text 字段
"text": { // 訊息內容
"body": "here is the message content text"
}
}
}
}
}
]
}
此代碼塊在浮窗中顯示