Advanced functionality API

Advanced features API

Get push unique identifier (cid)

Function description

cid is used to prevent api A push parameter defined when the caller retries causing repeated push by the server. User uses a cid After pushing, use the same again cid When pushing, the result of the first successful push will be returned directly and will not be pushed again.
cid is valid for 1 day.cid The format is: {appkey}-{uuid}
in use cid Previously, you had to get your cid pool. When getting type=push or not passed type value.

Calling address

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

Call verification

For details, see REST API Outlined Authentication method illustrate.

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

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

This code block is shown in the floating window

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

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

This code block is shown in the floating window

Request Parameters

count 可选参数。CID 数量，数值类型，不传则默认为 1。特别说明： a. 如果您是 VIP 应用，则此值范围为 [1, 1000]； b. 如果您是非 VIP 应用，则此值范围为 [1, 10]，传递值>10默认按照10处理。 type 可选参数。CID 类型。取值：push（默认），schedule

          count
    可选参数。CID 数量，数值类型，不传则默认为 1。
    特别说明：
    a. 如果您是 VIP 应用，则此值范围为 [1, 1000]；
    b. 如果您是非 VIP 应用，则此值范围为 [1, 10]，传递值>10默认按照10处理。
type
    可选参数。CID 类型。取值：push（默认），schedule

This code block is shown in the floating window

Return example

Return successfully

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

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

This code block is shown in the floating window

Return Parameters

cidlist cid 列表

          cidlist
    cid 列表

This code block is shown in the floating window

Things to note

Get push unique identifier (cid) API interface frequency and Push API The v3 interface frequencies are shared and will affect and consume each other.

Push verification API

Function description

Should API Only used to verify whether the push call can succeed, and push API The difference is: no message is sent to the user.
Other field descriptions: Same as Push API。

Calling address

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

Call verification

For details, see REST API Outlined Authentication method illustrate.

Request example

curl --insecure -X POST -v https://api.jpush.cn/v3/push/validate -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==

          curl --insecure -X POST -v https://api.jpush.cn/v3/push/validate -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==

This code block is shown in the floating window

Return example

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

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

This code block is shown in the floating window

Things to note

Push verification API interface frequency and Push API The v3 interface frequencies are shared and will affect and consume each other.

push undo API

Function description

