推送模板 API(VIP)
最近更新:2023-10-12
推送模板 API(VIP)
概述
开发者可以将推送时所需参数通过极光 webPortal 页面提前配置好,形成一套“推送模板”,然后通过此 API 接口,指定“模板 ID”推送,大大降低开发难度,节省开发调试时间,节省服务器带宽成本。
调用域名
调用验证
- 详情参见 REST API 概述的 鉴权方式 说明。
指定模板推送
指定模板【立即推送】
指定模板ID,模板参数(如有设置),进行立即推送。
调用地址
POST https://api.jpush.cn/v3/push/template
请求示例
//完整示例
{
"id": "c65b34b96512", // 创建模板后,极光生产的模板ID
"params": [{
"keys": { // 创建模板时,开发者设置的变量参数
"title": "这是推送给第⼀个regid的标题",
"content": "这是第⼀个regid的内容"
},
"audience": { // 本次推送,实际想推送的人群
"registration_id": [
"13065ffa4ee8411496f"
]
}
},
{
"keys": { // 创建模板时,开发者设置的变量参数
"title": "这是推送给第⼆个regid的标题",
"content": "这是第⼆个regid的内容"
},
"audience": { // 本次推送,实际想推送的人群
"registration_id": [
"170976fa8a754363cd1"
]
}
}
]
}
// 注意:不支持多种不同Audience类型的组合(tag\tagnot\tagand除外)
// 1. params 数组里面,同一个推送里面的 Audience 不允许不同类型组合(tag\tagnot\tagand除外)
// 2. params 数组里面,不同推送的 Audience 也不允许不同类型(tag\tagnot\tagand除外)
// 3. 如果是文件方式推送,一次推送只支持指定一个文件;
// 4. 如果是地理围栏方式推送,一次推送仅支持指定一个地理围栏
// 也就是说:假设数组长度是3,那么就表示有3个推送,这3个推送要么都是regid方式推送,要么都是alias方式推送
// 广播推送,"audicence": "all",且 params 数组里面仅允许1个json体
{
"id": "c65b34b96512",
"params": [
{
"keys": {
"title": "这是推送给第⼀个regid的标题",
"content": "这是第⼀个regid的内容"
},
"audicence": "all",
"trace_id": "8de06fh-8djfgg"
}
]
}
// regid推送,"audicence": {"registration_id":[]},params里面全部regid个数最多1000个
{
"id": "c65b34b96512",
"params": [
{
"keys": {
"title": "这是推送给第⼀个regid的标题",
"content": "这是第⼀个regid的内容"
},
"audicence": {"registration_id":["13065ffa4ee8411496f"]},
"trace_id": "98ode06fh-8dgg"
},
{
"keys": {
"title": "这是推送给第二个regid的标题",
"content": "这是第二个regid的内容"
},
"audicence": {"registration_id":["8914afdsa31"]},
"trace_id": "8de06fh-8djfgg"
},
]
}
// alias推送,"audicence": {"alias":[]},params里面全部alias个数最多1000个
{
"id": "c65b34b96512",
"params": [
{
"keys": {
"title": "这是推送给第⼀个alias的标题",
"content": "这是第⼀个alias的内容"
},
"audicence": {"alias":["4312kjkla31"]},
"trace_id": "98ode06fh-8dgg"
},
{
"keys": {
"title": "这是推送给第二个alias的标题",
"content": "这是第二个alias的内容"
},
"audicence": {"alias":["8914sa31"]},
"trace_id": "8de06fh-8djfgg"
},
]
}
// 标签推送,"audicence": {"tag":[]},且 params 数组里面允许1个json体,允许 "audience":{"tag":["tag1","tag2"], "tag_and":["tag3","tag4"], "tag_not":["tag5", "tag6"]},规则同Push APi
{
"id": "c65b34b96512",
"params": [
{
"keys": {
"title": "这是推送给tag的标题",
"content": "这是第tag的内容"
},
"audicence": {"tag":["tag1"]},
"trace_id": "8de06fh-8djfgg"
}
]
}
// segmentid 推送,"audicence": {"segment":[]},,且 params 数组里面允许1个json体,且只允许设置一个分组id值
{
"id": "c65b34b96512",
"params": [
{
"keys": {
"title": "这是推送给tag的标题",
"content": "这是第tag的内容"
},
"audicence": {"segment":["segmentid001"]},
"trace_id": "8de06fh-8djfgg"
}
]
}
//完整示例
{
"id": "c65b34b96512", // 创建模板后,极光生产的模板ID
"params": [{
"keys": { // 创建模板时,开发者设置的变量参数
"title": "这是推送给第⼀个regid的标题",
"content": "这是第⼀个regid的内容"
},
"audience": { // 本次推送,实际想推送的人群
"registration_id": [
"13065ffa4ee8411496f"
]
}
},
{
"keys": { // 创建模板时,开发者设置的变量参数
"title": "这是推送给第⼆个regid的标题",
"content": "这是第⼆个regid的内容"
},
"audience": { // 本次推送,实际想推送的人群
"registration_id": [
"170976fa8a754363cd1"
]
}
}
]
}
// 注意:不支持多种不同Audience类型的组合(tag\tagnot\tagand除外)
// 1. params 数组里面,同一个推送里面的 Audience 不允许不同类型组合(tag\tagnot\tagand除外)
// 2. params 数组里面,不同推送的 Audience 也不允许不同类型(tag\tagnot\tagand除外)
// 3. 如果是文件方式推送,一次推送只支持指定一个文件;
// 4. 如果是地理围栏方式推送,一次推送仅支持指定一个地理围栏
// 也就是说:假设数组长度是3,那么就表示有3个推送,这3个推送要么都是regid方式推送,要么都是alias方式推送
// 广播推送,"audicence": "all",且 params 数组里面仅允许1个json体
{
"id": "c65b34b96512",
"params": [
{
"keys": {
"title": "这是推送给第⼀个regid的标题",
"content": "这是第⼀个regid的内容"
},
"audicence": "all",
"trace_id": "8de06fh-8djfgg"
}
]
}
// regid推送,"audicence": {"registration_id":[]},params里面全部regid个数最多1000个
{
"id": "c65b34b96512",
"params": [
{
"keys": {
"title": "这是推送给第⼀个regid的标题",
"content": "这是第⼀个regid的内容"
},
"audicence": {"registration_id":["13065ffa4ee8411496f"]},
"trace_id": "98ode06fh-8dgg"
},
{
"keys": {
"title": "这是推送给第二个regid的标题",
"content": "这是第二个regid的内容"
},
"audicence": {"registration_id":["8914afdsa31"]},
"trace_id": "8de06fh-8djfgg"
},
]
}
// alias推送,"audicence": {"alias":[]},params里面全部alias个数最多1000个
{
"id": "c65b34b96512",
"params": [
{
"keys": {
"title": "这是推送给第⼀个alias的标题",
"content": "这是第⼀个alias的内容"
},
"audicence": {"alias":["4312kjkla31"]},
"trace_id": "98ode06fh-8dgg"
},
{
"keys": {
"title": "这是推送给第二个alias的标题",
"content": "这是第二个alias的内容"
},
"audicence": {"alias":["8914sa31"]},
"trace_id": "8de06fh-8djfgg"
},
]
}
// 标签推送,"audicence": {"tag":[]},且 params 数组里面允许1个json体,允许 "audience":{"tag":["tag1","tag2"], "tag_and":["tag3","tag4"], "tag_not":["tag5", "tag6"]},规则同Push APi
{
"id": "c65b34b96512",
"params": [
{
"keys": {
"title": "这是推送给tag的标题",
"content": "这是第tag的内容"
},
"audicence": {"tag":["tag1"]},
"trace_id": "8de06fh-8djfgg"
}
]
}
// segmentid 推送,"audicence": {"segment":[]},,且 params 数组里面允许1个json体,且只允许设置一个分组id值
{
"id": "c65b34b96512",
"params": [
{
"keys": {
"title": "这是推送给tag的标题",
"content": "这是第tag的内容"
},
"audicence": {"segment":["segmentid001"]},
"trace_id": "8de06fh-8djfgg"
}
]
}
此代码块在浮窗中显示
请求参数
- id:String类型,必填,模板ID(由极光服务器生成)
- params:JSON Array,必填,模板参数列表,可支持如下字段
- keys:JSON object,可选,若创建模板时有设置变量,此处推送时则必须指定并设置变量名和变量值。
- audience:格式和pushapi的⼀致。但是有如下限制:
- ⼴播推送,"audience": "all",且 params 数组⾥⾯仅允许1个json体
- regid推送,"audience": {"registration_id":[]},params⾥⾯全部regid个数最多1000个
- alias推送,"audience": {"alias":[]},params⾥⾯全部alias个数最多1000个
- 标签推送,"audience": {"tag":[]},且 params 数组⾥⾯允许1个json体
- segmentid 推送,"audience": {"segment":[]},且 params 数组⾥⾯允许1个json体,且只允许设置⼀个分组id值
- trace_id:string,可选,客户自行指定的标识,api会原样返回。
- geofence:JSON object,可选,地理围栏推送时,此处指定围栏相关参数。
返回示例
HTTP/2 200
{
"code": 0,
"message": "success",
"data": {
"push_list": [{ // 返回结果是按照请求参数 params 数组下标顺序一一对应
"code": 0,
"message_id": "2252000892313098"
},
{
"code": 0,
"message_id": "1098252000313050"
},
{
"code": 1011,
"message_id": "2252000000123130",
"message": "cannot find user by this audience or has been inactive for morethan 255 days "
},
{,
"code": 1003,
"message_id": "2252000003001231",
"message": "The registration_id aaaa is invalid!"
}
]
}
}
HTTP/2 200
{
"code": 0,
"message": "success",
"data": {
"push_list": [{ // 返回结果是按照请求参数 params 数组下标顺序一一对应
"code": 0,
"message_id": "2252000892313098"
},
{
"code": 0,
"message_id": "1098252000313050"
},
{
"code": 1011,
"message_id": "2252000000123130",
"message": "cannot find user by this audience or has been inactive for morethan 255 days "
},
{,
"code": 1003,
"message_id": "2252000003001231",
"message": "The registration_id aaaa is invalid!"
}
]
}
}
此代码块在浮窗中显示
HTTP/2 400
{
"code": 10004,
"message": "Missing parameters"
}
HTTP/2 400
{
"code": 10004,
"message": "Missing parameters"
}
此代码块在浮窗中显示
返回参数
JSON Object
- code:integer类型,返回code 0表示接⼝调⽤成功 ,⾮0表示失败
- message:string类型,"success"表示接口调用成功;接口调用失败,则提示失败原因
- data:json类型,模板推送返回数据
- push_list:JSON Array类型,推送列表结果
- message_id :string类型,推送message id
- code :integer类型,实际Push发送时的错误,⽐如⽤户不存在,错误码同push API错误码,有异常才返回此字段
- message :string类型,实际Push发送时的错误原因,错误push API,有异常才返回此字段
- push_list:JSON Array类型,推送列表结果
指定模板【定时推送】
指定模板,指定时间,定时推送。
调用地址
POST https://api.jpush.cn/v3/push/template/schedule
请求示例
//完整示例
{
"id": "c65b34b96512",
"params": [{ // 注意:params里面各字段要求,同[指定模板立即提送]要求
"keys": {
"title": "这是推送给第⼀个regid的标题",
"content": "这是第⼀个regid的内容"
},
"audience": {
"registration_id": [
"13065ffa4ee8411496f"
]
}
}],
"schedule_name": "定时⽂件推送示例",
"trigger": {
"periodical": {
"start": "2023-10-19 12:00:00",
"end": "2023-11-19 18:30:00",
"time": "18:05:00",
"time_unit": "day",
"frequency": 1
}
}
}
//完整示例
{
"id": "c65b34b96512",
"params": [{ // 注意:params里面各字段要求,同[指定模板立即提送]要求
"keys": {
"title": "这是推送给第⼀个regid的标题",
"content": "这是第⼀个regid的内容"
},
"audience": {
"registration_id": [
"13065ffa4ee8411496f"
]
}
}],
"schedule_name": "定时⽂件推送示例",
"trigger": {
"periodical": {
"start": "2023-10-19 12:00:00",
"end": "2023-11-19 18:30:00",
"time": "18:05:00",
"time_unit": "day",
"frequency": 1
}
}
}
此代码块在浮窗中显示
请求参数
- id:String类型,必填,模板ID
- params:JSON Array,必填,模板参数列表,可支持如下字段
- keys:JSON object,可选,若创建模板时有设置变量,此处推送时则必须指定并设置变量名和变量值。
- audience:格式和pushapi的⼀致。但是有如下限制:
- ⼴播推送,"audience": "all",且 params 数组⾥⾯仅允许1个json体
- regid推送,"audience": {"registration_id":[]},params⾥⾯全部regid个数最多1000个
- alias推送,"audience": {"alias":[]},params⾥⾯全部alias个数最多1000个
- 标签推送,"audience": {"tag":[]},且 params 数组⾥⾯允许1个json体
- segmentid 推送,"audience": {"segment":[]},且 params 数组⾥⾯允许1个json体,且只允许设置⼀个分组id值
- trace_id:string,可选,客户自行指定的标识,api会原样返回。
- schedule_name:String类型,必填,定时任务名称
- trigger:JSON object类型,必填,传值同 Schedule API ⼀致
返回示例
HTTP/2 200
{
"code": 0,
"message": "success",
"data": {
"schedule_list": [{
"schedule_id": "0eac1b80-c2ac-4b69-948b-c65b34b96512",
"code": 1011,
"messge": "**********"
}]
}
}
HTTP/2 200
{
"code": 0,
"message": "success",
"data": {
"schedule_list": [{
"schedule_id": "0eac1b80-c2ac-4b69-948b-c65b34b96512",
"code": 1011,
"messge": "**********"
}]
}
}
此代码块在浮窗中显示
返回参数
JSON Object
- code:integer类型,返回code 0表示接⼝调⽤成功 ,⾮0表示失败
- message:string类型,"success"表示接口调用成功;接口调用失败,则提示失败原因
- data:json类型,模板推送返回数据
- schedule_list:JSON Array类型,定时任务推送列表
- schedule_id :string类型,定时任务 id
- code :integer类型,实际Push发送时的错误,⽐如⽤户不存在,错误码同push API错误码,有异常才返回此字段
- message :string类型,实际Push发送时的错误原因,错误push API,有异常才返回此字段
- schedule_list:JSON Array类型,定时任务推送列表
调用返回
Code | 描述 | 详细解释 | HTTP Status Code |
---|---|---|---|
10001 | 参数错误 | json解析失败,反序列化失败 | 406 |
10002 | 参数错误 | json序列化失败 | 406 |
10003 | 系统内部错误 | 服务不可用 | 503 |
10004 | 参数错误 | 参数缺失 | 400 |
10005 | 参数错误 | 不支持的消息类型 | 400 |
10006 | 参数错误 | 缺失模板ID | 400 |
10007 | 参数错误 | offset或limit必须为整数 | 400 |
10008 | 参数错误 | 记录不存在 | 404 |
10009 | 参数错误 | 不能混合推送 | 400 |
10010 | 参数错误 | 参数长度超限 | 400 |
10011 | 参数错误 | 模板和变量key不匹配 | 400 |
10012 | 参数错误 | 超过模板数上限100 | 400 |
10013 | 参数错误 | 定时任务名字重复 | 400 |
2006 | 请求非法 | 接口只针对 VIP 开放 | 403 |
调用限制
- 以上所有API相关接口的频率和Push API接口频率共用,会互相影响和消耗。
- 如果是定时任务推送,定时任务调用限制 同样生效
- 此文档对应的所有接口均是 VIP 应用专属接口,非 VIP 使用会返回 2006 错误码。
文档内容是否对您有帮助?