Push API v3

推送概述

功能说明

向某单个设备或者某设备列表推送一条通知、或者消息。
推送的内容只能是 JSON 表示的一个推送对象。

调用地址

https://api.jpush.cn/v3/push

请求示例

curl --insecure -X POST -v https://api.jpush.cn/v3/push -H "Content-Type: application/json" -u "7d431e42dfa6a6d693ac2d04:5e987ac6d2e04d95a9d8f0d1" -d '{"platform":"all","audience":"all","notification":{"alert":"Hi,JPush !","android":{"extras":{"android-key1":"android-value1"}},"ios":{"sound":"sound.caf","badge":"+1","extras":{"ios-key1":"ios-value1"}}}}'

> POST /v3/push HTTP/1.1
> Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==

返回示例

< HTTP/1.1 200 OK
< Content-Type: application/json
{"sendno":"18","msg_id":"1828256757"}

调用验证

HTTP Header（头）里加一个字段（Key/Value 对）：

Authorization: Basic base64_auth_string

其中 base64_auth_string 的生成算法为：base64(appKey:masterSecret)
即，对 appKey 加上冒号，加上 masterSecret 拼装起来的字符串，再做 base64 转换。

推送对象

一个推送对象，以 JSON 格式表达，表示一条推送相关的所有信息。

示例与说明

{
    "cid": "8103a4c628a0b98974ec1949-711261d4-5f17-4d2f-a855-5e5a8909b26e",
    "platform": "all",
    "audience": {
        "tag": [
            "深圳",
            "北京"
        ]
    },
    "notification": {
        "android": {
            "alert": "Hi, JPush!",
            "title": "Send to Android",
            "builder_id": 1,
            "large_icon": "http://www.jiguang.cn/largeIcon.jpg",
            "intent": {
                "url": "intent:#Intent;component=com.jiguang.push/com.example.jpushdemo.SettingActivity;end",
            },
            "extras": {
                "newsid": 321
            }
        },
        "ios": {
            "alert": "Hi, JPush!",
            "sound": "default",
            "badge": "+1",
            "thread-id": "default"
            "extras": {
                "newsid": 321
            }
        },
        "voip": {    // 此功能需要 JPush iOS SDK v3.3.2 及以上版本支持
            "key": "value" // 任意自定义key/value对，api透传下去
        }
    },
    "message": {
        "msg_content": "Hi,JPush",
        "content_type": "text",
        "title": "msg",
        "extras": {
            "key": "value"
        }
    },
    "sms_message":{
       "temp_id":1250,
       "temp_para":{
            "code":"123456"
       },
        "delay_time":3600,
        "active_filter":false
    },
    "options": {
        "time_to_live": 60,
        "apns_production": false,
        "apns_collapse_id":"jiguang_test_201706011100"
    },
    "callback": {
        "url":"http://www.bilibili.com", 
        "params":{
            "name":"joe",
            "age":26
         },
         "type":3
    }
}

platform：推送平台

JPush 当前支持 Android, iOS, Windows Phone 三个平台的推送。其关键字分别为："android", "ios", "winphone"。

推送到所有平台：

{ "platform" : "all" }

指定特定推送平台：

{ "platform" : ["android", "ios"] }

audience：推送目标

推送设备对象，表示一条推送可以被推送到哪些设备列表。确认推送设备对象，JPush 提供了多种方式，比如：别名、标签、注册 ID、分群、广播等。

all

如果要发广播（全部设备），则直接填写 “all”。

基于业务优化的需求，极光将于 3 月 10 日对「广播推送」的频率进行限制，调整为 10 次每天，超过调用限制时将返回报错码 2008，官网控制台将与 Push API 同步调整。

注意：本次调整仅限制广播，对广播外的推送不影响。如广播推送需更高频率，请联系商务，详情请阅读公告。

推送目标

广播外的设备选择方式，有如下几种：

示例

• 推送给全部（广播）：

{
   "platform": "all",
   "audience" : "all",
   "notification" : {
      "alert" : "Hi, JPush!",
      "android" : {}, 
      "ios" : {
         "extras" : { "newsid" : 321}
      }
   }
}

• 推送给多个标签（只要在任何一个标签范围内都满足）：在深圳、广州、或者北京

{
    "audience" : {
        "tag" : [ "深圳", "广州", "北京" ]
    }
}

• 推送给多个标签（需要同时在多个标签范围内）：在深圳并且是“女”

