Push API v3

Push Overview

Function Description

Push a notification or message to a single device or a list of devices. Pushed content can only be a push object represented by JSON

Call Address

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

Request Example

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==

Return Example

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

Call Verification

Add a field (Key/Value pair) in the HTTP Header

Authorization: Basic base64_auth_string

The generation algorithm of base64_auth_string is: base64(appKey:masterSecret) That is, add a colon to the appKey, plus the string assembled by masterSecret, and do a base64 conversion.

Pushing Objects

A push object expressed in JSON format, represents a push-related piece of information

Examples and Descriptions

{
    "cid": "8103a4c628a0b98974ec1949-711261d4-5f17-4d2f-a855-5e5a8909b26e",
    "platform": "all",
    "audience": {
        "tag": [
            "深圳",
            "北京"
        ]
    },
    "notification": {
        "android": {
            "alert": "Hi, JPush!",
            "title": "Send to Android",
            "builder_id": 1,
            "extras": {
                "newsid": 321
            }
        },
        "ios": {
            "alert": "Hi, JPush!",
            "sound": "default",
            "badge": "+1",
            "extras": {
                "newsid": 321
            }
        }
    },
    "message": {
        "msg_content": "Hi,JPush",
        "content_type": "text",
        "title": "msg",
        "extras": {
            "key": "value"
        }
    },
    "sms_message":{
        "content":"sms msg content",
        "delay_time":3600
    },
    "options": {
        "time_to_live": 60,
        "apns_production": false,
        "apns_collapse_id":"jiguang_test_201706011100"
    }
}

platform：Push Platform

JPush currently supports the push of Android, iOS, and Windows Phone. The keywords are: "android", "ios".

Push to all platforms:：

{ "platform" : "all" }

Specify a specific push platform:：

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

audience：Push Target

Object of push device represents a list of devices to which a push can be pushed. To confirm the object of push device, JPush provides a variety of methods, such as aliases, tags, registration IDs, groupings, and broadcasts.

all

If you want to send a broadcast (all devices), fill in "all" directly.

Push Target

There are several ways to select devices outside the broadcast:：

Example

• Push to all (broadcast)：

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

• Push to multiple tags (as long as they are within any tag range): in Shenzhen, Guangzhou, or Beijing

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

• Push to multiple tags (requiring in multiple tags at the same time): In Shenzhen and "Female"

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

• Push to multiple aliases：

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

• Push to multiple registration IDs：

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

• Multiple push targets can be pushed at the same time: in Shenzhen or Guangzhou, and “female” “member”

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

notification：Notification

The "notification" object, which is one of the physical content objects (the other is the "message") of push, is pushed as a "notification" to the client. Its subordinate attribute contains 4 kinds, 3 platform attributes, and an "alert" attribute

alert

The content of the notification may have only the most basic attribute "alert" on each platform. The "alert" attribute of this position (directly under the notification object) is a shortcut definition. If the alert information of each platform is the same, it may not be defined. If there is a definition for each platform, the definition here will be overwritten.

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

The notification object defined above will be pushed to multiple platforms specified by "platform" and its information for notification alert will be the same.

android

Notifications on the Android platform will be displayed in a certain notification bar style by the JPush SDK. Supported fields are：

{
    "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",
             "extras" : {
                  "news_id" : 134,
                  "my_key" : "a value"
             }
        }
    }
}

iOS

APNs notification structure on the iOS platform. The content of this notification will be sent by the JPush agent to the Apple APNs server and presented on the iOS device in the form of a system notification. The content of this notice meets the specifications of the APNs. The supported fields are as follows：

Server Sends Message String

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

Client Receives apns

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

message：Custom Message

In-app messages. Or called: custom message, transparent message. This part of the content will not be displayed on the notification bar. The JPush SDK will transparently pass message content to the App after receiving it and then App needs to handle it. On the iOS platform, this part of the content is captured in the channel (non-APNS) of in-app message push. Windows Phone temporarily does not support in-app messages.

The message contains the following fields：

Android 1.6.2 and lower versions receive offline push with the coexistence of notifications and messages (that is, the api calls push notifications and messages at the same time). Only the notification section can be received, message section is not transparently passed to the App.
Android version 1.6.3 and above SDKs have been adjusted accordingly to receive offline notifications for simultaneous push of notifications and messages.
iOS 1.7.3 and above can parse v3 messages correctly, but cannot parse in-app messages that are delivered simultaneously with v2 push notifications.

Sms_message: SMS Supplement

Used to set SMS push content and the delay of sending SMS. If receive the number by mobile phone, the developer needs to match the user's mobile phone number with the device's registration id. Binding method: Server - Device - Update Device

Matched the original JSON service agreement, the message has the following field information:

options：Optional Parameters

Push options.

Currently contains the following options：

Cid: Push the Unique Identifier

Call Address

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

Function Description

Cid is a push parameter defined to prevent the api caller from retrying to cause repeated pushes on the server side. After the user pushes via a cid, and then pushed via the same cid again, the result of the first successful push will be returned directly, and will not be pushed again. The CID is valid for 1 day. The format of the CID is: {appkey}-{uuid} Before using the cid, you must obtain your cid pool through the interface. Get type=push or do not pass type value.

Call Example

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] Optional parameters. Numeric type, defaults to 1 if not passed. The range is [1, 1000]
type
    可选参数。CID类型。取值：push(默认), schedule   Optional parameters. CID type. Value: push (default), 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: Application Group Push

Call Address

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

Function Description

This API is used to create pushes for application groups created by developers on the portal. The groupkey can be obtained from the created grouping information, and is similar to the appkey, but it needs to be prefixed with the “group-” prefix.

Note: The override_msg_id attribute of option is not supported at this time.

Call Example

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

Push Check API

Call Address

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

Function Description

The API is only used to verify that if the push call succeeds. The difference with the push API is that no message is sent to the user. Descriptions of other fields: Same as push API.

Call Return

Reference

• HTTP return code: HTTP-Status-Code
• Get push delivery API: Report-API
• Old Push API: Push API v2
• Reference for HTTP specification: Basic Authentication of HTTP
• Apple APNs specification: Apple Push Notification Service
• Microsoft MPNs specification: Push notifications for Windows Phone 8