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 | 必选 | 消息服务名称，取值范围：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天之后的送达数量和展示数量不会再回调。