{
    "audience" : {
        "tag_and" : [ "深圳", "女" ]
    }
}

• 推送给多个别名：

{
    "audience" : {
        "alias" : [ "4314", "892", "4531" ]
    }
}

• 推送给多个注册 ID：

{
    "audience" : {
        "registration_id" : [ "4312kjklfds2", "8914afd2", "45fdsa31" ]
    }
}

• 可同时推送指定多类推送目标：在深圳或者广州，并且是 “女” “会员”

{
    "audience" : {
        "tag" : [ "深圳", "广州" ],
        "tag_and" : [ "女", "会员"]
    }
}

notification：通知

“通知”对象，是一条推送的实体内容对象之一（另一个是“消息”），是会作为“通知”推送到客户端的。
其下属属性包含 4 种，3 个平台属性，以及一个 "alert" 属性。

alert

通知的内容在各个平台上，都可能只有这一个最基本的属性 "alert"。
这个位置的 "alert" 属性（直接在 notification 对象下），是一个快捷定义，各平台的 alert 信息如果都一样，则可不定义。如果各平台有定义，则覆盖这里的定义。

{
    "notification" : {
        "alert" : "Hello, JPush!"
    }
}

上面定义的 notification 对象，将被推送到 "platform" 指定的多个平台，并且其通知 alert 信息都一样。

android

Android 平台上的通知，JPush SDK 按照一定的通知栏样式展示。

支持的字段有：

{
    "notification" : {
        "android" : {
             "alert" : "hello, JPush!", 
             "title" : "JPush test", 
             "builder_id" : 3, 
             "style":1  // 1,2,3
             "alert_type":1 // -1 ~ 7
             "big_text":"big text content",
             "inbox":JSONObject,
             "big_pic_path":"picture url",
             "priority":0, // -2~2
             "category":"category str",
             "large_icon": "http://www.jiguang.cn/largeIcon.jpg",
           "intent": {
                "url": "intent:#Intent;component=com.jiguang.push/com.example.jpushdemo.SettingActivity;end",
            },
             "extras" : {
                  "news_id" : 134, 
                  "my_key" : "a value"
             }
        }
    }
}

iOS

iOS 平台上 APNs 通知结构。
该通知内容会由 JPush 代理发往 Apple APNs 服务器，并在 iOS 设备上在系统通知的方式呈现。
该通知内容满足 APNs 的规范，支持的字段如下：

服务端发送消息串

{
    "notification" : {
         "ios" : {
                 "alert" : "hello, JPush!", 
                 "sound" : "sound.caf", 
                 "badge" : 1, 
                 "extras" : {
                      "news_id" : 134, 
                      "my_key" : "a value"
                 }
            }
       }
}                

客户端收到 apns

{
    "_j_msgid" = 813843507;
    aps =     {
        alert = "hello,JPush!";
        badge = 1;
        sound = "sound.caf";
    };
    "my_key" = "a value";
    "news_id" = 134;
}

winphone

Windows Phone 平台上的通知。
该通知由 JPush 服务器代理向微软的 MPNs 服务器发送，并在 Windows Phone 客户端的系统通知栏上展示。
该通知满足 MPNs 的相关规范。当前 JPush 仅支持 toast 类型：

    {
        "notification" : {
            "winphone" : {
                 "alert" : "hello, JPush!", 
                 "title" : "Push Test", 
                 "_open_page" : "/friends.xaml", 
                 "extras" : {
                      "news_id" : 134, 
                      "my_key" : "a value"
                 }
            }
        }
    }

VOIP

iOS VOIP功能。
该类型推送支持和 iOS 的 Notification 通知并存，请求参数结构参考：

    {
        "notification": {
            "ios" : {
                "alert" : "hello, JPush!",
                "sound" : "sound.caf"
            },
            "voip": {
                "key": "value" // 任意自定义key/value对，会透传给APP
            }
        }
    }

message：自定义消息

应用内消息。或者称作：自定义消息，透传消息。
此部分内容不会展示到通知栏上，JPush SDK 收到消息内容后透传给 App。需要 App 自行处理。
iOS 在推送应用内消息通道（非 APNS）获取此部分内容，即需 App 处于前台。Windows Phone 暂时不支持应用内消息。

消息包含如下字段：

Android 1.6.2 及以下版本 接收 notification 与 message 并存（即本次 api 调用同时推送通知和消息）的离线推送， 只能收到通知部分，message 部分没有透传给 App。

Android 1.6.3 及以上 SDK 版本已做相应调整，能正常接收同时推送通知和消息的离线记录。

