有奖捉虫:办公协同&微信生态&物联网文档专题 HOT

接口说明

请求方式:POST。
服务地址/v3/push/app
接口服务地址与服务接入点一一对应,请选择与您的应用服务接入点对应的 服务地址
接口功能:Push API 是所有推送接口的统称。Push API 有多种推送目标,推送目标见下文。 所有请求参数通过 JSON 封装上传给后台,后台通过请求参数区分不同的推送目标。如有疑问请参见 服务端错误码
注意
腾讯云移动推送结合业务优化的需求,对全量推送、标签推送和号码包推送进行限频(1条/秒),官网控制台将与 API 同步调整。
如果超过此频率会返回错误码:1008028,请您自行调整推送频率,否则可能会引起推送异常。

必要参数

推送必要参数指一条推送消息必需携带的参数。
参数名
类型
是否必需
描述
audience_type
String
推送目标:
all:全量推送
tag:标签推送
token:单设备推送
token_list:设备列表推送
account:单账号推送
account_list:账号列表推送
package_account_push:号码包推送
package_token_push:token 文件包推送
message
Object
消息体,请参见 消息体类型
message_type
String
消息类型:
notify:通知
message:透传消息/静默消息
environment
String
是(仅 iOS 平台使用)
用户指定推送环境,仅限 iOS 平台推送使用:
product: 推送生产环境
dev: 推送开发环境
注册打包的环境与推送环境需要保存一致,请参见 推送环境选择说明
upload_id
Integer
是(仅号码包推送\\ token 文件包推送时使用)
号码包或 token 包的上传 ID

audience_type:推送目标

推送目标,表示一条推送可以被推送到哪些设备。 Push API 提供了多种推送目标,例如全量、标签、单设备、设备列表、单账号、账号列表。
推送目标
描述
必需参数及使用说明
all
全量推送
tag
标签推送
tag_rules(推荐使用):
标签组合推送,可设置'与'、'或'、'非'组合规则
注意:当与 tag_list 二者共存时,tag_list 字段自动无效,参数说明请查看 tag_rules 参数说明tag_list(后续不再更新):
推送 tag1 和 tag2 的设备{"tags":["tag1","tag2"],"op":"AND"}
推送 tag1 或 tag2 的设备{"tags":["tag1","tag2"],"op":"OR"}
标签列表不能超过512个字符
token
单设备推送
token_list
如果该参数包含多个 token 只会推送第一个 token
格式 eg:[“token1”]
token 字符串长度不能超过36
token_list
设备列表群推
token_list
最多1000个 token
格式 eg:["token1","token2"]
token 字符串长度不能超过36
注意:若列表超过1000个 token,推送会失败,如需推送更大批量 token,建议您使用 上传 Token 包推送
account
单账号推送
account_list
该参数有多个账号时,仅推送第一个账号
格式 eg:["account1"]
account_list
账号列表群推
account_list
最多1000个 account
格式 eg:["account1","account2"]
注意: 若列表超过1000个 account,推送会失败,如需推送更大批量 account,建议您使用 号码包推送
package_account_push
号码包推送
上传号码包推送必填
package_token_push
token 文件包推送
上传 token 文件包推送必填
全量推送:推送给全部设备。
{
"audience_type": "all"
}
标签推送(tag_rules 方式):广东和湖南,并且是20200408当天活跃过的男性用户。
{
"audience_type": "tag",
"tag_rules": [
{
"tag_items": [
{
"tags": [
"guangdong",
"hunan"
],
"is_not": false,
"tags_operator": "OR",
"items_operator": "OR",
"tag_type": "xg_auto_province"
},
{
"tags": [
"20200408"
],
"is_not": false,
"tags_operator": "OR",
"items_operator": "AND",
"tag_type": "xg_auto_active"
},
{
"tags": [
"male"
],
"is_not": false,
"tags_operator": "OR",
"items_operator": "AND",
"tag_type": "xg_user_define"
}
],
"operator": "OR",
"is_not": false
}
]
}
单设备推送:推送给 token 为 token1 的设备。
{
"audience_type": "token",
"token_list": [
"token1"
]
}
设备列表推送,推送给 token 为 token1 和 token2 的设备。
{
"audience_type": "token_list",
"token_list": [
"token1",
"token2"
]
}
单账号推送:推送给账号为 account1 的设备。
{
"audience_type": "account",
"account_list": [
"account1"
]
}
账号列表推送:推送账号为 account1 和 account2 的设备。
{
"audience_type": "account_list",
"account_list": [
"account1",
"account2"
]
}

message_type:消息类型

针对不同平台,消息类型稍有不同,具体参照下表:
消息类型
描述
支持平台
特性说明
notify
通知栏消息
Android & iOS
通知栏展示消息 。
注意:该字段与 content-available: 1 互斥,请勿同时使用。
message
透传消息/静默消息
Android(透传消息)
iOS(静默消息)
通知栏不展示消息。
注意:因厂商限制,Android 透传消息只通过移动推送自建通道下发,无法通过厂商通道下发

message:消息体

消息体,即下发到客户端的消息。 Push API 对 iOS 和 Android 两个平台的消息有不同处理,需要分开来实现对应平台的推送消息,推送的消息体是 JSON 格式。

