Push template API(VIP)
Last updated:2025-03-06
Push template API(VIP)
Overview
Developers can pass the parameters required when pushingJiguang webPortal The page is configured in advance to form a set of "push templates", and then through this API interface, specify"Template ID"Pushing greatly reduces development difficulty, saves development and debugging time, and saves server bandwidth costs.
Call domain name
Call verification
- For details, see REST API Outlined Authentication method illustrate.
Specify template push
Specify template [push immediately]
Specify the template ID and template parameters (if any are set) for immediate push.
Calling address
POST https://api.jpush.cn/v3/push/template
Request example
//完整示例
{
"id": "c65b34b96512", // 创建模板后,极光生产的模板ID
"params": [{
"keys": { // 创建模板时,开发者设置的变量参数
"title": "这是推送给第⼀个regid的标题",
"content": "这是第⼀个regid的内容"
},
"audience": { // 本次推送,实际想推送的人群
"registration_id": [
"13065ffa4ee8411496f"
]
},
"options": {
"test_model": true, // 表示是否测试模式消息,false:正式消息(默认值),true:测试消息
}
},
{
"keys": { // 创建模板时,开发者设置的变量参数
"title": "这是推送给第⼆个regid的标题",
"content": "这是第⼆个regid的内容"
},
"audience": { // 本次推送,实际想推送的人群
"registration_id": [
"170976fa8a754363cd1"
]
},
"options": {
"test_model": true, // 表示是否测试模式消息,false:正式消息(默认值),true:测试消息
}
}
]
}
// 注意:不支持多种不同Audience类型的组合(tag\tagnot\tagand除外)
// 1. params 数组里面,同一个推送里面的 Audience 不允许不同类型组合(tag\tagnot\tagand除外)
// 2. params 数组里面,不同推送的 Audience 也不允许不同类型(tag\tagnot\tagand除外)
// 3. 如果是文件方式推送,一次推送只支持指定一个文件;
// 4. 如果是地理围栏方式推送,一次推送仅支持指定一个地理围栏
// 也就是说:假设数组长度是3,那么就表示有3个推送,这3个推送要么都是regid方式推送,要么都是alias方式推送
// 广播推送,"audience": "all",且 params 数组里面仅允许1个json体
{
"id": "c65b34b96512",
"params": [
{
"keys": {
"title": "这是推送给第⼀个regid的标题",
"content": "这是第⼀个regid的内容"
},
"audience": "all",
"options": {
"test_model": true, // 表示是否测试模式消息,false:正式消息(默认值),true:测试消息
},
"trace_id": "8de06fh-8djfgg"
}
]
}
// regid推送,"audience": {"registration_id":[]},params里面全部regid个数最多1000个
{
"id": "c65b34b96512",
"params": [
{
"keys": {
"title": "这是推送给第⼀个regid的标题",
"content": "这是第⼀个regid的内容"
},
"audience": {"registration_id":["13065ffa4ee8411496f"]},
"options": {
"test_model": true, // 表示是否测试模式消息,false:正式消息(默认值),true:测试消息
},
"trace_id": "98ode06fh-8dgg"
},
{
"keys": {
"title": "这是推送给第二个regid的标题",
"content": "这是第二个regid的内容"
},
"audience": {"registration_id":["8914afdsa31"]},
"options": {
"test_model": true, // 表示是否测试模式消息,false:正式消息(默认值),true:测试消息
},
"trace_id": "8de06fh-8djfgg"
},
]
}
// alias推送,"audience": {"alias":[]},params里面全部alias个数最多1000个
{
"id": "c65b34b96512",
"params": [
{
"keys": {
"title": "这是推送给第⼀个alias的标题",
"content": "这是第⼀个alias的内容"
},
"audience": {"alias":["4312kjkla31"]},
"options": {
"test_model": true, // 表示是否测试模式消息,false:正式消息(默认值),true:测试消息
},
"trace_id": "98ode06fh-8dgg"
},
{
"keys": {
"title": "这是推送给第二个alias的标题",
"content": "这是第二个alias的内容"
},
"audience": {"alias":["8914sa31"]},
"options": {
"test_model": true, // 表示是否测试模式消息,false:正式消息(默认值),true:测试消息
},
"trace_id": "8de06fh-8djfgg"
},
]
}
// 标签推送,"audience": {"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的内容"
},
"audience": {"tag":["tag1"]},
"options": {
"test_model": true, // 表示是否测试模式消息,false:正式消息(默认值),true:测试消息
},
"trace_id": "8de06fh-8djfgg"
}
]
}
// segmentid 推送,"audience": {"segment":[]},,且 params 数组里面允许1个json体,且只允许设置一个分组id值
{
"id": "c65b34b96512",
"params": [
{
"keys": {
"title": "这是推送给tag的标题",
"content": "这是第tag的内容"
},
"audience": {"segment":["segmentid001"]},
"options": {
"test_model": true, // 表示是否测试模式消息,false:正式消息(默认值),true:测试消息
},
"trace_id": "8de06fh-8djfgg"
}
]
}
//完整示例
{
"id": "c65b34b96512", // 创建模板后,极光生产的模板ID
"params": [{
"keys": { // 创建模板时,开发者设置的变量参数
"title": "这是推送给第⼀个regid的标题",
"content": "这是第⼀个regid的内容"
},
"audience": { // 本次推送,实际想推送的人群
"registration_id": [
"13065ffa4ee8411496f"
]
},
"options": {
"test_model": true, // 表示是否测试模式消息,false:正式消息(默认值),true:测试消息
}
},
{
"keys": { // 创建模板时,开发者设置的变量参数
"title": "这是推送给第⼆个regid的标题",
"content": "这是第⼆个regid的内容"
},
"audience": { // 本次推送,实际想推送的人群
"registration_id": [
"170976fa8a754363cd1"
]
},
"options": {
"test_model": true, // 表示是否测试模式消息,false:正式消息(默认值),true:测试消息
}
}
]
}
// 注意:不支持多种不同Audience类型的组合(tag\tagnot\tagand除外)
// 1. params 数组里面,同一个推送里面的 Audience 不允许不同类型组合(tag\tagnot\tagand除外)
// 2. params 数组里面,不同推送的 Audience 也不允许不同类型(tag\tagnot\tagand除外)
// 3. 如果是文件方式推送,一次推送只支持指定一个文件;
// 4. 如果是地理围栏方式推送,一次推送仅支持指定一个地理围栏
// 也就是说:假设数组长度是3,那么就表示有3个推送,这3个推送要么都是regid方式推送,要么都是alias方式推送
// 广播推送,"audience": "all",且 params 数组里面仅允许1个json体
{
"id": "c65b34b96512",
"params": [
{
"keys": {
"title": "这是推送给第⼀个regid的标题",
"content": "这是第⼀个regid的内容"
},
"audience": "all",
"options": {
"test_model": true, // 表示是否测试模式消息,false:正式消息(默认值),true:测试消息
},
"trace_id": "8de06fh-8djfgg"
}
]
}
// regid推送,"audience": {"registration_id":[]},params里面全部regid个数最多1000个
{
"id": "c65b34b96512",
"params": [
{
"keys": {
"title": "这是推送给第⼀个regid的标题",
"content": "这是第⼀个regid的内容"
},
"audience": {"registration_id":["13065ffa4ee8411496f"]},
"options": {
"test_model": true, // 表示是否测试模式消息,false:正式消息(默认值),true:测试消息
},
"trace_id": "98ode06fh-8dgg"
},
{
"keys": {
"title": "这是推送给第二个regid的标题",
"content": "这是第二个regid的内容"
},
"audience": {"registration_id":["8914afdsa31"]},
"options": {
"test_model": true, // 表示是否测试模式消息,false:正式消息(默认值),true:测试消息
},
"trace_id": "8de06fh-8djfgg"
},
]
}
// alias推送,"audience": {"alias":[]},params里面全部alias个数最多1000个
{
"id": "c65b34b96512",
"params": [
{
"keys": {
"title": "这是推送给第⼀个alias的标题",
"content": "这是第⼀个alias的内容"
},
"audience": {"alias":["4312kjkla31"]},
"options": {
"test_model": true, // 表示是否测试模式消息,false:正式消息(默认值),true:测试消息
},
"trace_id": "98ode06fh-8dgg"
},
{
"keys": {
"title": "这是推送给第二个alias的标题",
"content": "这是第二个alias的内容"
},
"audience": {"alias":["8914sa31"]},
"options": {
"test_model": true, // 表示是否测试模式消息,false:正式消息(默认值),true:测试消息
},
"trace_id": "8de06fh-8djfgg"
},
]
}
// 标签推送,"audience": {"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的内容"
},
"audience": {"tag":["tag1"]},
"options": {
"test_model": true, // 表示是否测试模式消息,false:正式消息(默认值),true:测试消息
},
"trace_id": "8de06fh-8djfgg"
}
]
}
// segmentid 推送,"audience": {"segment":[]},,且 params 数组里面允许1个json体,且只允许设置一个分组id值
{
"id": "c65b34b96512",
"params": [
{
"keys": {
"title": "这是推送给tag的标题",
"content": "这是第tag的内容"
},
"audience": {"segment":["segmentid001"]},
"options": {
"test_model": true, // 表示是否测试模式消息,false:正式消息(默认值),true:测试消息
},
"trace_id": "8de06fh-8djfgg"
}
]
}
This code block is shown in the floating window
Request Parameters
- id:StringType, required, template ID (given byJiguangServer generated)
- params:JSON Array, required, template parameter list, can support the following fields
- keys:JSON object, optional. If variables are set when creating the template, the variable name and variable value must be specified and set when pushing here.
- audience:Format andpushapiconsistent. But there are the following restrictions:
- Broadcast push,"audience": "all",and params Only 1 is allowed in the arrayjsonbody
- regidpush,"audience": {"registration_id":[]},paramsAll insideregidThe largest number1000indivual
- aliaspush,"audience": {"alias":[]},paramsAll insidealiasThe largest number1000indivual
- tag push,"audience": {"tag":[]},and params 1 is allowed in the arrayjsonbody
- segmentid push,"audience": {"segment":[]},and params 1 is allowed in the arrayjsonbody, and only one group id value is allowed to be set
- options:JSON object, optional, supports the same fields and formatspushapiconsistent
- test_model:boolean, optional, indicating whether to test mode messages,false: formal message (default),true:Test message
- trace_id:string, optional, customer-specified logo,apiwill be returned unchanged.
- geofence:JSON object, optional, when pushing geofence, specify fence-related parameters here.
Return example
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!"
}
]
}
}
This code block is shown in the floating window
HTTP/2 400
{
"code": 10004,
"message": "Missing parameters"
}
HTTP/2 400
{
"code": 10004,
"message": "Missing parameters"
}
This code block is shown in the floating window
Return Parameters
JSON Object
- code:integertype, returncode 0 means the interface call is successful, non-0 means failure
- message:stringtype,"success"Indicates that the interface call is successful; if the interface call fails, the reason for the failure will be prompted.
- data:jsonType, template push return data
- push_list:JSON ArrayType, push list results
- message_id :stringtype, pushmessage id
- code :integertype, actualPushError when sending, such as the user does not exist, the error code is the same aspush APIError code. This field will be returned only if there is an exception.
- message :stringtype, actualPushThe reason for the error when sending, errorpush API, this field will be returned only if there is an exception
- push_list:JSON ArrayType, push list results
Specify template [scheduled push]
Specify the template, specify the time, and push it regularly.
Calling address
POST https://api.jpush.cn/v3/push/template/schedule
Request example
//完整示例
{
"id": "c65b34b96512",
"params": [{ // 注意:params 数组⾥⾯仅允许1个json体,params里面各字段要求同[指定模板立即推送]
"keys": {
"title": "这是推送给第⼀个regid的标题",
"content": "这是第⼀个regid的内容"
},
"audience": {
"registration_id": [
"13065ffa4ee8411496f"
]
},
"options": {
"test_model": true, // 表示是否测试模式消息,false:正式消息(默认值),true:测试消息
}
}],
"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 数组⾥⾯仅允许1个json体,params里面各字段要求同[指定模板立即推送]
"keys": {
"title": "这是推送给第⼀个regid的标题",
"content": "这是第⼀个regid的内容"
},
"audience": {
"registration_id": [
"13065ffa4ee8411496f"
]
},
"options": {
"test_model": true, // 表示是否测试模式消息,false:正式消息(默认值),true:测试消息
}
}],
"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
}
}
}
This code block is shown in the floating window
Request Parameters
- id:StringType, required, template ID
- params:JSON Array, required, template parameter list, can support the following fields (scheduled push params Array length is limited to 1)
- keys:JSON object, optional. If variables are set when creating the template, the variable name and variable value must be specified and set when pushing here.
- audience:Format andpushapiconsistent. But there are the following restrictions:
- Broadcast push,"audience": "all",and params Only 1 is allowed in the arrayjsonbody
- regidpush,"audience": {"registration_id":[]},paramsAll insideregidThe largest number1000one, and params Only 1 is allowed in the arrayjsonbody
- aliaspush,"audience": {"alias":[]},paramsAll insidealiasThe largest number1000one, and params Only 1 is allowed in the arrayjsonbody
- tag push,"audience": {"tag":[]},and params 1 is allowed in the arrayjsonbody
- segmentid push,"audience": {"segment":[]},and params 1 is allowed in the arrayjsonbody, and only one group id value is allowed to be set
- options:JSON object, optional, supports the same fields and formatspushapiconsistent
- test_model:boolean, optional, indicating whether to test mode messages,false: formal message (default),true:Test message
- trace_id:string, optional, customer-specified logo,apiwill be returned unchanged.
- schedule_name:StringType, required, scheduled task name
- trigger:JSON objectType, required, same as passed value Schedule API Consistent
Return example
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": "**********"
}]
}
}
This code block is shown in the floating window
Return Parameters
JSON Object
- code:integertype, returncode 0 means the interface call is successful, non-0 means failure
- message:stringtype,"success"Indicates that the interface call is successful; if the interface call fails, the reason for the failure will be prompted.
- data:jsonType, template push return data
- schedule_list:JSON ArrayType, scheduled task push list
- schedule_id :stringType, scheduled task id
- code :integertype, actualPushError when sending, such as the user does not exist, the error code is the same aspush APIError code. This field will be returned only if there is an exception.
- message :stringtype, actualPushThe reason for the error when sending, errorpush API, this field will be returned only if there is an exception
- schedule_list:JSON ArrayType, scheduled task push list
call returns
| Code | describe | Detailed explanation | HTTP Status Code |
|---|---|---|---|
| 10001 | Parameter error | jsonParsing failed, deserialization failed | 406 |
| 10002 | Parameter error | jsonSerialization failed | 406 |
| 10003 | System internal error | Service unavailable | 503 |
| 10004 | Parameter error | Parameter missing | 400 |
| 10005 | Parameter error | Unsupported message type | 400 |
| 10006 | Parameter error | Missing template ID | 400 |
| 10007 | Parameter error | offsetorlimitMust be an integer | 400 |
| 10008 | Parameter error | Record does not exist | 404 |
| 10009 | Parameter error | Cannot push mixedly | 400 |
| 10010 | Parameter error | Parameter length exceeds limit; If the template is pushed regularly, please pay attention to the fields params Array length is limited to 1 |
400 |
| 10011 | Parameter error | Templates and variableskeyno match | 400 |
| 10012 | Parameter error | Exceeded the maximum number of templates100 | 400 |
| 10013 | Parameter error | The scheduled task name is repeated | 400 |
| 2006 | Illegal request | The interface is only for VIP open | 403 |
call limit
- all of the aboveAPIThe frequency of the relevant interface andPush APIThe interface frequencies are shared and will affect and consume each other.
- If it is a scheduled task push,Scheduled task calling restrictions Also valid
- All interfaces corresponding to this document are VIP Application-specific interface, non- VIP Use will return 2006 error code.
Was this document helpful?