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透传下去
        },
        "quickapp": {
            "alert": "Hi, JPush!",
            "title": "Send to QuickApp",
            "page": "/page1"
        }
    },
    "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, QuickApp，Windows Phone 四个平台的推送。其关键字分别为："android", "ios", "quickapp","winphone"。

推送到所有平台：

{ "platform" : "all" }

指定特定推送平台：

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

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;
}

Quick App

快应用平台上通知结构。 该通知内容满足快应用平台的规范，支持的字段如下：

服务端发送消息串

{
    "notification" : {
        "quickapp": {
            "alert": "Hi, JPush!",
            "title": "Send to QuickApp",
            "page": "/page1",
            "extras" : {
                "news_id" : 134, 
                "my_key" : "a value"
            }
        }
}                 

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 推送通知同时下发的应用内消息。

inapp_message：应用内提醒

inapp_message 此功能生效需Android push SDK≥V3.9.0、iOS push SDK≥V3.4.0，若低于此版本按照原流程执行。

inapp_message 面向于通知栏消息类型，对于通知权限关闭的用户可设置启用此功能。此功能启用后，当用户前台运行APP时，会通过应用内消息的方式展示通知栏消息内容。

• inapp_message： 面向通知栏消息，Boolean类型；
• 值为 true 表示启用应用内提醒功能；
• 值为 false 表示禁用应用内提醒功能。

示例如下：

{
    "cid": "8103a4c628a0b98974ec1949-711261d4-5f17-4d2f-a855-5e5a8909335e",
    "platform": "all",
    "audience": {
        "tag": [
            "深圳",
            "北京"
        ]
    },
    "notification": {
        "android": {
            "alert": "Hi, JPush!",
            "title": "Send to Android"
        },
        "ios": {
            "alert": "Hi, JPush!",
            "sound": "default",
            "badge": "+1",
            "thread-id": "default"
            "extras": {
                "newsid": 321
            }
        }
    },
    "inapp_message": {
        "inapp_message": true
    }
}

sms_message：短信补充

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

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

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

options：可选参数

推送可选项。

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

third_party_channel

示例：

"third_party_channel":{
    "xiaomi":{
              "distribution":"jpush",   // 表示纯小米用户通知栏消息下发逻辑，全部取值：jpush、ospush、secondary_push
              "channel_id":"*******",   //可选，2020/06 新增，由小米提供给到开发者，开发者通过此处透传；
                                        //如果传递了此字段，也传递了 notification-android-channel_id 字段，则针对小米通道下发时，以此字段为准；
                                        //如果此字段未传递，则以 notification-android-channel_id 字段为准。
                                        //当 distribution 为 jpush 时，该参数实际无效
              "large_icon":"jgmedia-2-14b23451-0001-41ce-89d9-987b465122da",  //可选，支持极光的media_id及小米厂商的大图标id,必须配合小米大文本或者是大图片使用，否则无效
              "small_icon_uri":"jgmedia-3-14b23451-0001-41ce-89d9-987b465122da",   //可选，支持极光的media_id及小米厂商的小图标id
              "small_icon_color":"#ABCDEF",   //可选，不填充默认灰色
              "big_text":"testbigtext", //可选，最多支持128个字符，配合小米style使用
              "style":1 //可选，默认为0普通模式，bigText=1，bigPicture=3
              "distribution_fcm":"fcm" // 可选，2020/09/15 新增，表示小米+fcm共存时下发逻辑，此处表示 fcm + 小米组合用户，消息走fcm下发
                                      // 全部取值：jpush、fcm、pns、secondary_fcm_push（优先极光然后fcm）、secondary_pns_push（优先极光然后小米）  
              "distribution_customize":"first_ospush"  // 可选，表示推送自定义消息优先走厂商通道下发，无效走极光通道下发
    },
    "huawei":{
              "distribution":"secondary_push",  // 表示纯华为用户通知栏消息下发逻辑，全部取值：jpush、ospush、secondary_push
              "distribution_fcm":"jpush", // 可选，2020/09/15 新增，表示华为+fcm共存时下发逻辑，此处表示 fcm+华为组合用户，消息走极光下发
                                         // 全部取值：jpush、fcm、pns、secondary_fcm_push（优先极光然后fcm）、secondary_pns_push（优先极光然后华为）
              "importance":"HIGH",        //可选，2020/09/21 新增，对应华为的 importance 字段,值为 String 类型，对应值分别是：“LOW”（一般消息）、“NORMAL”（重要消息）、“HIGH”（非常重要消息），不填充默认为"NORMAL"
              "large_icon":"jgmedia-2-14b23451-0001-41ce-89d9-987b465122da",  //可选，支持极光的media_id及网络https路径
              "small_icon_uri":"jgmedia-3-14b23451-0001-41ce-89d9-987b465122da",   //可选，支持极光的media_id及华为厂商本地路径
              "inbox": JSONObject, //可选，配合华为style使用
              "style":2, //可选，默认为0普通模式，bigText=1，Inbox=2
              "only_use_vendor_style":true //只使用自身通道设置的样式，不使用android里面设置大图标/小图标/大文本等样式
    },
    "meizu":{
              "distribution":"jpush",   // 表示纯魅族用户通知栏消息下发逻辑，全部取值：jpush、ospush、secondary_push
              "distribution_fcm":"pns" // 可选，2020/09/15 新增，表示魅族+fcm共存时下发逻辑，此处表示 fcm+魅族组合用户，消息走魅族下发
                                 // 全部取值：jpush、fcm、pns、secondary_fcm_push（优先极光然后fcm）、secondary_pns_push（优先极光然后魅族）
    },
    "fcm":{                         // 这个参数不支持 distribution_fcm 字段
              "distribution":"jpush"  // 表示纯 fcm 用户通知栏消息下发逻辑，全部取值：jpush、ospush、secondary_push
    },
    "oppo":{
              "distribution":"ospush", // 表示纯 oppo 用户通知栏消息下发逻辑，全部取值：jpush、ospush、secondary_push
              "channel_id":"*******", //可选，2020/06 新增，由开发者通自行去OPPO官方申请，申请通过，开发者通过过此处透传；
                                      //如果传递了此字段，也传递了 notification-android-channel_id 字段，则针对 OPPO 通道下发时，以此字段为准；
                                      //如果此字段未传递，则以 notification-android-channel_id 字段为准。
                                      //当 distribution 为 jpush 时，该参数实际无效；
                                      //当 distribution 为 secondary_push 时，限制策略走极光通道和走厂商通道逻辑一致：厂商不限制，极光也不限制；开发者如果恶意使用此字段，被转发到厂商的请求如果因配额限制导致推送无法下发问题，后台由开发者自行承担。
              "distribution_fcm":"secondary_fcm_push", // 可选，2020/09/15 新增，表示oppo+fcm共存时下发逻辑，此处表示 fcm+oppo 组合用户，消息优先走极光，然后走fcm下发
                                                // 全部取值：jpush、fcm、pns、secondary_fcm_push（优先极光然后fcm）、secondary_pns_push（优先极光然后oppo）
              "large_icon":"jgmedia-2-14b23451-0001-41ce-89d9-987b465122da",  //可选，支持极光的media_id及oppo厂商的大图标id
              "big_pic_path":"jgmedia-1-14b23451-0001-41ce-89d9-987b465122da", //可选，配合oppo的style使用
              "style":1 //可选，默认为0普通模式，bigText=1，bigPicture=3
    },
    "vivo":{
            "distribution":"jpush",   // 表示纯 vivo 用户通知栏消息下发逻辑，全部取值：jpush、ospush、secondary_push
            "classification": 0,     //可选，int 类型，2020/06 新增，和vivo官方字段含义一致 0 代表运营消息，1 代表系统消息，不填vivo官方默认为0
                                     //当 distribution 为 jpush 时，该参数实际无效；
                                     //当 distribution 为 secondary_push 时，限制策略走极光通道和走厂商通道逻辑一致：厂商不限制，极光也不限制；开发者如果恶意使用此字段，被转发到厂商的请求如果因配额限制导致推送无法下发问题，后台由开发者自行承担。
            "distribution_fcm":"secondary_pns_push", // 可选，2020/09/15 新增，表示vivo+fcm共存时下发逻辑，此处表示 fcm+vivo 组合用户，消息优先走极光，然后走vivo下发
                                                 // 全部取值：jpush、fcm、pns、secondary_fcm_push（优先极光然后fcm）、secondary_pns_push（优先极光然后vivo）
            "push_mode":0             //可选，2020/09/21 新增，对应 vivo 的 pushMode 字段,值为int 类型，值分别是：“0”表示正式推送；“1”表示测试推送，不填默认为0
    }
}

options.third_party_channel字段说明：

options.third_party_channel： key 只支持 xiaomi、huawei、meizu、oppo、vivo、fcm类型用户。 key 可以为上述6个类型中的其中一个或者多个同时存在，未传递的 key 其对应的厂商下发走默认下发逻辑。

默认下发逻辑为：如果推送的是通知，一次推送请求中，目标用户同时包含厂商用户和非厂商用户，那厂商用户走对应厂商下发，非厂商用户走极光通道下发；

每个厂商类型的KEY可以同时存在以下3个策略参数：

• distribution：面向通知栏消息，定义系统通道用户下发通知栏消息的逻辑，字符串类型，取值不能为空字符串，只能是"ospush"、"jpush"、"secondary_push" 和 "first_ospush"。
  • 值为 first_ospush 时表示推送优先走厂商通道下发，无效走极光通道下发；
  • 值为 ospush 表示推送强制走厂商通道下发；

    当请求时指定了“ospush”值时需要特别注意，只要指定此值的厂商对应配额不够时，推送请求会失败，返回 1012 错误码。
    举例：假设指定一个小米用户的 RegistrationID 推送，请求时针对小米、OPPO等厂商通道都指定了“ospush”，且OPPO厂商通道都配额已经用完，则推送同样会返回 1012 错误，提示厂商配额不足。

  • 值为 jpush 表示推送强制走极光通道下发；
  • 值为 secondary_push 表示推送优先走极光，极光不在线再走厂商，厂商作为辅助；【建议此种方式】
• distribution_fcm： 面向通知栏消息，定义fcm+国内厂商组合类型用户下发通知栏消息的逻辑，字符串类型，取值不能为空字符串，只能是"jpush"、"fcm"、"pns"、"secondary_fcm_push"、"secondary_pns_push"。
  • 值为 jpush 表示推送强制走极光通道下发；
  • 值为 fcm 表示推送强制走 fcm 通道下发；
  • 值为 pns 表示推送强制走小米/华为/魅族/oppo/vivo 通道下发；
  • 值为 secondary_fcm_push 表示针对fcm+国内厂商组合类型用户，推送优先走极光，极光不在线再走fcm通道，fcm作为辅助；
  • 值为 secondary_pns_push 表示针对fcm+国内厂商组合类型用户，推送优先走极光，极光不在线再走厂商通道，厂商作为辅助；
• distribution_customize： 面向自定义消息，定义国内厂商类型用户（当前仅对xiaomi、huawei生效）下发自定义消息的逻辑，字符串类型，取值不能为空字符串，只能是"first_ospush"。此功能生效需Android push SDK≥V3.9.0。
  • 值为 jpush 表示推送强制走极光通道下发；
  • 值为 first_ospush 时表示推送优先走厂商通道下发，无效走极光通道下发；
  • 值为 secondary_push 表示推送优先走极光，极光不在线再走厂商，厂商作为辅助;

不同厂商类型的KEY可以存在以下属性参数：

• channel_id： 为了适配小米、oppo 手机厂商通知栏消息分类，由开发者自行向手机厂商申请，具体申请规则参考：小米 ，oppo 。
• classification： 为了适配 vivo 手机厂商通知栏消息分类,值为int 类型，“0”代表运营消息，“1”代表系统消息，不填默认为0，目前vivo对系统消息分类较为严格，具体规则参考：vivo ；
• push_mode： 为了适配 vivo 手机厂商通知栏消息，对应 vivo 的 pushMode 字段,值为int 类型，值分别是：“0”表示正式推送；“1”表示测试推送，不填默认为0；参考：vivo pushMode ；
• importance： 为了适配华为手机厂商的通知栏消息智能分类，对应华为的 importance 字段,值为 String 类型，对应值分别是：“LOW”（一般消息）、“NORMAL”（重要消息）、“HIGH”（非常重要消息），不填充默认为"NORMAL"，参考：华为通知消息智能分类 。
• urgency：为了适配华为手机厂商自定义消息的优先级。值为string类型，对应值分别为是：“HIGH”（非常重要消息，HIGH级别消息到达用户手机时可强制拉起应用进程）、“NORMAL”（重要消息）。设置“HIGH”需要向华为申请特殊权限，参考：特殊权限如何申请 。
• category：为了适配华为手机厂商自定义消息，标识高优先级透传消息的特殊场景，值为string类型，对应值分别为是：“PLAY_VOICE”（语音播报）、“VOIP”（VoIP电话）。使用此字段申请特殊权限，参考：特殊权限如何申请 。
• large_icon： 为了适配厂商的消息大图标样式，目前支持小米/华为/oppo三个厂商，优先使用厂商字段， 厂商字段没有填充，则使用android里面定义large_icon字段android内的large_icon，其中小米支 持极光的media_id(极光media_id详见：Image API v3)及小米厂商的大图标id,但必须配合小米大文本或者是大图片使用，否则无效，华为支持极光的media_id及网络https路径，oppo支持极光的media_id及oppo厂商的大图标id，JPush Android SDK v3.9.0版本以上才支持该字段
• small_icon_uri： 为了适配厂商的消息小图标样式，目前支持小米/华为两个厂商，优先使用厂商字段， 厂商字段没有填充，则使用android里面定义small_icon_uri字段android内的small_icon_uri，其中小米支持极光的media_id及小米厂商的小图标id，支持极光的media_id及华为厂商本地路径
• small_icon_color： 为了适配小米厂商的消息小图标样式颜色，不填充默认是灰色，JPush Android SDK v3.9.0版本以上才支持该字段
• style： 为了适配厂商的消息大文本/inbox/大图片样式，不填充默认是0，对应关系bigText=1，Inbox=2，bigPicture=3，JPush Android SDK v3.9.0版本以上才支持该字段
• big_text： 为了适配厂商的消息大文本样式,目前支持小米/华为/oppo三个厂商，优先使用厂商字段， 厂商字段没有填充，则使用android里面定义big_text字段android内的big_text，其中小米最多支持128个字符(一个英文或一个中文算一个字符)，配合小米style使用，oppo最多也是支持128个字符，配合style使用，JPush Android SDK v3.9.0版本以上才支持该字段
• inbox： 为了适配厂商的消息inbox样式,目前支持华为厂商，优先使用厂商字段， 厂商字段没有填充，则使用android里面定义inbox字段android内的inbox，配合华为style使用，JPush Android SDK v3.9.0版本以上才支持该字段
• big_pic_path： 为了适配厂商的消息大图片样式,目前支持小米/oppo两个厂商，优先使用厂商字段， 厂商字段没有填充，则使用android里面定义big_pic_path字段android内的big_pic_path，配合各自厂 商的style使用，JPush Android SDK v3.9.0版本以上才支持该字段
• only_use_vendor_style：值为布尔类型，为true，只使用自身通道设置的样式，不使用android里面设置大图标/小图标/大文本/inbox/大图片样式，反之则可使用android里面设置的样式，默认为false，JPush Android SDK v3.9.0版本以上才支持该字段

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:送达和点击回执, 8:推送成功回执, 9:成功和送达回执, 10:成功和点击回执, 11:成功和送达以及点击回执
    }
}

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 列表