iOS 1.7.3 及以上的版本才能正确解析 v3 的 message，但是无法解析 v2 推送通知同时下发的应用内消息。

sms_message：短信补充

sms_message 用于设置短信推送内容以及短信发送的延迟时间。

开发者需要先把用户的手机号码与设备的 registrationID 匹配。绑定方法：服务端-Device-更新设备; Android API-设置手机号码; iOS API-设置手机号码；

与原有 JSON 业务协议相匹配，消息有如下字段信息：

options：可选参数

推送可选项。

当前包含如下几个可选项：

third_party_channel

此功能仅对厂商 VIP 用户生效。

如需要开通此功能，请联系：商务客服

示例：

"third_party_channel":{
    "xiaomi":{"distribution":"jpush"
              "channel_id":"*******"    //可选，2020/06 新增，由小米提供给到开发者，开发者通过此处透传；
                                        //如果传递了此字段，也传递了 notification-android-channel_id 字段，则针对小米通道下发时，以此字段为准；
                                        //如果此字段未传递，则以 notification-android-channel_id 字段为准。
                                        //当 distribution 为 jpush 时，该参数实际无效
    },
    "huawei":{"distribution":"secondary_push"},
    "meizu":{"distribution":"jpush"},
    "fcm":{"distribution":"jpush"},
    "oppo":{"distribution":"ospush"
            "channel_id":"*******"    //可选，2020/06 新增，由开发者通自行去OPPO官方申请，申请通过，开发者通过过此处透传；
                                      //如果传递了此字段，也传递了 notification-android-channel_id 字段，则针对 OPPO 通道下发时，以此字段为准；
                                      //如果此字段未传递，则以 notification-android-channel_id 字段为准。
                                      //当 distribution 为 jpush 时，该参数实际无效；
                                      //当 distribution 为 secondary_push 时，限制策略走极光通道和走厂商通道逻辑一致：厂商不限制，极光也不限制；开发者如果恶意使用此字段，被转发到厂商的请求如果因配额限制导致推送无法下发问题，后台由开发者自行承担。
    },
    "vivo":{"distribution":"jpush"
            "classification": 0      //可选，int 类型，2020/06 新增，和vivo官方字段含义一致 0 代表运营消息，1 代表系统消息，不填vivo官方默认为0
                                     //当 distribution 为 jpush 时，该参数实际无效；
                                     //当 distribution 为 secondary_push 时，限制策略走极光通道和走厂商通道逻辑一致：厂商不限制，极光也不限制；开发者如果恶意使用此字段，被转发到厂商的请求如果因配额限制导致推送无法下发问题，后台由开发者自行承担。
    }
}

    }
}

• 字段说明：
  • options.third_party_channel 的 key 只支持 xiaomi、huawei、meizu、oppo、vivo、fcm；
  • options.third_party_channel 的 key 可以其中一个或者多个 key 同时存在，未传递的 key 其对应的厂商下发走默认下发逻辑，默认下发逻辑说明如下：
    • 如果推送的是通知，一次推送请求中，目标用户同时包含厂商用户和非厂商用户，那厂商用户走对应厂商下发，非厂商用户走极光通道下发；
  • distribution 为字符串类型，取值不能为空字符串，只能是"ospush"、"jpush"、"secondary_push"。
    • 值为 ospush 表示推送强制走厂商通道下发；
    • 值为 jpush 表示推送强制走极光通道下发；
    • 值为 secondary_push 表示推送优先走极光，极光不在线再走厂商，厂商作为辅助；【建议此种方式】
  • channel_id 为了适配小米、oppo手机厂商消息分类，由开发者自行向手机厂商申请，具体申请规则参考：小米 ，oppo 。
  • classification 为了适配vivo手机厂商消息分类,值为int 类型，“0”代表运营消息，“1”代表系统消息，不填默认为0，目前vivo对系统消息分类较为严格，具体规则参考：vivo 。

callback：回调参数

Push API发起请求时，可以指定 callback 参数，方便用户临时变更回调 URL 或者回调带上其自定义参数，满足其日常业务需求。

此功能仅针对极光 VIP 用户提供，主要提供消息送达、点击回执数据。

如需要开通此功能，请联系：商务客服

示例：

{
    "platform":"all",
    "audience":"all",
    "notification":{
        "alert":"Hi, JPush",
    },
    ....
    "callback": {
        "url":"https://***",  // 可选字段；
        "params":{          // 可选
            "name":"joe",
            "age":26
         },
         "type":3   // 可选，1：送达回执，2：点击回执，3：送达和点击回执
    }
}

