帮你快速理解、总结文档立即下载

全员/标签/单推回调

最近更新时间:2026-11-05 17:33:27
我的收藏

功能说明

开启推送插件后,全员/标签/单发推送的结果可以通过配置基础回调的方式,将结果转发给 App 后台。

注意事项

该回调属于下行扩散后的事件回调,为防止大量回调请求打垮 App 后台,默认 QPS:1000次/s。超频的回调会延迟一段时间重试,如果您因业务需求需要调整 QPS,可以 提交工单 申请。
要启用回调,必须配置回调 URL,并打开本回调对应的开关,配置方法详见 第三方回调配置 文档。
回调的方向是即时通信 IM 后台向 App 后台发起 HTTP POST 请求。
App 后台在收到回调请求之后,务必校验请求 URL 中的参数 SDKAppID 是否是自己的 SDKAppID。
其他安全相关事宜请参见 第三方回调简介:安全考虑 文档。

接口说明

请求 URL 示例

以下示例中 App 配置的回调 URL 为 https://www.example.com
https://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
发起推送时设置的参数。为 1 表示是 iOS 静默推送,无通知栏弹窗,苹果建议1小时最多推送3条静默消息。详情请参见:APNs Background Notification。
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
发起推送时设置的参数。含义:小米推送 MIUI 10 及以上的通知类别(Channel)适配字段。详细请参见:小米消息分类。该字段不为空时,会覆盖控制台推送证书配置的 ChannelID 值。

HuaWei Object 描述

字段
类型
说明
PushID
string
推送成功后,华为返回的厂商推送 ID,推送失败时该字段可能为空。如未收到推送,咨询华为推送时可能需要提供这个 ID 用于排查问题。
ChannelID
string
发起推送时设置的参数。含义:华为推送 EMUI 10.0 及以上的通知渠道字段。该字段不为空时,会覆盖控制台推送证书配置的 ChannelID 值。
Category
string
发起推送时设置的参数。含义:华为推送消息分类,用于标识消息类型,详细请参见: category 描述。
该字段不为空时,会覆盖控制台推送证书配置的 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
发起推送时设置的参数。含义:魅族推送消息分类,“0”代表公信消息,“1”代表私信消息,详细请参见: 魅族消息分类说明。
该字段不为空时,会覆盖控制台魅族推送证书配置的消息分类。

OPPO Object 描述

字段
类型
说明
PushID
string
推送成功后,OPPO 返回的厂商推送 ID,推送失败时该字段可能为空。如未收到推送,咨询 OPPO 推送时可能需要提供这个 ID 用于排查问题。
ChannelID
string
发起推送时设置的参数。含义:OPPO 推送 Android 8.0 及以上的 NotificationChannel 通知适配字段。
该字段不为空时,会覆盖控制台推送证书配置的 ChannelID 值。
Category
string
发起推送时设置的参数。含义:OPPO 推送消息分类,用于标识消息类型,详细请参见: category 描述
该字段不为空时,会覆盖控制台推送证书配置的 category 值。

VIVO Object 描述

字段
类型
说明
PushID
string
推送成功后,vivo 返回的厂商推送 ID,推送失败时该字段可能为空。如未收到推送,咨询 vivo 推送时可能需要提供这个 ID 用于排查问题。
Category
string
发起推送时设置的参数。含义:vivo 推送消息分类,用于标识消息类型,详细请参见 category 描述。
该字段不为空时,会覆盖控制台推送证书配置的 category 值。

Honor Object 描述

字段
类型
说明
PushID
string
推送成功后,荣耀返回的厂商推送 ID,推送失败时该字段可能为空。如未收到推送,咨询荣耀推送时可能需要提供这个 ID 用于排查问题。
Importance
string
发起推送时设置的参数。含义:荣耀推送消息分类,取值为 LOW、NORMAL,详细请参见:荣耀消息分类。

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
错误说明。