AppPush
WebPush
WhatsApp
Email
SMS
OTP
回调 API
最新更新：2024-12-12
將「消息狀態」的數據回調給企業的業務系統，可根據該信息進行統計分析等動作。
回調地址
企業需要設置接收「消息狀態變更」的回調地址，可在Push後台管理->應用設置->回調設置進行配置。
回調地址合法性校驗
在Push後台管理->應用設置->回調設置進行配置回調地址時，會發起一個POST請求並附帶一個8位隨機字符串的請求body參數echostr，您需要在Response Body裡將echostr的value 返回，格式如下：
請求body
{
"echostr": "12345678"
}
請求body
{
"echostr": "12345678"
}
此代碼塊在浮窗中顯示
返回body
12345678
返回body
12345678
此代碼塊在浮窗中顯示
安全機制
用於客戶鑑權，可選。
為了確保消息的來源身份是 Engagelab, 你可以選擇對 POST 數據的來源進行安全認證。（不驗證, 直接解析 POST 的數據也可以）
安全認證的方法如下：
在Enagelab控制台的回調地址上配置回調用戶名（可選，下邊描述為username）和回調密鑰（可選，下邊描述為secret）進行身份驗證。
從請求Header中獲取 X-CALLBACK-ID，舉例如下：
X-CALLBACK-ID: timestamp=1681991058;nonce=123123123123;username=test;signature=59682d71e2aa2747252e4e62c15f6f241ddecc8ff08999eda7e0c4451207a16b
X-CALLBACK-ID: timestamp=1681991058;nonce=123123123123;username=test;signature=59682d71e2aa2747252e4e62c15f6f241ddecc8ff08999eda7e0c4451207a16b
此代碼塊在浮窗中顯示
其中 timestamp 為回調消息的時間戳（標準），nonce 為一個隨機數，signature 為簽名信息，簽名方法為：
signature=HMAC-SHA256(secret, timestamp+nonce+username)
signature=HMAC-SHA256(secret, timestamp+nonce+username)
此代碼塊在浮窗中顯示
應答機制
開發者服務接收到 Engagelab 的回調後，需要在 3 秒內按下述要求進行應答。
- **接收成功：**HTTP 應答狀態碼需返回 200 或 204，無需返回應答報文。
- **接收失敗：**HTTP 應答狀態碼需返回 5XX 或 4XX，同時需返回應答報文，格式如下：
{
"code": 2002,
"message": "失敗"
}
{
"code": 2002,
"message": "失敗"
}
此代碼塊在浮窗中顯示
| 字段 | 類型 | 必選/可選 | 說明 |
|---|---|---|---|
| code | int | 可選 | 錯誤碼 |
| message | string | 可選 | 錯誤詳細信息 |
重試機制
如果遇到 URL 訪問錯誤、超時、應答返回了接收失敗，Engagelab 最多會重試 5 次。每次重試的時間間隔最快為 10s, 1min, 5min, 30min, 1h. 即在消息丟失前，你有足夠的時間來修復 URL。
如果超過重試次數，Engagelab 將會把消息丟棄。
每次事件處理、數據解析，你需要在 3 秒內返回「接收成功的應答」 , 否則 Engagelab 將會重發該條消息。
回調內容
回調方式：POST
Content-Type：application/json
回調字段說明
消息主體
| 字段名 | 類型 | 必選/可選 | 說明 |
|---|---|---|---|
total |
int | 必選 | 本次回調包含的消息數量 |
rows |
array | 必選 | 消息狀態變更的詳細信息列表，包含以下字段： |
rows 陣列字段
| 字段名 | 類型 | 必選/可選 | 說明 |
|---|---|---|---|
message_id |
string | 必選 | 消息的唯一標識 |
from |
string | 可選 | 發送方，默認appkey |
to |
string | 可選 | 接收方的標識（如 registrationID） |
server |
string | 必選 | 消息服務名稱，取值範圍：AppPush、WebPush |
channel |
string | 必選 | 消息通道，取值範圍：EngageLab、Chrome、Firefox、Safari、Edge、Opera、Other |
custom_args |
object | 可選 | 消息創建時提交的自定義參數，此處原樣返回 |
itime |
int | 必選 | 消息狀態真實產生的時間戳，與message_status字段相結合，可以得到各個消息狀態的時間戳 |
status |
object | 必選 | 消息狀態信息，包含以下字段： |
status 對象字段
| 字段名 | 類型 | 必選/可選 | 說明 |
|---|---|---|---|
message_status |
string | 必選 | 消息狀態，取值範圍：target_valid、sent、delivered、click、target_invalid、sent_failed、delivered_failed、no_click |
status_data |
object | 可選 | 自定義狀態數據，包含以下字段： |
channel_message_id |
string | 可選 | 第三方通道的消息 ID |
ntf_msg |
int | 必選 | 消息類型，取值範圍：1: 通知消息、2: 自定義消息、7: 應用內消息 |
platform |
string | 必選 | 推送平台，取值範圍：b: web |
uid |
int | 必選 | 推送的 UID |
app_version |
string | 必選 | SDK 集成 app 版本，通過 SDK 上報數據獲得 |
channel |
string | 必選 | SDK 集成 app 渠道，通過 SDK 上報數據獲得 |
msg_time |
int | 必選 | 消息下發時間，調用 API 請求發送消息成功的時間點 |
time_zone |
string | 必選 | 組織所在時區 |
loss_valid_type |
int | 可選 | 該字段無實際意義，無需處理 |
plan_user_total |
int | 可選 | 該字段無實際意義，無需處理 |
callback_type |
int | 可選 | 該字段無實際意義，無需處理 |
error_code |
int | 可選 | 錯誤碼，僅在失敗時提供 |
error_detail |
object | 可選 | 錯誤詳細信息，僅在失敗時提供，包含以下字段： |
message |
string | 可選 | 描述詳細錯誤原因，僅 FCM 通道提供 |
loss |
object | 可選 | 折損信息，包含以下字段： |
loss_source |
string | 可選 | 折損來源，取值範圍：EngageLab、Chrome、Firefox、Safari、Edge、Opera、Other |
loss_step |
int | 可選 | 折損階段，取值範圍：1: 計劃目標→有效目標、2: 有效目標→發送數量、3: 發送數量→送達數量、4: 送達數量→點擊數量 |
消息狀態取值說明
| 狀態取值 | 含義 | 含義 |
|---|---|---|
target_valid |
有效目標 | 過去365天活躍過即被視為有效目標 |
sent |
發送成功 | 發送到服務器成功 |
delivered |
送達成功 | 以送達设备回調成功為成功送達 |
click |
用戶點擊 | 以sdk上報點擊為用戶點擊 |
target_invalid |
無效目標 | 根據折損表定義，在折損階段1的就為無效目標 |
sent_failed |
發送失敗 | 根據折損表定義，在折損階段2的就為無效目標 |
delivered_failed |
送達失敗 | 根據折損表定義，在折損階段3的就為送達失敗 |
no_click |
點擊失敗 | 根據折損表定義，在折損階段4的就為點擊失敗，僅應用內消息會有此事件 |
回調示例
請求報頭
POST /developer_define_url HTTP/1.1
Content-Type: application/json
POST /developer_define_url HTTP/1.1
Content-Type: application/json
此代碼塊在浮窗中顯示
請求體
{
"total": 1,
"rows": [
{
"message_id": "1666165485030094861", //engagelab側的消息id
"from": "", // 發送方
"to": "", // 接收方，registrationID
"server": "WebPush",
"channel": "Chrome",
"custom_args": {}, // 這條消息創建時提交的參數，將於此回調時原樣返回
"itime": 1640707579, // 消息狀態變更時的時間戳，如消息已送達的時間
"status": {
// 成功時響應這些字段
"message_status": "delivered", // 消息狀態
"status_data": { // 自定義
"channel_message_id": "wamid.123321abcdefed==" // 可選，第三方通道的msgid
"ntf_msg": 1, //消息類型
"platform": "a", //推送平台
"uid": 100, //推送的uid
"app_version": "", //sdk集成app版本，通過sdk上報數據獲得
"channel": "", //sdk集成app渠道，通過sdk上報數據獲得
"msg_time": 1640707579, //消息下發時間，調用 API 請求發送消息成功的時間點
"time_zone": "+8", //組織所在時區
"loss_valid_type": 0, //該字段無實際意義，無需處理
"plan_user_total": 0, //該字段無實際意義，無需處理
"callback_type": 0 //該字段無實際意義，無需處理
},
// 失敗時響應這些字段
"error_code": 0, //錯誤碼--對應生命周期錯誤碼
"error_detail": {
"message": "" //錯誤原因
},
"loss": {
"loss_source": "vivo",
"loss_step": 1
} //折損階段和折損來源
}
}
]
}
{
"total": 1,
"rows": [
{
"message_id": "1666165485030094861", //engagelab側的消息id
"from": "", // 發送方
"to": "", // 接收方，registrationID
"server": "WebPush",
"channel": "Chrome",
"custom_args": {}, // 這條消息創建時提交的參數，將於此回調時原樣返回
"itime": 1640707579, // 消息狀態變更時的時間戳，如消息已送達的時間
"status": {
// 成功時響應這些字段
"message_status": "delivered", // 消息狀態
"status_data": { // 自定義
"channel_message_id": "wamid.123321abcdefed==" // 可選，第三方通道的msgid
"ntf_msg": 1, //消息類型
"platform": "a", //推送平台
"uid": 100, //推送的uid
"app_version": "", //sdk集成app版本，通過sdk上報數據獲得
"channel": "", //sdk集成app渠道，通過sdk上報數據獲得
"msg_time": 1640707579, //消息下發時間，調用 API 請求發送消息成功的時間點
"time_zone": "+8", //組織所在時區
"loss_valid_type": 0, //該字段無實際意義，無需處理
"plan_user_total": 0, //該字段無實際意義，無需處理
"callback_type": 0 //該字段無實際意義，無需處理
},
// 失敗時響應這些字段
"error_code": 0, //錯誤碼--對應生命周期錯誤碼
"error_detail": {
"message": "" //錯誤原因
},
"loss": {
"loss_source": "vivo",
"loss_step": 1
} //折損階段和折損來源
}
}
]
}
此代碼塊在浮窗中顯示
折損階段:
- 計劃目標-》有效目標
- 有效目標-》已發送
- 已發送-》已送達
- 已送達-》點擊
注意：
1.部分通道的點擊和送達可能存在重複現象，開發者可自行進行去重處理。
2.發送成功5天之後的送達數量和展示數量不會再回調。
