推送模板 API(VIP)
最近更新:2023-10-12

推送模板 API(VIP)

概述

开发者可以将推送时所需参数通过极光 webPortal 页面提前配置好,形成一套“推送模板”,然后通过此 API 接口,指定“模板 ID”推送,大大降低开发难度,节省开发调试时间,节省服务器带宽成本。

调用域名

https://api.jpush.cn

调用验证

指定模板推送

指定模板【立即推送】

指定模板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,有异常才返回此字段

指定模板【定时推送】

指定模板,指定时间,定时推送。

调用地址

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,有异常才返回此字段

调用返回

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 错误码。
文档内容是否对您有帮助?

Copyright 2011-2022, jiguang.cn, All Rights Reserved. 粤ICP备12056275号-13 深圳市和讯华谷信息技术有限公司

在文档中心打开