消息回调

将「消息状态」的数据回调给企业的业务系统，可根据该信息进行统计分析等动作。

回调地址

企业需要设置接收「消息状态变更」的回调地址，可在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`、`HuaWei`、`XiaoMi`、`MeiZu`、`OPPO`、`VIVO`、`HONOR`、`FCM`、`APNs`
`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: 自定义消息`、`5: ios实时活动消息`、`6: ios voip消息`、`7: 应用内消息`
`platform`	string	必选	推送平台，取值范围：`a: 安卓`、`i: ios`、`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`、`HuaWei`、`XiaoMi`、`MeiZu`、`OPPO`、`VIVO`、`HONOR`、`FCM`、`APNs`
`loss_step`	int	可选	折损阶段，取值范围：`1: 计划目标→有效目标`、`2: 有效目标→发送数量`、`3: 发送数量→送达数量`、`4: 送达数量→点击数量`

消息状态取值说明

状态取值	含义	含义
`target_valid`	有效目标	过去365天活跃过即被视为有效目标
`sent`	发送成功	发送到服务器成功
`delivered`	送达成功	EngageLab、XiaoMi、OPPO、VIVO以真实送达回调为成功送达； FCM和APNs是以成功发送到厂商服务器为成功送达； HuaWei、MeiZu、HONOR未配置厂商回调则以成功发送到厂商服务器为成功送达，配置了以厂商的真实回调为成功送达。
`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": "AppPush", "channel": "FCM", "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": "AppPush",
            "channel": "FCM",
            "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天之后的送达数量和展示数量不会再回调。

消息回调

回调地址

回调地址合法性校验

安全机制

应答机制

重试机制

回调内容

回调字段说明

消息主体

rows 数组字段

status 对象字段

消息状态取值说明

回调示例

请求报头

请求体

折损阶段

`rows` 数组字段

`status` 对象字段