推送校验 API

调用地址

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

功能说明

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

批量单推（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
    }
}

推送撤销

调用地址

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"
  }
}

文件推送

文件立即推送调用地址

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

文件定时推送调用地址

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

功能说明

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

调用说明

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

文件立即推送调用参数示例

{
    "platform":"all",
    "audience":{
        "file":{
            "file_id":"004f2b2c3d8fc649fa60ad2c-15563487-577d-4bb0-806b-56f1a19e06c1"
        }
    },
    "notification":{
        "alert":"Hello, JPush!"
    },
    "message":{
        "msg_content":"Hello, JPush!"
    },
    "options":{
        "time_to_live":600,
        "apns_production":false
    }
}

文件定时推送调用参数示例

{
    "cid": "7103a4c428a0b98974ec1849-711161d4-5f17-4d2f-b855-5e5a8909b26e",
    "name":"Schedule_Name",
    "enabled":true,
    "trigger":{
        "periodical":{
            "start":"2021-02-19 12:00:00",
            "end":"2021-03-19 18:30:00",
            "time":"18:05:00",
            "time_unit":"day",
            "frequency":1
        }
    },
    "push":{
        "platform":"all",
        "audience":{
            "file":{
                "file_id":"004f2b2c3d8fc649fa60ad2c-15563487-577d-4bb0-806b-56f1a19e06c1"
            }
        },
        "notification":{
            "alert":"Hello, JPush!"
        },
        "message":{
            "msg_content":"Hello, JPush!"
        },
        "options":{
            "time_to_live":600,
            "apns_production":false
        }
    }
}