callback 包含如下字段：

notification_3rd：自定义消息转厂商通知

Push API 发起自定义消息类型的推送请求时，针对 Android 设备，如果 APP 长连接不在线，则消息没法及时的下发；针对这种情况，极光推出了“自定义消息转厂商通知”的功能。

也就是说，针对用户一些重要的自定义消息，可以申请开通极光 VIP 厂商通道功能，开通后，通过 APP 长连接不在线时没法及时下发的消息，可以通过厂商通道下发以厂商通知形式展示，及时提醒到用户。极光内部会有去重处理，您不用担心消息重复下发问题。

如需要开通此功能，请联系：商务客服

示例：

{
    "platform":"all",
    "audience":"all",
    "message":{
        "msg_content": "Hi,JPush",
    },
    "notification_3rd": {
        "content": "Hi,JPush",
        "title": "msg",
        "channel_id": "channel001",
        "uri_activity": "cn.jpush.android.ui.OpenClickActivity",
        "uri_action": "cn.jpush.android.intent.CONNECTION"
        "badge_add_num": 1
        "badge_class": "com.test.badge.MainActivity"
        "sound": "sound"
        "extras":{
            "news_id" : 134, 
            "my_key" : "a value"
        }
    }
}

• notification_3rd 包含如下字段：

• 使用说明
  • notification_3rd 只针对开通了厂商通道的用户生效；
  • notification 和 notification_3rd 不能同时有内容，如果这两块同时有内容，则会返回错误提示；
  • notification_3rd 的内容对 iOS 和 WinPhone 平台无效，只针对 Android 平台生效；
  • notification_3rd 是用作补发厂商通知的内容，只有当 message 部分有内容，才允许传递此字段，且要两者都不为空时，才会对离线的厂商设备转发厂商通道的通知。

cid：推送唯一标识符

调用地址

GET https://api.jpush.cn/v3/push/cid[?count=n[&type=xx]]

功能说明

cid 是用于防止 api 调用端重试造成服务端的重复推送而定义的一个推送参数。

用户使用一个 cid 推送后，再次使用相同的 cid 进行推送，则会直接返回第一次成功推送的结果，不会再次进行推送。

CID 的有效期为 1 天。CID 的格式为：{appkey}-{uuid}

在使用 cid 之前，必须通过接口获取你的 cid 池。获取时 type=push 或者不传递 type 值。

调用示例

Request Header

curl --insecure -X GET -v https://api.jpush.cn/v3/push/cid?count=3 -H "Content-Type: application/json" -u "2743204aad6fe2572aa2d8de:e674a3d0fd42a53b9a58121c"

GET /v3/push/cid?count=3
Authorization: Basic (base64 auth string)
Content-Type: text/plain
Accept: application/json

Request Params

count
    可选参数。数值类型，不传则默认为 1。范围为 [1, 1000]
type
    可选参数。CID 类型。取值：push（默认），schedule

Response Header

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

 Response Data  

{
 "cidlist":[
 "8103a4c628a0b98994ec1949-128eeb45-471c-49f3-b442-a05c20c9ed56",
 "8103a4c628a0b98994ec1949-6e44d7f1-89f5-48a8-bec4-e359c15b13e5",
 "8103a4c628a0b98994ec1949-47e0a960-ce67-4e71-94ce-b4b9e8813af0"
 ]
}

Response Params

cidlist
    cid 列表

Group Push API：应用分组推送

调用地址

POST https://api.jpush.cn/v3/grouppush

功能说明

该 API 用于为开发者在 portal 端创建的应用分组创建推送。

groupkey 可以在创建的分组信息中获取，使用起来同 appkey 类似，但在使用的时候前面要加上 “group-” 前缀。

注：暂不支持 option 中 override_msg_id 的属性；分组推送仅在官网支持设置定时，调 Schedule API 时不支持。

调用示例

curl --insecure -X POST -v https://api.jpush.cn/v3/grouppush -H "Content-Type: application/json" -u "group-e4c938578ee598be517a2243:71d1dc4dae126674ed386b7b" -d '{"platform":["android"],"audience":"all","notification":{"android":{"alert":"notification content","title":"notification title"}},"message":{"msg_content":"message content"}}'

批量单推（VIP专属接口）

调用地址