Android 普通消息

Android 平台具体字段如下表:
字段名
类型
父项目
默认值
必需
参数描述
title
String
message
消息标题
content
String
message
消息内容
accept_time
Array
message
消息将在哪些时间段允许推送给用户。
单个元素由 "start" 和 "end" 组成的起止时间对组成
"start" 和 "end" 由 hour (小时)和 min(分钟)描述对应时刻,详细参考具体示例。
注意:因厂商限制, 仅对移动推送自建通道有效
thread_id
String
message
通知分组折叠的组别识别名
注意:因厂商限制, 仅对移动推送自建通道有效
thread_sumtext
String
message
通知分组折叠后显示的摘要,thread_id 非空时有效
注意:因厂商限制, 仅对移动推送自建通道有效
xg_media_resources
String
message
通知栏大图片 url 地址,仅对移动推送自建通道和小米通道生效;
注意:如需使用小米通道大图通知功能,需先调用小米图片上传接口上传图片文件,获取小米指定的图片地址 pic_url ,再填入移动推送推送对应的参数 xg_media_resources 中。
xg_media_audio_resources
String
message
音频富媒体元素地址。
支持 mp3 格式音频,建议大小在5MB以内。
注意:仅移动推送自建通道支持该参数下发,其他通道不下发该参数
android
Object
message
安卓通知高级设置结构体,请参见 Android 结构体说明

Android 结构体说明

字段名
类型
父项目
默认值
必需
参数描述
n_ch_id
String
android
通知渠道 ID(仅移动推送自建通道生效),请参见 创建通知渠道
n_ch_name
String
android
通知渠道名称(仅移动推送自建通道生效) ,请参见 创建通知渠道
n_category
String
android
通知分类(仅移动推送自建通道且 Android SDK1.4.3.1及以上版本生效),请参见 移动推送自建通道通知分类说明

注意:适配华为本地通知自分类可使用此字段,详细请参见 华为本地通知适配说明
n
_importance

Integer
android
4
通知渠道优先级(仅移动推送自建通道且 Android SDK1.4.3.1及以上版本生效),请参见 移动推送自建通道通知渠道优先级说明
1: 对应 Android 系统的 IMPORTANCE_MIN
2: 对应 Android 系统的 IMPORTANCE_LOW
3: 对应 Android 系统的 IMPORTANCE_DEFAULT
4: 对应 Android 系统的 IMPORTANCE_HEIGHT
注意:仅在首次创建通知的 Channel 时生效,如本地已有相同的通知渠道此字段不生效。
xm_ch_id
String
android
小米渠道 ID(仅小米推送通道生效)。
fcm_ch_id
String
android
FCM 渠道 ID(仅 FCM 推送通道生效)。
hw_biz_type
Integer
android
0
是否开启华为快通知:
1:开启
0:关闭
注意:仅华为通道有效,其需要 联系华为商务 开通
urgency
string
android
NORMAL
华为/荣耀通道下发的消息紧急程度,取值HIGH、NORMAL(默认)。
oppo_top_notification_bar_show
Bool
android
false
OPPO 置顶功能:
true:置顶
false:不置顶
注意:仅OPPO通道有效,其需要 联系 OPPO 商务 开通
oppo_senior_push
Bool
android
false
OPPO 商业化推送(用于置顶和免折叠) :
true:不占个人配额和总配额
false:占用普通总额和个人配额
其需要 联系 OPPO 商务 开通。
oppo_advertiser_id
String
android
OPPO 广告主 ID,OPPO 厂商分配。
vivo_marketing
Object
android
vivo vpush 商业化字段,仅 vivo 通道有效,包含广告模板 ID、消息样式等,详情参见 vivo_marketing 参数说明,其需要 联系 vivo 商务 开通。
hw_ch_id
String
android
华为渠道 ID(仅 华为推送通道生效)
说明:如果您应用的数据处理位置为中国区时通知渠道无效,详细说明请您参见华为自定义渠道文档。

hw_category
String
android
华为消息类型标识,确定消息提醒方式,对特定类型消息加快发送,参数详情请参见 华为的请求参数说明 的 category 参数。
IM:即时聊天
VOIP:音视频通话
SUBSCRIPTION:订阅

hw_importance