注意

• 文件推送（文件立即推送/文件定时推送） API 接口频率规则和 File API v3 频率规则一样 20次/min，且各个文件相关接口频率会互相消耗。
• 对于文件定时推送，创建定时任务成功后，任务被执行前文件被删除，则任务执行时推送动作将会失败。

Group Push API：应用分组推送

调用地址

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

功能说明

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

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

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

注2： 2020.08.11 此接口新增返回 group_msgid 字段，用于唯一标识本次分组推送请求，后续可用于分组推送统计。

调用示例

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"}}'

返回示例

{"004f2b2c3d8fc649fa60ad2c":{"msg_id":"38280675634520813","sendno":"0"},"4bb78a2d6404fa239906db70":{"error":{"code":1011,"message":"cannot find user by this audience"},"dad9619c708ae3663647d01e":{"msg_id":"9007276705113721","sendno":"0"},"group_msgid":"bspkjbi81sipokgfvmu0"}

应用分组文件推送（VIP专属接口）

调用地址

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

功能说明

该 API 用于为开发者在 portal 端创建的应用分组进行文件推送，推送参数和格式跟文件推送一样。

需要注意对是，此接口鉴权使用的是 base64(groupkey:group_secret)

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

注：此接口只对已经开通权限对客户支持，未开通权限客户使用将会返回错误返回码 2007。

调用示例

curl --insecure -X POST -v https://api.jpush.cn/v3/grouppush/file -H "Content-Type: application/json" -u "group-e4c938578ee598be517a2243:71d1dc4dae126674ed386b7b" -d '{"platform":["android"],"audience":{"file": {"file_id":"9516d30d2c128dd2000e35b6-e4b030ed-6f89-468c-8f3a-41302f88fe44"}},"notification":{"android":{"alert":"notification content","title":"notification title"}},"message":{"msg_content":"message content"}}'

调用返回

相关参考

• 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
• 各推送通道标题与内容限制
  • 小米通道 1.推送标题长度限制50个字，推送内容长度限制128个字，不能包含特殊字符，例如#，>>。 2.检查手机通知权限设置，小米有不重要通知功能，部分消息可能会存在通知栏的不重要通知里。
  • 魅族通道 1.标题长度限制32个字，内容长度限制100个字，不能包含特殊字符#。 2.部分消息可能会存入魅族手机右上角【魅族消息盒子】中。
  • OPPO通道 1.通知栏标题长度限制32个字，子标题长度限制10个字，通知内容长度限制为200个字数以内。【中英文都算一个】 2.OPPO是默认关闭通知权限的，确认开启通知权限和通知权限下的【Default】通道权限。
  • VIVO通道 1.标题长度限制20个字（40个英文字符），内容长度限制50个字（100个英文字符），不能包含特殊字符，例如#，>>。 2.VIVO官方为避免造成用户打扰，目前禁止凌晨向用户推送不必要的消息，具体时间点为23:00-07:00。 3.VIVO官方要求的正式应用发送的content里面不能是纯数字、纯英文、纯符号、符号加数字，包含“测试”、“test”字样、大括号、中括号。 4.VIVO官方要求对于同一设备一天内运营消息的推送条数不能超过5条，系统消息无条数限制。 5.VIVO官方要求对于同一设备一天内不能重复推送内容相同的运营消息，系统消息无此限制。 6.VIVO机型默认关闭通知权限，确认开启通知权限。
  • 华为通道 1.标题长度限制40个字，内容长度限制1024个字。 2.华为通知，通知内容和标题禁止携带政府，领导人名称、台独等相关内容。 3.检查通知权限，华为手机默认【营销通知】的权限为静默通知，静默推送没有声音、震动等提示。
  • 极光通道 1.Android 平台 Notification+Message 长度限制为 4000 字节。 2.iOS Notification 中 “iOS”:{ } 及大括号内的总体长度不超过：2000 个字节（包括自定义参数和符号），iOS 的 Message 部分长度不超过 4000 字节。 3.WinPhone 平台 Notification 长度限制为 1000 字节。