功能说明
开启推送插件后,全员/标签/单发推送的结果可以通过配置基础回调的方式,将结果转发给 App 后台。
注意事项
该回调属于下行扩散后的事件回调,为防止大量回调请求打垮 App 后台,默认 QPS:1000次/s。超频的回调会延迟一段时间重试,如果您因业务需求需要调整 QPS,可以 提交工单 申请。
要启用回调,必须配置回调 URL,并打开本回调对应的开关,配置方法详见 第三方回调配置 文档。
回调的方向是即时通信 IM 后台向 App 后台发起 HTTP POST 请求。
App 后台在收到回调请求之后,务必校验请求 URL 中的参数 SDKAppID 是否是自己的 SDKAppID。
其他安全相关事宜请参见 第三方回调简介:安全考虑 文档。
接口说明
请求 URL 示例
以下示例中 App 配置的回调 URL 为
https://www.example.comhttps://www.example.com?SdkAppid=$SDKAppID&CallbackCommand=$CallbackCommand&contenttype=json
请求参数说明
字段 | 说明 |
https | 请求协议为 HTTPS; 请求方式为 POST。 |
www.example.com | 回调 URL。 |
SdkAppid | 创建应用时在即时通信 IM 控制台分配的 SDKAppID。 |
CallbackCommand | 固定为: Push.AllMemberPush。 |
contenttype | 请求包体固定为 json。 |
请求包示例
{"Events": [ // events数组长度范围为1~100{"CallbackCommand":"Push.AllMemberPush","EventType": 1, // 事件类型,EventType=1表示离线推送"TaskId": "657bf434_537529d8_2000005e80aa873_2780d131_bc614e", // 全员/标签/单推推送 TaskId"TaskTime": 1557481127, // 全员推送任务发起时间戳, 单位为秒"EventTime": 1557481128, // 事件发生时间戳, 单位为秒"To_Account": "user2", // 接受者"PushPlatform": 4, // 推送厂商"PushStage": 1, // 推送阶段"VendorInfo": {"FCM": { // 消息推送到FCM,这里包含了FCM厂商信息"PushID": "xxxx","ChannelID": "xxxx","PushType": 0}},"ErrCode": 0, // 推送事件结果"ErrInfo": "OK" // 推送事件结果描述,可能为空},{"CallbackCommand":"Push.AllMemberPush","EventType": 1, // 事件类型,EventType=1表示离线推送"TaskId": "657bf434_537529d8_2000005e80aa873_2780d131_9", // 全员/标签/单推推送 TaskId"TaskTime": 1557481127, // 全员推送任务发起时间戳, 单位为秒"EventTime": 1557481129, // 事件发生时间戳, 单位为秒"To_Account": "user3", // 接受者"PushPlatform": 1, // 推送厂商"PushStage": 1, // 推送阶段"VendorInfo": {"APNS": { // 消息推送到 APNS ,这里包含了 APNS 厂商信息"PushID": "EF956E0D-0322-A33C-B546-85540B78BEE8","MutableContent": 1,"PushType": 2,"IsDowngraded": 1,"DowngradeReason": "voip token not exist"}},"ErrCode": 0, // 推送事件结果"ErrInfo": "OK" // 推送事件结果描述,可能为空},....]}
请求包字段说明
字段 | 类型 | 说明 |
Events | Array [ Event Object ] | 批量回调内容,最多包含100个回调事件(Event Object)的数据。 |
Event Object 结构
字段 | 类型 | 说明 |
CallbackCommand | String | 回调命令。 |
EventType | Integer | 事件类型: EventType = 1 表示离线推送; EventType = 2 表示在线推送; EventType = 3 表示离线存储。 |
TaskId | String | 全员推送发送时返回的任务 ID。 |
DataId | String | 客户业务自定义标识,推送请求中未设置该字段时,回调中不返回该字段。 |
TaskTime | Integer | 全员推送任务发起时间戳,单位为秒。 |
EventTime | Integer | 事件发生时间戳,单位为秒。 |
To_Account | String | 消息接收者 UserID。 |
PushPlatform | Integer | 推送厂商(在线推送 EventType = 2/3 不区分厂商,默认返回 0 ): PushPlatform = 0表示未知厂商; PushPlatform = 1表示 Apple APNS 推送; PushPlatform = 2表示小米推送; PushPlatform = 3表示华为推送; PushPlatform = 4表示 Google FCM 推送; PushPlatform = 5表示魅族推送; PushPlatform = 6表示 OPPO 推送; PushPlatform = 7表示 vivo 推送; PushPlatform = 8表示荣耀推送; PushPlatform = 9表示鸿蒙推送。 |
DeviceType | Integer | 推送设备类型(离线推送 EventType = 1 不区分设备类型,离线推送时不返回该字段): DeviceType = 0表示未知设备; DeviceType = 1表示 Apple 设备; DeviceType = 2表示小米设备; DeviceType = 3表示华为设备; DeviceType = 4表示 Google 设备; DeviceType = 5表示魅族设备; DeviceType = 6表示 OPPO 设备; DeviceType = 7表示 vivo 设备; DeviceType = 8表示荣耀设备; DeviceType = 9表示鸿蒙设备。 |
PushStage | Integer | 推送阶段: PushStage = 1表示推送发送; PushStage = 2表示推送触达; PushStage = 3表示推送点击。 |
VendorInfo | Object | 推送发送给厂商时设置的关键参数以及厂商返回的推送 ID,如果推送发送成功了但是设备没有收到,用户可以获取这个 ID 去厂商自助咨询具体原因。 注意: 这个字段只有在 PushStage = 1 时才会带上。发往不同推送厂商的信息封装到不同的 Object 里: APNS:Object,推送发给 APNs 时才有这个字段。详见 APNS Object 的描述; XiaoMi:Object,推送发给小米时才有这个字段。详见 XiaoMi Object 的描述; HuaWei:Object,推送发给华为时才有这个字段。详见 HuaWei Object 的描述; FCM:Object,推送发给 FCM 时才有这个字段。详见 FCM Object 的描述; Meizu:Object,推送发给魅族时才有这个字段。详见 Meizu Object 的描述; OPPO:Object,推送发给 OPPO 时才有这个字段。详见 OPPO Object 的描述; VIVO:Object,推送发给 vivo 时才有这个字段。详见 VIVO Object 的描述; Honor:Object,推送发给荣耀时才有这个字段。详见 Honor Object 的描述; Hmony:Object,推送发给鸿蒙时才有这个字段。详见 Hmony Object 的描述。 |
ErrCode | Integer | 推送事件结果: ErrCode = 0表示成功; ErrCode 非0表示失败。 |
ErrInfo | String | 推送事件结果描述。结果描述为空时,回调中不返回该字段。 |
APNs Object 描述
字段 | 类型 | 说明 |
PushID | string | 推送成功后,APNs 返回的厂商推送 ID,推送失败时该字段可能为空。如未收到推送,咨询 APNS 推送时可能需要提供这个 ID 用于排查问题。 |
MutableContent | Integer | 发起推送时设置的参数。含义:为 1 表示开启 iOS 10+ 的推送扩展,默认为0。 |
InterruptionLevel | string | 发起推送时设置的参数。含义:iOS 15+ 的推送通知级别,取值只能是 active、critical、passive、time-sensitive 中的一个,详情请参见:APNs InterruptionLevel 描述。 |
ContentAvailable | Integer | |
PushType | Integer | 发起推送时请求的推送类型(为原始请求类型,发生降级时实际按普通通知下发): 0:普通通知; 1:透传(静默)推送; 2:VoIP 推送; 3:Live Activity(实时活动)推送。 |
IsDowngraded | Integer | 是否降级为普通通知,请求 VoIP 或 Live Activity 推送,但对应的 Token 不存在或已过期,且未设置不降级时,会降级为普通通知推送。 0:未降级; 1:已降级。 |
DowngradeReason | String | 降级原因,仅 IsDowngraded = 1 时返回。取值示例: voip token not exist:VoIP Token 不存在;attributes_type: xxx, start token not exist:发起 Live Activity 时,对应 attributes_type 的 Start Token 不存在;laid: xxx, token not exist:更新/结束 Live Activity 时,对应 Live Activity ID 的 Token 不存在;laid: xxx, token expired:更新/结束 Live Activity 时,对应 Live Activity ID 的 Token 已过期(超过 12 小时)。 |
XiaoMi Object 描述
字段 | 类型 | 说明 |
PushID | string | 推送成功后,小米返回的厂商推送 ID,推送失败时该字段可能为空。如未收到推送,咨询小米推送时可能需要提供这个 ID 用于排查问题。 |
ChannelID | string |
HuaWei Object 描述
字段 | 类型 | 说明 |
PushID | string | 推送成功后,华为返回的厂商推送 ID,推送失败时该字段可能为空。如未收到推送,咨询华为推送时可能需要提供这个 ID 用于排查问题。 |
ChannelID | string | 发起推送时设置的参数。含义:华为推送 EMUI 10.0 及以上的通知渠道字段。该字段不为空时,会覆盖控制台推送证书配置的 ChannelID 值。 |
Category | string | 该字段不为空时,会覆盖控制台推送证书配置的 category 值。 |
FCM Object 描述
字段 | 类型 | 说明 |
PushID | string | 推送成功后,FCM 返回的厂商推送 ID,推送失败时该字段可能为空。如未收到推送,咨询 FCM 推送时可能需要提供这个 ID 用于排查问题。 |
ChannelID | string | 发起推送时设置的参数。含义:Google 推送 Android 8.0 及以上的通知渠道字段。 |
PushType | Integer | 推送类型: 0:通知消息(Notification Message); 1:数据消息(Data Message)。 |
Meizu Object 描述
字段 | 类型 | 说明 |
PushID | string | 推送成功后,魅族返回的厂商推送 ID,推送失败时该字段可能为空。如未收到推送,咨询魅族推送时可能需要提供这个 ID 用于排查问题。 |
NoticeMsgType | integer | 该字段不为空时,会覆盖控制台魅族推送证书配置的消息分类。 |
OPPO Object 描述
字段 | 类型 | 说明 |
PushID | string | 推送成功后,OPPO 返回的厂商推送 ID,推送失败时该字段可能为空。如未收到推送,咨询 OPPO 推送时可能需要提供这个 ID 用于排查问题。 |
ChannelID | string | 发起推送时设置的参数。含义:OPPO 推送 Android 8.0 及以上的 NotificationChannel 通知适配字段。 该字段不为空时,会覆盖控制台推送证书配置的 ChannelID 值。 |
Category | string | 该字段不为空时,会覆盖控制台推送证书配置的 category 值。 |
VIVO Object 描述
字段 | 类型 | 说明 |
PushID | string | 推送成功后,vivo 返回的厂商推送 ID,推送失败时该字段可能为空。如未收到推送,咨询 vivo 推送时可能需要提供这个 ID 用于排查问题。 |
Category | string | 该字段不为空时,会覆盖控制台推送证书配置的 category 值。 |
Honor Object 描述
字段 | 类型 | 说明 |
PushID | string | 推送成功后,荣耀返回的厂商推送 ID,推送失败时该字段可能为空。如未收到推送,咨询荣耀推送时可能需要提供这个 ID 用于排查问题。 |
Importance | string |
Hmony Object 描述
字段 | 类型 | 说明 |
PushID | string | 推送成功后,鸿蒙返回的厂商推送 ID,推送失败时该字段可能为空。如未收到推送,咨询鸿蒙推送时可能需要提供这个 ID 用于排查问题。 |
PushType | Integer | 推送类型: 0:普通通知; 7:实况窗。 |
应答包示例
{"ActionStatus": "OK","ErrorInfo": "","ErrorCode": 0 // 0为回调成功,1为回调出错}
应答包字段说明
字段 | 类型 | 说明 |
ActionStatus | String | 请求处理的结果: OK 表示处理成功; FAIL 表示失败。 |
ErrorCode | Integer | 错误码。 |
ErrorInfo | String | 错误说明。 |