Integer
android
华为消息的提醒级别,取值如下:
1:表示通知栏消息预期的提醒方式为静默提醒,消息到达手机后,无铃声震动。
2:表示通知栏消息预期的提醒方式为强提醒,消息到达手机后,以铃声、震动提醒用户。终端设备实际消息提醒方式将根据 hw_category 字段取值或者 智能分类 结果进行调整。
荣耀消息分类,对不同类别消息的展示 ,取值如下:
1:表示消息为资讯营销类,默认展示方式为静默通知,仅在下拉通知栏展示。
2:表示消息为服务通讯类,默认展示方式为锁屏展示+下拉通知栏展示。
oppo_ch_id
String
android
OPPO 渠道 ID(仅 OPPO 推送通道生效)
vivo_category
String
android
vivo 消息类型标示,根据 vivo 推送消息分类规范,自行对消息进行分类,请在发送消息时携带 vivo_category 字段并正确赋值,参数值详情请参见 vivo 消息分类
IM:即时聊天
ACCOUNT:账号与资产变动
SUBSCRIPTION:订阅提醒
注意:赋值请按照消息分类规则填写,且必须大写;若传入错误无效的值,否则返回错误码10096。
vivo_ch_id
String
android
0
vivo 渠道 ID:“0”代表运营消息,“1”代表系统消息(仅 vivo 推送通道生效)。
说明:该字段即将下线,请6月30号之前申请 vivo_category 参数传值,否则被判为运营消息(推送受限)。
builder_id
Integer
android
0
本地通知样式标识,指定成您在终端预设的样式id, 不传则不指定。
badge_type
Integer
android
-1
通知角标:
-2:自动增加1,支持华为设备
-1:不变,支持华为、vivo 设备
[0, 100):直接设置,支持华为、vivo 设备
注意:不同厂商设备的角标适配能力不同,各参数值实现效果请参见 角标适配指南
ring
Integer
android
1
是否有铃声:
0:没有铃声
1:有铃声
ring_raw
String
android
指定 Android 工程里 raw 目录中的铃声文件名,不需要后缀名。
说明:自定义铃声仅华为、小米、FCM 和移动推送自建通道支持,需配合n_ch_id字段使用,配置步骤可参考 如何设置自定义铃声
vibrate
Integer
android
1
是否使用震动:
0:没有震动
1:有震动
lights
Integer
android
1
是否使用呼吸灯:
0:不使用呼吸灯
1:使用呼吸灯
clearable
Integer
android
1
通知栏是否可清除:
0: 不可清理
1: 可清理
icon_type
Integer
android
0
指定通知栏缩略图显示的是应用内图标还是网络资源图标 :
0:应用内图标,仅对移动推送自建通道有效
1:网络资源图标,仅移动推送自建通道、FCM、华为、荣耀通道支持
icon_res
String
android
指定通知栏缩略图的具体图片资源 :
当 icon_type = 0:填写 Android 应用内的图片资源文件名称(不带文件后缀),仅对移动推送自建通道有效
当前 icon_type = 1:填写缩略图 url 地址,缩略图格式要求可参见 富媒体通知文档,仅移动推送自建通道、FCM、华为、荣耀通道支持
style_id
Integer
android
1
设置是否覆盖指定编号的通知样式:
0: 不覆盖下发的样式
1: 优先使用在终端设置的样式
small_icon
String
android
消息在状态栏显示的图标,若不设置,则显示应用图标
icon_color
Integer
android
0
通知栏小图标染色
仅移动推送自建通道有效
需要使用 RGB 颜色的十进制值,例如 RGB 颜色 #01e240,请填入123456,
0:默认不染色。
action
Object
android
设置点击通知栏之后的行为,默认为打开 App,详情参考 action 参数说明
custom_content
String
android
用户自定义的参数(需要序列化为 JSON String)获取方式详见 通知点击跳转-客户端获取参数
说明:
华为官方通知:「2021年9月30日起停用V2协议」。移动推送已将华为推送协议升级到V5,V5协议不支持通过【附加参数】字段携带自定义参数。如果您集成了华为厂商通道,建议您改用 Intent 方式携带自定义参数,否则将导致自定义参数不能成功通过华为推送通道下发。

show_type
Integer
android
2
应用前台时,是否展示通知 。 默认展示,仅对移动推送自建通道、FCM 通道有效
1:不展示
2:展示
说明:
若取值为1且应用在前台,终端用户对该条推送无感知,但有抵达数据上报。


vivo_marketing 参数说明

字段名
类型
父项目
默认值
必需
参数描述
creative_id
Int64
vivo_marketing
vivo 广告模板ID,开发者可前往 vivo 营销平台创建通知广告模板,详情请参见vivo付费服务接口文档,其需要 联系 vivo 商务开通。 非vivo付费服务请忽略。
style_type
Int64
vivo_marketing
标题+内容:id =1,类型纯文本
标题+内容+小图:id=2,类型小图
标题+内容+大图+小图(可选):id=3,类型大图
标题+内容+组图/三图+小图(可选):id=4,类型组图/三图
详情请参见vivo付费服务接口文档,其需要 联系 vivo 商务开通。 非vivo付费服务请忽略。
price
String
vivo_marketing
出价,系统以此价格为准进行实时 cpc 计费,该价格不得低于与 vivo 商务商定价格,其需要 联系 vivo 商务开通。 非vivo付费服务请忽略。
style
Struct
vivo_marketing
vivo 付费通道样式,详情请参见vivo付费服务接口文档,其需要联系 vivo 商务开通。 非vivo付费服务请忽略。

vivo_style 参数说明

