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

https://api.jpush.cn

Call verification

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

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

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?

Copyright 2011-2026, jiguang.cn, All Rights Reserved. 粤ICP备12056275号-13 Shenzhen Hexun Huagu Information Technology Co., Ltd.

Open in Docs Center