Tencent Cloud

Recent Pages

推送接口

最后更新时间：2024-01-25 11:53:41

接口说明
请求方式：POST。
服务地址/v3/push/app
接口服务地址与服务接入点一一对应，请选择与您的应用服务接入点对应的 服务地址。
接口功能：Push API 是所有推送接口的统称。Push API 有多种推送目标，推送目标见下文。
所有请求参数通过 JSON 封装上传给后台，后台通过请求参数区分不同的推送目标。如有疑问请参见 服务端错误码。
注意：
腾讯云移动推送结合业务优化的需求，对全量推送、标签推送和号码包推送的频率进行限制，均调整为 1条/秒，官网控制台将与 API 同步调整。
如果超过此频率可能会引起推送异常，如相关推送需更高频率，您可以联系 在线客服。
必要参数
推送必要参数指一条推送消息必需携带的参数。
﻿
参数名
类型
是否必需
描述
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
无
否
通知渠道名称（仅移动推送自建通道生效） ，请参见 创建通知渠道﻿
xm_ch_id
String
android
无
否
小米渠道 ID（仅小米推送通道生效）
fcm_ch_id
String
android
无
否
FCM 渠道 ID（仅 FCM 推送通道生效）
hw_biz_type
Integer
android
0
否
是否开启华为快通知：
1：开启
0：关闭
注意：仅华为通道有效，其需要联系华为商务开通。
hw_ch_id
String
android
无
否
华为渠道 ID（仅 华为推送通道生效）
hw_category
String
android
无
否
华为消息类型标识，确定消息提醒方式，对特定类型消息加快发送，参数详情请参见 华为的请求参数说明 的 category 参数。
IM：即时聊天
VOIP：音视频通话
SUBSCRIPTION：订阅
﻿hw_importance
﻿
Integer
android
无
否
消息的提醒级别，取值如下：
1：表示通知栏消息预期的提醒方式为静默提醒，消息到达手机后，无铃声震动
2：表示通知栏消息预期的提醒方式为强提醒，消息到达手机后，以铃声、震动提醒用户。终端设备实际消息提醒方式将根据 hw_category 字段取值或者 智能分类 结果进行调整。
oppo_ch_id
String
android
无
否
OPPO渠道 ID（仅 OPPO 推送通道生效）
vivo_ch_id
String
android
0
否
vivo 渠道 ID：“0”代表运营消息，“1”代表系统消息（仅 vivo 推送通道生效）
n_id
Integer
android
0
否
（该字段已废弃，后续会下线，如需使用覆盖功能请使用覆盖参数：collapse_id）
通知消息对象的唯一标识（移动推送自建通道）
（1）大于0：会覆盖先前相同 id 的消息
（2）等于0：展示本条通知且不影响其他消息
（3）等于-1：将清除先前所有消息，仅展示本条消息
builder_id
Integer
android
0
否
本地通知样式标识
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
否
通知栏是否可清除
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
否
设置是否覆盖指定编号的通知样式
small_icon
String
android
无
否
消息在状态栏显示的图标，若不设置，则显示应用图标
icon_color
Integer
android
0
否
通知栏小图标染色
仅移动推送自建通道有效
需要使用 RGB 颜色的十进制值，例如 RGB 颜色 #01e240，请填入123456
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且应用在前台，终端用户对该条推送无感知，但有抵达数据上报
说明：
华为官方通知：「2021年9月30日起停用V2协议」。移动推送已将华为推送协议升级到V5，V5协议不支持通过【附加参数】字段携带自定义参数。如果您集成了华为厂商通道，建议您改用 Intent 方式携带自定义参数，否则将导致自定义参数不能成功通过华为推送通道下发。
﻿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）1：需要确认
（2）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": "默认通知",
                "n_id": 0,
                "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 参数说明
﻿
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 接口，如果不携带此字段则没有抵达数据上报
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\\"}"
    }
}
可选参数
Push API 可选参数是除了audience_type、message_type、message以外，可选的高级参数。
参数名
类型
父项目
必需
默认值
描述
expire_time
Integer
无
否
86400（24小时）
消息离线存储时间（单位为秒），最长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 参数说明﻿
group_id
String
无
否
tpns_yyyymmdd，yyyymmdd 代表推送日期
该字段已废弃，后续会下线，若需要使用聚合统计请使用推送计划字段：plan_id
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
int
无
否
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 取值表
标签名称
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 放在一个数组类型里
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 中
若无额外数据，则可能无此字段
示例说明
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": "默认通知",
                "n_id": 0,
                "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,
    "environment": "product",
    "ret_code": 0,
    "push_id": "3895624686"
}
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",
    "ret_code": 0,
    "environment": "dev",
    "err_msg": "",
    "result": "[0]"
}
标签推送场景（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  
        }
    ]
}
﻿

tencent cloud

Recent Pages

推送接口

接口说明

必要参数

audience_type：推送目标

message_type：消息类型

message：消息体

Android 普通消息

Android 结构体说明

iOS 通知消息

iOS 字段说明

Android 透传消息

iOS 静默消息

可选参数

tag_rules 参数说明

tag_items 说明

tag_type 取值表

channel_rules 参数说明

loop_param 参数说明

应答参数

示例说明

Android 账号推送请求消息

账号推送应答消息

iOS 单设备推送请求消息

单设备推送应答消息

标签推送场景（tag_rules 方式）

本页内容是否解决了您的问题？

本页内容是否解决了您的问题？

参数名	类型	是否必需	描述
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

推送目标	描述	必需参数及使用说明
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 文件包推送必填

消息类型	描述	支持平台	特性说明
notify	通知栏消息	Android & iOS	通知栏展示消息注意：该字段与 content-available: 1 互斥，请勿同时使用。
message	透传消息/静默消息	Android（透传消息） iOS（静默消息）	通知栏不展示消息。注意：因厂商限制，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 结构体说明

字段	类型	父项目	必填	描述
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_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 等

字段名	类型	注释
seq	Integer	与请求包一致（如果请求包无该字段，则该字段返回为0）
push_id	String	推送 ID 注意：如果您是循环推送类型，则会返回多个 pushid 放在一个数组类型里
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 中若无额外数据，则可能无此字段

tencent cloud

注册

登录

Recent Pages

推送接口

接口说明

必要参数

audience_type：推送目标

message_type：消息类型

message：消息体

Android 普通消息

Android 结构体说明

iOS 通知消息

iOS 字段说明

Android 透传消息

iOS 静默消息

可选参数

tag_rules 参数说明

tag_items 说明

tag_type 取值表

channel_rules 参数说明

loop_param 参数说明

应答参数

示例说明

Android 账号推送请求消息

账号推送应答消息

iOS 单设备推送请求消息

单设备推送应答消息

标签推送场景（tag_rules 方式）

本页内容是否解决了您的问题？

本页内容是否解决了您的问题？