字段名
类型
父项目
默认值
必需
参数描述
small_image_id
Int64
vivo_style
小图,请填写上传图片后所获得图片 ID(需要在vivo 侧上传),详情请参见vivo付费服务接口文档,其需要联系 vivo 商务开通。非vivo付费服务请忽略。
large_image_id
Int64
vivo_style
大图,请填写上传图片后所获得图片 ID(需要在 vivo 侧上传),详情请参见vivo付费服务接口文档,其需要联系 vivo 商务开通。非vivo付费服务请忽略。
buttons
array
vivo_style
最多可填写 3 个按钮,单个按钮长度不超过 12 个字符(6 个汉字或 12 个英文字母) 支持每个按钮单独配置 deeplink 链接,详情请参见vivo付费服务接口文档,其需要联系 vivo 商务开通。非vivo付费服务请忽略。

vivo_button 参数说明

字段名
类型
父项目
默认值
必需
参数描述
name
String
vivo_button
按钮名字,详情请参见vivo付费服务接口文档,其需要联系 vivo 商务开通。非vivo付费服务请忽略。
skip_type
Int
vivo_button
单击跳转类型:
1:打开 App 首页
2:打开链接
4:打开 App 内指定页面
详情请参见vivo付费服务接口文档,其需要联系 vivo 商务开通。非vivo付费服务请忽略。
skip_content
String
vivo_button
跳转内容 跳转类型为 2 时,跳转内容最大 1000 个字符,跳转类型为 4 时,跳转 内容最大 1024 个字符。关于 skipContent 的内容可 以参考【vivo 推送常见问题】,其需要联系vivo 商务开通。 非vivo付费服务请忽略。

action 参数说明

