推送 payload 配置
更新时间： 2026/08/03 15:49:51
云信 IM 服务端支持自定义消息的推送配置。
用户在发送消息或者自定义系统通知时，可以通过入参 payload 来自定义推送配置，包括推送标题，消息类型，点击跳转形式、厂商原始参数等。为了集成多家厂商的推送服务，云信限定了 payload 的格式（JSON），当用户按照格式正确填写对应的推送参数后，云信会按厂商规则解析、过滤、补全，并组装成对应请求体，并透传给对应的厂商。
若 payload 格式填写不正确，可能会导致推送不成功。
本文主要介绍云信 payload 字段的使用说明，并提供各厂商对应的示例代码。
云信 payload 格式
云信的 payload 参数格式如下：
| 参数 | 类型 | 说明 |
|---|---|---|
| pushTitle | String | 公用参数，指定推送消息的标题。 |
| apsField | JSON | APNs 推送消息中的 aps 参数，可参考 APNs 推送消息示例。 |
| pushkitFirst | boolean | 是否优先使用 PushKit 推送（如果没有 PushKit 相关信息，则采用 APNs 推送）。 true：优先使用 PushKit 推送；false：优先使用 APNs 推送。 |
| notifyId | int | 推送通知的消息 ID（标识符），需要为 32 位整数。若 ID 相同，后一条会覆盖前一条通知。 |
| hwPassThroughField | JSON | 华为透传消息中的 Message 参数，可参考 华为透传消息示例。 |
| hwField | JSON | 华为通知栏消息中的 message.notification/androidConfig 参数，可参考 华为通知栏消息示例。 |
| honorPassThroughField | JSON | 荣耀透传消息中的 Message 参数，可参考 荣耀透传消息示例。 |
| honorField | JSON | 荣耀通知栏消息中的 Message.android 参数，可参考 荣耀通知栏消息示例。 |
| vivoField | JSON | vivo 推送消息的请求体参数，可参考 vivo 推送消息示例。 |
| oppoField | JSON | OPPO 推送消息中的 Message 参数，可参考 OPPO 推送消息示例。 |
| miField | JSON | 小米推送消息的请求体参数，可参考 小米推送消息示例。 |
| mzField | JSON | 魅族推送消息的请求体参数，可参考 魅族推送消息示例。 |
| fcmFieldV1 | JSON | 新版谷歌 FCM 推送消息中的 notification 参数，可参考 谷歌 FCM 推送消息示例。 |
| harmonyField | JSON | 鸿蒙推送消息中的 Message 参数，可参考 鸿蒙推送消息示例。 |
| androidField | JSON | 安卓系统厂商通用推送字段，可参考 安卓系统厂商推送字段。 |
安卓系统厂商通用推送字段
androidField 当前支持的结构如下：
JSON{
"clickAction": {
"type": 1,
"url": "",
"intentUri": "",
"intentAction": "",
"activity": ""
}
}
其中 type 的映射如下：
| 厂商 | type=1 | type=2 | type=3 |
|---|---|---|---|
| 华为 | 打开应用 | 打开 URL | 打开应用内页或 intent |
| Honor | 打开应用 | 打开 URL | 打开应用内页或 intent |
| OPPO | click_action_type=0 |
click_action_type=2 |
click_action_type=1/4/5 |
| vivo | skipType=1 |
skipType=2 |
skipType=4 |
| 魅族 | clickType=0 |
clickType=2 |
clickType=1 |
| 小米 | notify_effect=1 |
notify_effect=3 |
notify_effect=2 |
| FCM v1 | 不处理 | 不处理 | 仅 intentAction 会映射到 message.android.notification.click_action |
云信 payload 示例
云信 payload 示例如下：
JSON{
"pushTitle": "",
"notifyId": 12345,
"apsField": {},
"hwPassThroughField": {},
"hwField": {},
"honorPassThroughField": {},
"honorField": {},
"vivoField": {},
"oppoField": {},
"miField": {},
"mzField": {},
"fcmFieldV1": {},
"harmonyField": {},
"androidField": {
"clickAction": {
"type": 3,
"intentAction": "com.netease.demo.ACTION"
}
},
各个推送厂商的自定义透传参数支持以以下方式统一传递，云信会复制到各个厂商的对应自定义透传参数（需要开通开关）
"key": "value"
}
第三方推送厂商对应的 payload 示例
APNs 推送消息
JSON{
"pushTitle":"", // 指定推送消息的标题
"apsField": {
"alert" : {
"title" : "Game Request",
"subtitle" : "Five Card Draw",
"body" : "Bob wants to play poker"
},
"category" : "GAME_INVITATION"
}
}
apsField 中的字段说明，详见 APNs 官网文档。
小米推送消息
JSON{
"pushTitle":"",// 推送消息标题
"miField": {
// 小米推送的 extra 参数直接以以下方式传递：
"channel_id":"",//通知类别（Channel）的ID,消息模板绑定的 channel id
"template_id": "",//消息模板 id
"template_param": "{\"city\":\"北京\",\"userName\":\"%s\"}",//消息模板参数，值为 JSON 字符串。参数名、参数个数需要与小米侧模板配置保持一致
"sound":"",//自定义通知栏消息铃声 URI，铃声文件放在 Android app 的 raw 目录下
"ticker":"",//开启通知消息在状态栏滚动显示
"notify_foreground":"1",//开启或关闭 app 在前台时的通知弹出，1：弹出，2：不弹出，默认为1
"notify_effect":"1",//预定义通知栏消息的点击行为。1：通知栏点击后打开app的Launcher Activity，2：通知栏点击后打开app的任一Activity（开发者还需要传入intent_uri），3：通知栏点击后打开网页（开发者还需要传入web_uri）
"intent_uri":"",
"web_uri":"",
"jobkey":"",
"app_version":"",//可以接收消息的 app 版本号，用逗号分割
"app_version_not_in":"",//无法接收消息的app版本号，用逗号分割
"connpt":"",//指定在特定的网络环境下才能接收到消息。目前仅支持指定 wifi
"only_send_once":"1"//设置为1，表示该仅设备在线时发送一次，不缓存离线消息进行多次下发
}
}
extra开头的字段说明详见 小米官方文档。- 由于网易云信默认需占用 2 个 extra 字段用于内部逻辑，因此您最多可再添加 8 个字段（总数上限为 10 个）。
华为推送消息
华为推送消息分类通知栏消息和透传消息，两种类型分别传入 hwPassThroughField 和 hwField JSON 字符串来自定配置。
- 如果一条消息的
payload中同时包含hwPassThroughField和hwField，则该推送会作为透传消息。即hwPassThroughField生效，hwField的字段无效。 - 其他字段说明详见 华为官方文档。
华为通知栏消息
JSON{
"pushTitle":"",//消息标题
"hwField": {
"click_action": { "type": 1},//消息点击行为。type为1：打开应用自定义页面，type为2：点击后打开特定URL，type为3：点击后打开应用
"badge": {},//Android通知消息角标控制
"style":0,//通知栏样式
"androidConfig": {
"collapse_key":-1,//用户设备离线时，Push 服务器对离线消息缓存机制，默认为-1，详见官方文档 AndroidConfig.collapse_key
"urgency":"NORMAL",//透传消息投递优先级，详见官方文档AndroidConfig.urgency
"category":"IM",//标识消息类型，用于标识高优先级透传场景，详见官方文档 AndroidConfig.category
"data":""//自定义消息负载，详见官方文档AndroidConfig.data
}
}
}
华为透传消息
JSON{
"pushTitle":"",//消息标题
"hwPassThroughField": {
"data":"{\"1111\":\"22222\"}",//自定义消息负载,只支持字符串或json格式字符串
"android": {
"collapse_key":-1,//用户设备离线时，Push服务器对离线消息缓存机制,默认为-1，详见官方文档AndroidConfig.collapse_key
"urgency":"NORMAL",//透传消息投递优先级,详见官方文档AndroidConfig.urgency
"category":"IM",//标识消息类型,用于标识高优先级透传场景,，详见官方文档AndroidConfig.category
}
}
}
荣耀推送消息
荣耀推送消息分类通知栏消息和透传消息，两种类型分别传入 honorPassThroughField 和 honorField JSON 字符串来自定配置。
- 如果一条消息的
payload中同时包含honorPassThroughField和honorField，则该推送会作为透传消息。即honorPassThroughField生效，honorField的字段无效。 - 其他字段说明详见 荣耀官方文档。
荣耀通知栏消息
JSON{
"pushTitle":"", // 消息标题
"honorField":{
"biTag": "biTag001", // AndroidConfig.biTag
"data": "", // AndroidConfig.data
"notification": { // AndroidNotification
"bigBody": "the big body",
"bigTitle": "the big title",
"body": "the big body",
"title": "the big title",
"buttons": [{
"actionType": 0,
"data": "",
"intent": "",
"intentType": 0,
"name": "test"
}],
"clickAction": {// 消息点击行为
"action": "",
"intent": "intent://com.hihonor.codelabpush",
"type": 1,//1为打开应用自定义页面，2为点击后打开特定URL，3为点击后打开应用
"url": "https://www.vmall.com"
},
"image": "https://res.vmallres.com/SXppnESYv4K11DBxDFc2.png",
"importance": "NORMAL",
"style": 0,
"when": "2014-10-02T15:01:23.045123456Z"
}
}
}
荣耀透传消息
JSON{
"pushTitle":"", //消息标题
"honorPassThroughField": {
"data":"{\"1111\":\"22222\"}", // message.data
"android": {
"biTag":"", // AndroidCofig.biTag
}
}
}
vivo 推送消息
JSON{
"pushTitle":"",//消息标题
"vivoField": {
"skipType":"1",//点击跳转类型 1：打开APP首页 2：打开链接 3：自定义 4:打开app内指定页面，默认为1
"skipContent":"",//跳转内容,与skipType对应
"classification":"0",//消息类型 0：运营类消息，1：系统类消息。默认为0
"networkType":"-1",//网络方式 -1：不限，1：wifi下发送，不填默认为-1
"pushMode":"0",//推送模式 0：正式推送；1：测试推送，不填默认为0
"category":"IM" // 二级分类
}
}
vivoField 中的字段说明，详见 vivo 官方文档。
OPPO 推送消息
JSON{
"pushTitle":"",//消息标题
"oppoField": {
"channel_id": "", //指定下发的通道ID
"private_msg_template_id": "",//OPPO 私信模板 id
"private_title_parameters": {//标题模板参数
"city": "北京"
},
"private_content_parameters": {//内容模板参数
"userName": "%s" //昵称占位, %s 会被服务端替换为发送者昵称
},
"category":"IM", //通道类别名
"notify_level": 2, //通知栏消息提醒等级，1-通知栏；2-通知栏+锁屏；16-通知栏+锁屏+横幅+震动+铃声
"click_action_type": "", //点击通知栏后触发的动作类型。0（默认0.启动应用；1.跳转指定应用内页（action标签名）；2.跳转网页；4.跳转指定应用内页（全路径类名）；5.跳转Intent scheme URL: "",
"click_action_activity": "",
"click_action_url": "",
"action_parameters": "",
"style": 1, //通知栏样式
"sub_title": "", // 子标题
"network_type": 0, //推送的网络环境类型
}
}
oppoField 中的字段说明，详见 OPPO 官方文档。
魅族推送消息
JSON{
"pushTitle": "",
"mzField": {
"noticeBarInfo": {
"title": "",
"content": ""
},
"clickTypeInfo": {
"parameters": {
"key": "value"
}
}
}
}
mzField 中的字段说明，详见 魅族官方文档。
谷歌 FCM 推送消息
使用 FCM HTTP V1 协议推送需要申请 HTTP V1 鉴权证书。当使用该版本证书进行推送时，payload 中应使用 "fcmFieldV1" 字段配置自定义推送参数。服务器会根据用户SDK中配置的证书版本选取推送通道。
FCM HTTP V1 推送的更多信息请参考 官方文档。
JSON{
"fcmFieldV1":{
"validate_only": true,
"message": {
"needNotification": false, // 是否需要自动填充notification字段，默认true，当需要使用数据消息时，此字段需要设置为false
"notification": {
"image": "string"
},
"data": {
"name": "wrench",
"mass": "1.3kg",
"count": "3"
},
"android": {
"restricted_package_name": "string",
"data": {
"string": "string",
},
"notification": {
"channel_id": "string",
"color": "string",
},
"fcm_options": {
"analytics_label": "string"
},
"direct_boot_ok": true
}
}
}
}
鸿蒙推送消息
JSON{
"harmonyField": {
"payload": {
"notification": {
"category": "MARKETING",
"title": "普通通知标题",
"body": "普通通知内容",
"clickAction": {
"actionType": 0
},
"badge": {
"addNum": 1
},
"notifyId": 12345
}
},
"pushOptions": {
"testMessage": true,
"ttl": 1223
}
}
}
harmonyField 中的字段说明，详见 鸿蒙推送官网文档。
相关参考文档
更多推送参数说明请参考第三方推送厂商的官方文档：
此文档是否对你有帮助？