The undo operation will first attempt to undo from the server (Android Messages, queued/sending status can be revoked by the server;iOS message, the queued status can be revoked by the server); secondly, for Push SDK（JPush Android SDK v3.5.0 and above and JPush iOS SDK v3.2.8 and above), will try to undo messages that have been displayed but not clicked on the device. (at presentAndroidThe manufacturer itself supports andJiguangThe ones that have been adapted are mainly Xiaomi,vivo）

Calling address

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

Call verification

For details, see REST API Outlined Authentication method illustrate.

Request example

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

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

This code block is shown in the floating window

Return example

Return successfully

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

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

This code block is shown in the floating window

return on failure

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

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

This code block is shown in the floating window

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

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

This code block is shown in the floating window

Things to note

push undo API interface frequency and Push API The v3 interface frequencies are shared and will affect and consume each other.

Manufacturer quota query API

Function description

In order to control the frequency of application push messages, manufacturers will calculate the upper limit of the number of push messages per day based on the number of daily connections the application has with the manufacturer. It is currently known that Xiaomi,oppo、vivoThere are daily quota controls. The quota can be queried in the manufacturer's backend or throughJiguangWebPortalConsole query; in order to further facilitate development,JiguangThe query interfaces of the three platforms are summarized for developers to call and query.

Calling address

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

Call verification

For details, see REST API Outlined Authentication method illustrate.

Request example

GET /v3/push/quota Authorization: Basic (base64 auth string) Content-Type: text/plain Accept: application/json

          GET /v3/push/quota
    Authorization: Basic (base64 auth string)
    Content-Type: text/plain
    Accept: application/json

This code block is shown in the floating window

Return example

Return successfully

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

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

This code block is shown in the floating window

{ "code": 0, // 返回code 0表示接口调用成功 "message": "success" // success 表示接口调用成功 "data": { "xiaomi_quota": { // 小米配额 "operation": { // 运营消息 "total": 100, // 可用总额度 "used": 20 // 已使用额度 } }, "oppo_quota": { // OPPO配额 "operation": { // 运营消息 "total": 100, "used": 20 } }, "vivo_quota": { // vivo配额 "system": { // 系统消息 "total": 100, // 开通了不限量时，返回-1 "used": 20 // 开通了不限量时，返回-1 }, "operation": { // 运营消息 "total": 100, "used": 20 } } } // 返回数据，需要返回数据的接口会将数据放在此字段返回 }

          {
    "code": 0, // 返回code 0表示接口调用成功
    "message": "success" // success 表示接口调用成功
    "data": {
        "xiaomi_quota": { // 小米配额
            "operation": { // 运营消息
                "total": 100, // 可用总额度
                "used": 20 // 已使用额度
            }
        },
        "oppo_quota": { // OPPO配额
            "operation": { // 运营消息
                "total": 100,
                "used": 20
            }
        },
        "vivo_quota": { // vivo配额
            "system": { // 系统消息
                "total": 100, // 开通了不限量时，返回-1
                "used": 20 // 开通了不限量时，返回-1
            },
            "operation": { // 运营消息
                "total": 100,
                "used": 20
            }
        }
    } // 返回数据，需要返回数据的接口会将数据放在此字段返回
}

This code block is shown in the floating window

return on failure

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

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

This code block is shown in the floating window

{ "code": 1004, // 返回code非0表示失败 "message": "app_key does not exist" // 接口调用失败，则提示失败原因 }

          {
    "code": 1004, // 返回code非0表示失败
    "message": "app_key does not exist" // 接口调用失败，则提示失败原因
}

This code block is shown in the floating window

Things to note

Manufacturer quota query API interface frequency and Push API Interface frequency sharing, consumption Push API Interface frequency.

File push API

Function description

Supports specifying unique file identifiers (file_id) to push, the file is uniquely identified (file_id) can be referred to File API v3 File upload interface get.

Call verification

For details, see REST API Outlined Authentication method illustrate.

Calling address

Files are pushed immediately

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

File push regularly

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

Call instructions

Push supported parameters and common Push API v3 The parameters are the same, just audience parameters and Push API The v3 interface is different, this interface supports audience Parameters only support passing file。

Request example

File pushed immediately

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

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

This code block is shown in the floating window

Regular push of files

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

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

This code block is shown in the floating window

Return example

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

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

This code block is shown in the floating window

Things to note

File push (immediate file push / scheduled file push) API Interface frequency rules and File API v3 The frequency rule is the same 20 times /min, and the frequencies of each file-related interface will consume each other.
For instant push, it is recommended to create the push task 5 minutes before performing the file deletion operation, otherwise the push task may fail.
For scheduled file push, after the scheduled task is successfully created, if the file is deleted before the task is executed, the push action will fail when the task is executed.

Application group file push API（VIP）

Function description

Should API Used for developers in portal Use the application group created on the end to push files. The push parameters and format are the same as those for file push.

This interface only supports customers who have activated permissions. If used by customers who have not activated permissions, an error return code will be returned. 2007。

Call the file upload interface to obtain file_id when you need to use dev_key and dev_secret Verify, refer to the details File upload interface。

Calling address

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

Call verification

It should be noted that yes, this interface authentication uses base64(groupkey:group_secret)

groupkey It can be obtained from the created group information and can be used in the same way. AppKey Similar, but when using it, add "group-" prefix,group_secret Corresponding to the group information Group Master Secret, please refer to Group push API。

Request example

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

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

This code block is shown in the floating window

Return example

{ "0c3de43c6a6b68c9f4261b06": { "msg_id": "18100287417805254", "sendno": "0" }, "35c424abde12f475566ca8af": { "msg_id": "18100287207481882", "sendno": "0" }, "8f02a4fa717a6235734d92de": { "msg_id": "18100287420699802", "sendno": "0" }, "group_msgid": "cbp0jnu09s687o2j1oa0" }

          {
    "0c3de43c6a6b68c9f4261b06": {
        "msg_id": "18100287417805254",
        "sendno": "0"
    },
    "35c424abde12f475566ca8af": {
        "msg_id": "18100287207481882",
        "sendno": "0"
    },
    "8f02a4fa717a6235734d92de": {
        "msg_id": "18100287420699802",
        "sendno": "0"
    },
    "group_msgid": "cbp0jnu09s687o2j1oa0"
}

This code block is shown in the floating window

call return

For details, please refer to Push API。

Things to note

Application group file push API The interface will eventually call Push API v3 interface, so it will eventually consume Push API v3 interface frequency.