POST https://api.jpush.cn/v3/push/batch/regid/single
POST https://api.jpush.cn/v3/push/batch/alias/single

注：/v3/push/batch/regid/single 针对的是RegID方式批量单推，/v3/push/batch/alias/single 针对的是Alias方式批量单推

功能说明

如果您在给每个用户的推送内容都不同的情况下，可以使用此接口。

如需要开通此接口，请联系：商务客服

调用说明

使用此接口前，您需要配合使用 cid:推送唯一标识符 接口提前获取到 cid 池，获取时 type=push 或者不传递 type 值；获取到cid值后，传递参数格式如下：

{"pushlist":{
    "cid值1":{     
        ...
    },
    "cid值2":{     
        ...
    },
    ...
}}

调用示例

Request Header

POST /v3/push/batch/regid/single HTTP/1.1 Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==

或者

POST /v3/push/batch/alias/single HTTP/1.1 Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==

Request Params

pushlist
    必填参数。JSON类型
cid值
    必填参数。JSON类型，取值：push（默认），JSON Value部分具体字段参考下面表格说明

完整参数示例：

{"pushlist":{
    "cid1":{     
        "platform": "all",
        "target": "aliasvalue1",       // 此处填写的是regid值或者alias值
        "notification": {
            ...    // 省略参数同push api部分
        },
        "message": {
            ...   // 省略参数同push api部分
        },
        "sms_message":{
            ...  // 省略参数同push api部分
        },
        "options": {
            ...  // 省略参数同push api部分
        }
    },
    "cid2":{     
        "platform": "all",
        "target": "aliasvalue2",       // 此处填写的是regid值或者alias值
        "notification": {
            ...
        },
        "message": {
            ...
        },
        "sms_message":{
            ...
        },
        "options": {
            ...
        }
    },
    ...
}}

Response

成功返回：

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

Success Response Data
{
    "cid1"：{
        "msg_id":134123478
    },
    "cid1"：{
        "msg_id":134123478,
        "error":{
            "code":1011,
            "message":"****"
        }
    },
    "cid3"：{
        "error":{
            "code":1009,
            "message":"****"
        }
    },
    ...
}

失败返回：

HTTP/1.1 400 OK
Content-Type: application/json; charset=utf-8

 Failed Response Data 
{
    "error":{
        "message":"Authen failed",
        "code":1004
    }
}

推送校验 API

调用地址

POST https://api.jpush.cn/v3/push/validate

功能说明

该 API 只用于验证推送调用是否能够成功，与推送 API 的区别在于：不向用户发送任何消息。 其他字段说明：同推送 API。

文件推送

调用地址

POST https://api.jpush.cn/v3/push/file

功能说明

支持指定文件唯一标识（file_id）进行推送，文件唯一标识（file_id）可以参考 File API v3 的 文件上传接口获得。

调用说明

推送支持的参数和普通 Push API v3参数一致，仅仅只是 audience 参数和Push API v3接口有区别，此接口支持的 audience 参数仅仅支持传递 file，示例如下：

{
    "audience": {
        "file": {"file_id":"xxxx-xxxx"}
    }
}

• 说明：文件推送 API 接口频率规则和 File API v3 频率规则一样 20次/min，且各个文件相关接口频率会互相消耗。

推送撤销

调用地址

DELETE https://api.jpush.cn/v3/push/{msgid}

功能说明

撤销操作首先会从服务端尝试撤销（Android消息，排队中/发送中状态可以服务端撤销；iOS消息，排队中状态可以服务端撤销）；其次，针对 Push SDK（JPush Android SDK v3.5.0 及以上和 JPush iOS SDK v3.2.8 及以上），会尝试从设备端撤销已展示但未被点击的消息。

Example Request

DELETE /v3/push/{msgid}
    Authorization: Basic (base64 auth string)
    Content-Type: text/plain
    Accept: application/json

Example Response

Success Response

HTTP/1.0 200 
  Content-Type: application/json
  Content-Length: 0

Failed Response

HTTP/1.0 400 
  Content-Type: application/json
  Content-Length: 0

{
  "error":{
    "code":1003,
    "message":"msgid doesn't exist"
  }
}

调用返回

参考

• HTTP 返回码：HTTP-Status-Code
• 获取推送送达 API：Report-API
• 老版本 Push API：Push API v2
• HTTP 规范参考：HTTP 基本认证
• Apple APNs 规范：Apple Push Notification Service
• Microsoft MPNs 规范：Push notifications for Windows Phone 8