字段名
类型
父项目
默认值
必需
参数描述
action_type
Integer
action
1
点击动作类型,
1:打开 activity 或 App 本身
2:打开浏览器
3:打开 App 自定义页面(推荐使用,参考 使用 Intent 方式跳转指引
activity
String
action
action_type 为1,且需要打开 activity 时必选
activity 完整名称,例如 com.x.y.PushActivity
aty_attr
Object
action
action_type 为1,且需要打开 activity 时可选
activity 属性
if:Intent 的 Flag 属性,类型为 Integer
pf:PendingIntent 的 Flag 属性,类型为 Integer
browser
Object
action
action_type 为2时必选
打开浏览器操作,
url:网页地址,仅支持 http、https,类型为 String
confirm:是否需要用户确认,类型为 Integer
1:需要确认
0:不需要确认
intent
String
action
action_type 为3时必选
自定义 scheme,例如 xgscheme://com.tpns.push/notify_detail
完整的消息示例如下:
{
"title": "xxx",
"content": "xxxxxxxxx",
"xg_media_resources": "xxx" , //此处填富媒体元素地址,例如https://www.xx.com/img/bd_logo1.png?qua=high
"xg_media_audio_resources":"xxx", //此处填音频富媒体元素地址,例如http://sc1.111ttt.cn/2018/1/03/13/396131227447.mp3
"thread_id":"活动_id",
"thread_sumtext":"运营活动",
"accept_time": [
{
"start": {//时间段起始时间,
"hour": "13",//起始时间 小时值, 取值 [0:24)
"min": "00"// 起始时间 分钟值, 取值[0:60)
},
"end": {//时间段结束时间
"hour": "14",//结束时间 小时值, 取值 [0:24)
"min": "00" //结束时间 分钟值,取值[0:60)

}
},
{
"start": {
"hour": "00",
"min": "00"
},
"end": {
"hour": "09",
"min": "00"
}
}
],
"android": {
"n_ch_id": "default_message",
"n_ch_name": "默认通知",
"builder_id": 0,
"ring": 1,
"ring_raw": "ring",
"badge_type":-1,
"vibrate": 1,
"lights": 1,
"clearable": 1,
"icon_type": 0,
"icon_res": "xg",
"style_id": 1,
"small_icon": "xg",
"action": {
"action_type": 1,// 动作类型,1,打开activity或app本身;2,打开浏览器;3,打开Intent
"activity": "com.x.y.PushActivity",
"aty_attr": {// activity属性,只针对action_type=1的情况
"if": 0, // Intent的Flag属性
"pf": 0 // PendingIntent的Flag属性
},
"browser": {
"url": "https://cloud.tencent.com ", // 仅支持http、https
"confirm": 1 // 是否需要用户确认
},
"intent": "xgscheme://com.tpns.push/notify_detail" //SDK版本需要大于等于1.0.9,然后在客户端的intent配置data标签,并设置scheme属性
},
"custom_content":"{\\"key\\":\\"value\\"}"
}
}

iOS 通知消息

iOS 平台具体字段如下表:
字段名
类型
父项目
默认值
必需
参数描述
title
String
message
消息标题,此字段会覆盖 alert 下的 title 中的内容。
content
String
message
消息内容,此字段会覆盖 alert 下的 body 中的内容。
thread_id
String
message
通知分组折叠的组别识别名
ios
Object
message
iOS 消息结构体,请参见 iOS 字段说明
show_type
Integer
message
2
应用前台时,是否展示通知 。
1:不展示
2:展示
说明:若取值为1且应用在前台,终端用户对该条推送无感知,但有抵达数据上报。
xg_media_resources
String
message
图片、音视频富媒体元素 url 地址,详情请参见 富媒体通知

iOS 字段说明

字段名
类型
父项目
默认值
必需
参数描述
aps
Object
ios
苹果推送服务(APNs)特有的消息体字段,请参见 aps 参数说明,其他详细介绍请参见官网 Payload
custom_content
String
ios
自定义下发的参数,需要序列化为 json string
aps 参数说明
字段名
类型
父项目
默认值
必需
参数描述
alert
Object
aps
包含标题和消息内容
badge_type
Integer
aps
用户设置角标数字:
-1:角标数字不变
-2:角标数字自动加1
>=0:设置自定义角标数字
category
String
aps
下拉消息时显示的操作标识
mutable-content
Integer
aps
1
通知拓展参数。
推送的时候携带 "mutable-content":1,说明是支持 iOS 10 的 Service Extension
开启后,推送详情中会有抵达数据上报,使用该功能前请按照 通知服务扩展的使用说明 实现 Service Extension 接口,如果不携带此字段则没有抵达数据上报
注意:
如果消息有富媒体信息(xg_media_resources字段)此字段强制取值为1

sound
String
aps
sound 字段使用情况如下:
播放系统默认提示音,"sound":"default"
播放本地自定义铃声,"sound":"chime.aiff"
静音效果,"sound":"" 或者是去除 sound 字段。
自定义铃声说明:格式必须是 Linear PCM、MA4(IMA/ADPCM)、alaw,μLaw 的一种,将声频文件放到项目 bundle 目录中,且时长要求30s以下,否则就是系统默认的铃声。
interruption-level
String
aps
active
仅对 iOS 15 以后的设备生效,需要在Capability 中打开Time Sensitive Notifications选项,有4个值可以选择设置:
passive:被动通知,即并不需要及时关注的通知。
active:主动通知,默认的通知。
time-sensitive:时效性通知,需要人们立刻注意的通知。
critical:重要通知,需要立刻关注的通知。
完整的消息示例如下:
{
"title": "xxx",
"content": "xxxxxxxxx",
"thread_id":"活动_id",
"xg_media_resources":"https://www.xx.com/img/bd_logo1.png",
"show_type":1,
"ios":{
"aps": {
"alert": {
"subtitle": "my subtitle"
},
"badge_type": 5,
"category": "INVITE_CATEGORY",
"sound":"default",
"interruption-level":"time-sensitive",
"mutable-content":1
},
"custom_content":"{\\"key\\":\\"value\\"}"
}
}

Android 透传消息

透传消息,Android 平台特有,即不显示在手机通知栏中的消息,可以用来实现让用户无感知的向 App 下发带有控制性质的消息。
注意
因厂商限制,Android 透传消息只通过移动推送自建通道下发,无法通过厂商通道下发。
Android 平台具体字段如下表:
字段名
类型
父项目
默认值
是否必需
参数描述
title
String
message
命令描述
content
String
message
命令内容
android
Object
message
安卓消息结构体
accept_time
Array
message
消息将在哪些时间段允许推送给用户。
单个元素由 "start" 和 "end" 组成的起止时间对组成。
"start" 和 "end" 由 hour (小时)和 min(分钟)描述对应时刻,详细参考具体示例。
注意:因厂商限制, 仅对移动推送自建通道有效。
custom_content
String
android
需要序列化为 json string
具体完整示例:
{
"title": "this is title",
"content": "this is content",
"android": {
"custom_content":"{\\"key\\":\\"value\\"}"
},
"accept_time": [
{
"start": {
"hour": "13",
"min": "00"
},
"end": {
"hour": "14",
"min": "00"
}
},
{
"start": {
"hour": "00",
"min": "00"
},
"end": {
"hour": "09",
"min": "00"
}
}
]
}

iOS 静默消息

静默消息,iOS 平台特有,类似 Android 中的透传消息,消息不展示,当静默消息到达终端时,iOS 会在后台唤醒 App 一段时间(小于30s),让 App 来处理消息逻辑。
具体字段如下表:
字段名
类型
父项目
默认值
是否必要
参数描述
ios
Object
message
ios 消息结构体
aps
Object
ios
苹果推送服务(APNs)特有的,其中最重要的键值对如下:
content-available:标识消息类型(必须为1),类型为 Integer
不能包含 alert、sound、badge_type 字段,详细介绍请参见 Payload
注意:content-available: 1与 message_type:"notify" 字段互斥,请勿同时使用
custom_content
String
ios
需要序列化为 json string
具体完整示例:
{
"ios":{
"aps": {
"content-available": 1
},
"custom_content":"{\\"key\\":\\"value\\"}"
}
}

iOS LiveActivity

实时活动,用户可以通过 ActivityKit 开发锁屏状态下的实时活动界面或开发基于灵动岛的动画效果,可以通过 APNs 发送远程通知来更新或结束实时活动。
具体字段如下表:
字段名
类型
父项目
默认值
是否必要
参数描述
activity
String
终端 ActivityKit 初始化活动 ID
event
String
aps
事件类型,更新实时活动取值 update ,结束实时活动取值 end
content-state
Object
aps
实时活动内容更新,KV 格式,用户配合终端所需内容自行定义及解析
dismissal-date
Integer
aps
4小时
当结束实时活动, event 为 end 时生效,不填则默认4小时后消失,若取值为过去时间则立马消失,若取值4小时以内的时间则按指定时间消失
说明:
当使用实时活动时,message_type 取 notify 值。
具体完整示例:
{
"audience_type": "activity",
"activity": "6F21C4FC-5FB0-4310-AA13-C7B12FD6FAEF",
"environment": "dev",
"message_type": "notify",
"message": {
"ios": {
"aps": {
"event": "update",
"dismissal-date":1684310548,
"content-state": {
"step": "inProgress",
"describe": "Delivery Update756"
},
"sound":"mysound.wav",
"alert": {

}
},
"custom_content": "{\\"key\\":\\"value\\"}"
}
}
}


可选参数

Push API 可选参数是除了audience_typemessage_typemessage以外,可选的高级参数。
参数名
类型
父项目
必需
默认值
描述
expire_time
Integer
86400(24小时)
消息离线存储时间(单位为秒),最长72小时
若 expire_time = 0,则表示实时消息
若 expire_time 大于0,且小于800s,则系统会重置为800s
若expire_time >= 800s,按实际设置时间存储,最长72小时
设置的最大值不得超过259200,否则会导致推送失败
如需调整离线消息时间,请联系 在线客服 申请
channel_expires
Array[{"chanel":string,"expire_time":int}]
在推送接口中填写 channel_expires 字段后, 在推送流程中,会区分此类型消息和普通消息,单独使用通道的特殊离线消息时长,其他通道则使用默认值 expire_time 过期时间,消息离线存储时间(单位为秒),最长72小时
若 expire_time = 0,则表示实时消息
若 expire_time 大于0,且小于800s,则系统会重置为800s
若 expire_time >= 800s,按实际设置时间存储,最长72小时
设置的最大值不得超过259200,否则会导致推送失败
如需调整离线消息时间,请联系 在线客服 申请
send_time
String
当前系统时间
定时推送任务,指定推送时间,可选择未来90天内的时间:
格式为 yyyy-MM-DD HH:MM:SS
若小于服务器当前时间,则会立即推送
仅全量推送、号码包推送和标签推送支持此字段
multi_pkg
Boolean
false
多包名推送:当 App 存在多个渠道包(例如应用宝、豌豆荚等),并期望推送时所有渠道的 App 都能收到消息,可将该值设置为 true。
注意:该参数默认控制移动推送自建通道的多包名推送,需要实现厂商通道多包名推送详见 厂商通道多包名配置 文档
loop_param
Object
0
仅全量推送、号码包推送和标签推送支持此字段,详情见下文 loop_param 参数说明
plan_id
String
推送计划 ID,推送计划创建及使用方式可 参考文档
tag_rules
Array
仅标签推送必需
标签组合推送,可设置'与'、'或'、'非'组合规则
注意:当与 tag_list 二者共存时,tag_list 字段自动无效,参数说明请查看 tag_rules 参数说明
account_list
Array
单账号推送、账号列表推送时必需
若单账号推送:
要求 audience_type = account
参数格式:[ "account1" ]
若账号列表推送:
参数格式:["account1","account2"]
最多1000 个 account
account_push_type
Integer
账号推送时可选
0
0:往账号的最新的 device 上推送信息
1:往账号关联的所有 device 设备上推送信息
account_type
Integer
0
账号类型,需要与推送的账号所属类型一致,取值可参考 账号类型取值表
token_list
Array
单设备推送、设备列表推送时必需
若单设备推送:
要求 audience_type=token
参数格式:[ "token1" ]
若设备列表推送:
参数格式:[ "token1","token2" ]
最多1000个 token
ignore_invalid_token
Integer
0
0:代表如果有无效的token则这个接口调用失败
1:代表忽略无效的token继续进行下发
注意:仅对 token 列表推送和单 token 推送有效
push_speed
Integer
推送限速设置每秒 X 条,X 取值参数范围1000 - 50000
仅全量推送、号码包推送和标签推送有效
collapse_id
Integer
系统默认分配一个 collapse_id
消息覆盖参数,在前一条推送任务已经调度下发后,如果第二条推送任务携带相同的 collapse_id 则会停止前一条推送中尚未下发的移动推送自建通道数据,同时会覆盖展示第一条推送任务的消息。
已完成任务的 collapse_id 可以通过 单个任务推送信息查询接口 获取。
目前仅支持全推、标签推送、号码包推送。
channel_rules
Array
推送通道选择策略。
可自定义该条推送允许通过哪些通道下发,默认允许通过所有通道下发,详细推送策略参考 通道策略
channel_rules 数组单元素数据结构见下 channel_rules 参数说明
tpns_online_push_type
Integer
0
在线设备是否通过移动推送自建通道下发:
0:默认在线走移动推送自建通道下发
1:在线不优先走移动推送自建通道下发
force_collapse
Boolean
false
对于不支持消息覆盖的 OPPO 、vivo 通道的设备,是否进行消息下发。
false:不下发消息
true:下发消息
说明
对于 collapse_id,有以下使用条件:
暂不支持用户自定义此参数,需要移动推送生成的 collapse_id。
目前仅支持移动推送自建通道、APNS 通道、小米通道、魅族通道以及华为系统版本 EMUI10 及以上的设备。
对于华为通道,覆盖消息时携带自定义参数需要使用 intent 方式,如使用 custom_content 方式携带自定义参数,接口层会进行拦截。
目前 OPPO 通道 vivo 通道不支持覆盖消息。当新创建覆盖消息时可通过 force_collapse 字段设置为 false 来关闭 vivo、OPPO 通道的下发。

tag_rules 参数说明

字段
类型
父项目
必填
描述
tag_items
Array
tag_rules
标签规则,参见 tag_items 说明
operator
String
tag_rules
tag_rules 数组内各元素的运算符,第一个 tag_rules 元素的 operator 为无效数据,第二个 tag_rules 元素的 operator 作为第一个和第二个 tag_rules 元素之间的运算符。
OR: 或运算
AND:且运算
is_not
Boolean
tag_rules
是否对 tag_items 数组的运算结果进行非运算。
true:进行非运算
false:不进行非运算

tag_items 说明

字段
类型
父项目
必填
描述
tags
Array
tag_items
具体标签值,类型:string,如 tag1,guangdong 等。
is_not
Boolean
tag_items
是否对 tag 数组的运算结果进行非运算。
true:非运算
false:不进行非运算
tags_operator
String
tag_items
tags 内标签对应的运算符。
OR:或运算
AND:且运算
items_operator
String
tag_items
tag_items 数组内各元素的运算符,第一个 tag_items 元素的 items_operator 为无效数据,第二个 tag_items 元素的 items_operator 作为第一个和第二个 tag_items 元素之间的运算符。
OR :或运算
AND :且运算
注意:不同规则之间运算符逻辑优先级「AND」>「OR」
tag_type
String
tag_items

tag_type 取值表

标签名称
tag_type 取值
标签名举例
自定义标签
xg_user_define
tag1,tag2 等
App版本
xg_auto_version
1.1.0,1.2.0.1等
设备省份信息
xg_auto_province
guangdong,shanghai 等
活跃信息
xg_auto_active
20200131,20200201等
XG SDK版本
xg_auto_sdkversion
1.1.5.2,1.1.5.3等
系统语言
xg_auto_systemlanguage
zh,en 等
手机品牌
xg_auto_devicebrand
Xiaomi,vivo 等
手机机型
xg_auto_deviceversion
MI 9 SE,vivo X9Plus 等
国家
xg_auto_country
CN,SG 等
说明
详细使用方法可参见 标签推送示例

channel_rules 参数说明

字段名
类型
父项目
是否必填
参数说明
channel
String
channel_rules
下发推送通道。
xg:自建通道
hw:华为通道
xm:小米通道
mz:魅族通道
vivo:vivo 通道
oppo:OPPO 通道
apns:APNs 通道
honor:荣耀通道
fcm:FCM通道
disable
Boolean
channel_rules
是否关闭 channel 中对应的通道, 默认打开通道。
true:关闭
false:打开

loop_param 参数说明

字段名
类型
父项目
是否必填
注释
startDate
String
loop_param
循环区间开始日期,可选择未来90天内的时间。格式 YYYY-MM-DD,例如2019-07-01
endDate
String
loop_param
循环区间截止日期,可选择未来90天内的时间。格式 YYYY-MM-DD,例如2019-07-07
loopType
Integer
loop_param
循环类型:
天: 1
周: 2
月: 3
loopDayIndexs
Array
loop_param
按天循环:填写[0],表示每天的任务,按周循环:填周几[0-6],如[0, 1, 2]表示每周的星期天,周一,周二进行推送,按月循环:填写日期,如[1,10,20],每个月1,10,20号
dayTimes
Array
loop_param
具体推送时间,格式 HH:MM:SS,例如["19:00:00", "20:00:00"],表示每天的19点,20点进行推送

应答参数

字段名
类型
是否必须
注释
seq
Integer
与请求包一致(如果请求包无该字段,则该字段返回为0)
push_id
String
推送 ID
注意:如果您是循环推送类型,则会返回多个 pushid 放在一个数组类型里
collapse_id
Integer
消息覆盖ID
invalid_targe_list
Array
仅对 token 列表推送和单 token 推送 且 ignore_invalid_token 值为1时返回,该字段会存储被过滤的无效 token ,有效 token 会正常下发
ret_code
Integer
错误码,详细参照错误码对照表
environment
String
用户指定推送环境,仅支持 iOS
product: 生产环境
dev: 开发环境
err_msg
String
请求出错时的错误信息
result
String
请求正确时,
若有额外数据要返回,则结果封装在该字段的 json 中
若无额外数据,则此字段为空
err_msg_zh
String
中文错误信息

示例说明

Android 账号推送请求消息

{
"audience_type": "account",
"account_list": [
"account1"
],
"multi_pkg":true,
"push_speed":50000,
"channel_rules": [
{
"channel": "mz",
"disable": true
},
{
"channel": "xm",
"disable": false
}
],
"message_type": "notify",
"message": {
"title": "测试标题",
"content": "测试内容",
"xg_media_resources": "xxx1" , //此处填富媒体元素地址,例如https://www.xx.com/img/bd_logo1.png?qua=high
"xg_media_audio_resources":"xxx", //此处填音频富媒体元素地址,例如http://sc1.111ttt.cn/2018/1/03/13/396131227447.mp3
"accept_time": [
{
"start": {//时间段起始时间,
"hour": "13",//起始时间 小时值, 取值 [0:24)
"min": "00"// 起始时间 分钟值, 取值[0:60)
},
"end": {//时间段结束时间
"hour": "14",//结束时间 小时值, 取值 [0:24)
"min": "00" //结束时间 分钟值,取值[0:60)

}
},
{
"start": {
"hour": "00",
"min": "00"
},
"end": {
"hour": "09",
"min": "00"
}
}
],
"android": {
"n_ch_id": "default_message",
"n_ch_name": "默认通知",
"builder_id": 0,
"ring": 1,
"ring_raw": "ring",
"badge_type":-1,
"vibrate": 1,
"lights": 1,
"clearable": 1,
"icon_type": 0,
"icon_res": "xg",
"style_id": 1,
"small_icon": "xg",
"action": {
"action_type": 1,// 动作类型,1,打开 activity 或 app 本身;2,打开浏览器;3,打开 Intent
"activity": "xxx",
"aty_attr": {// activity属性,只针对action_type=1的情况
"if": 0, // Intent的Flag属性
"pf": 0 // PendingIntent的Flag属性
},
"browser": {
"url": "xxxx ", // 仅支持http、https
"confirm": 1 // 是否需要用户确认
},
"intent": "xxx" //SDK版本需要大于等于1.0.9,然后在客户端的intent配置data标签,并设置scheme属性
},
"custom_content":"{\\"key\\":\\"value\\"}"
}
}
}

账号推送应答消息

{
"seq": 0,
"push_id": "3895624686",
"collapse_id": 0,
"environment": "product",
"err_msg": "NO_ERROR",
"result": "{}",
"ret_code": 0,
"invalid_targe_list": [],
"err_msg_zh": ""
,

}

iOS 单设备推送请求消息

{
"audience_type": "token",
"environment":"dev",
"token_list": [ "05da87c0ae********fa9e08d884aada5bb2"],
"message_type":"notify",
"message":{
"title": "推送标题",
"content": "推送内容",
"ios":{
"aps": {
"alert": {
"subtitle": "推送副标题"
},
"badge_type": -2,
"sound":"Tassel.wav",
"category": "INVITE_CATEGORY"

},
"custom_content":"{\\"key\\":\\"value\\"}"
}
}
}

单设备推送应答消息

{
"seq": 0,
"push_id": "427184209",
"collapse_id": 55067797,
"ret_code": 0,
"environment": "dev",
"err_msg": "",
"result": "{}",
"invalid_targe_list": [],
"err_msg_zh": ""
}

标签推送场景(tag_rules 方式)

场景一:广东和湖南,并且是20200408当天活跃过的男性用户 表达式:(xg_auto_province.guangdong 或 xg_auto_province.hunan)与 xg_auto_active.20200408 与 xg_user_define.male
{
"audience_type": "tag",
"tag_rules": [
{
"tag_items": [
{
"tags": [
"guangdong",
"hunan"
],
"is_not": false, //是否对tags内标签计算的结果进行非运算,true-进行非运算,false-不进行非运算
"tags_operator": "OR", //tags内标签对应的运算符
"items_operator": "OR", //tag_items内各元素的运算符,第一个元素的items_operator为无效数据,第二个元素的items_operator作为第一个和第二个元素之前的运算符,以此类推
"tag_type": "xg_auto_province" //tags内标签对应的标签类型
},
{
"tags": [
"20200408"
],
"is_not": false,
"tags_operator": "OR",
"items_operator": "AND",
"tag_type": "xg_auto_active"
},
{
"tags": [
"male"
],
"is_not": false,
"tags_operator": "OR",
"items_operator": "AND",
"tag_type": "xg_user_define"
}
],
"operator": "OR",
"is_not": false
}
]
}
场景二:近3天活跃,并且 App 版本不为1.0.2的华为用户 表达式:(xg_auto_active.20200406 或 xg_auto_active.20200407 或 xg_auto_active.20200408)与 (非 xg_auto_version.1.0.2) 与 xg_auto_devicebrand.huawei
{
"audience_type": "tag",
"tag_rules": [
{
"tag_items": [
{
"tags": [
"20200406",
"20200407",
"20200408"
],
"is_not": false, //是否对tags内标签计算的结果进行非运算,true-进行非运算,false-不进行非运算
"tags_operator": "OR", //tags内标签对应的运算符
"items_operator": "OR", //tag_items内各元素的运算符,第一个元素的items_operator为无效数据,第二个元素的items_operator作为第一个和第二个元素之前的运算符,以此类推
"tag_type": "xg_auto_active" //tags内标签对应的标签类型
},
{
"tags": [
"1.0.2"
],
"is_not": true,
"tags_operator": "OR",
"items_operator": "AND",
"tag_type": "xg_auto_verison"
},
{
"tags": [
"huawei"
],
"is_not": false,
"tags_operator": "OR",
"items_operator": "AND",
"tag_type": "xg_auto_devicebrand"
}
],
"operator": "OR",
"is_not": false
}
]
}