Scheduled push tasks API

Overview

API The layer supports timing functions. This is a relatively independent task execution module that maintains a Schedule object. **Note: **Tune API The created scheduled tasks can only be scheduled API Get/modify/delete.

Calling address

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

Call verification

For details, see REST API Outlined Authentication method illustrate.

Schedule object definition

Scheduled tasks:

          {
 "cid": "7103a4c428a0b98974ec1849-711161d4-5f17-4d2f-b855-5e5a8909b26e",
 "name": "Schedule_Name",
 "enabled": true,
 "trigger": {
 "single":{ 
 "time": "2014-09-17 12:00:00" //yyyy-MM-dd HH:mm:ss
 }
 },
 "push": {
 "platform": "all",
 "audience": "all",
 "notification": {
 "alert": "Hello, JPush!"
 },
 "message": {
 "msg_content":"Message!"
 },
 "options": {
 "time_to_live":60
 }
 } 
}

        

Regular tasks:

          { "cid": "7103a4c428a0b98974ec1849-711161d4-5f17-4d2f-b855-5e5a8909b26e",
 "name": "Schedule_Name",
 "enabled": true,
 "trigger": {
 "periodical": {
 "start":"2014-09-17 12:00:00",
 "end": "2014-09-18 12:00:00", 
 "time": "12:00:00", 
 "time_unit": "WEEK", //month, week, day, 大小写不敏感
 "frequency": 1,
 "point": ["WED","FRI"] //time_unit为 day 的时候，point 不能存在。WED，FRI 大小写不敏感。month:"01","02"
 }
 }, 
 "push": { 
 "platform": "all", 
 "audience": "all",
 "notification": {"alert": "Hello, JPush!" }, 
 "message": {"msg_content":"Message!" }, 
 "options": {"time_to_live":60}
 }
}

        

Field description

every schedule tasks, all by name、enabled、trigger、push It consists of four sections.

• cid

  • and push api middle cid The usage is consistent, see cid illustrate. Note:schedule api payload in push The field contains cid fields will be ignored.

• push

  • Regular push, please refer to push api in each field.
  • Scheduled file push, please refer to File push Field description.

• name

  • express schedule The name of the task, given by schedule-api After the user is successfully created schedule Return after the mission, no more than 255 Bytes are composed of Chinese characters, letters, numbers, and underscores.

• enabled

  • Indicates the current status of the task, a Boolean value, which must be true or false, it must be when creating a task true。

• trigger

  • express schedule The triggering condition of the task. Currently only scheduled tasks are supported (single) and periodic tasks (periodical）。
    • single
      • Represents a scheduled task
        • time is a required option and the format is "yyyy-MM-dd HH:mm:ss",like "2014-02-15 13:16:59", cannot be "2014-2-15 13:16:59" or "2014-12-15 13:16", that is, the date and time format must be complete. The latest time of the scheduled task cannot exceed one year.
    • periodical
      • Indicates periodic tasks
        • start Indicates the effective start time of the periodic task, and the format must be strictly: "yyyy-MM-dd HH:mm:ss" and the time must be in 24-hour format.
        • end Indicates the expiration time of the periodic task, the format is the same as above. The maximum span of periodic tasks cannot exceed one year.
        • time Indicates the periodic execution time that triggers the periodic task, and the format is strictly: "HH:mm:ss", and is a 24-hour clock.
        • time_unit The minimum time unit representing the execution of periodic tasks is: "day"、"week" and "month" Three types. Case insensitive, such as "day", "Day", "DAy" are all legal time_unit。
        • frequency This item is related to time_unit The products jointly represent the execution cycle of the periodic task,frequency The maximum value currently supported is 100. like time_unit for day，frequency If it is 2, it means that the push is triggered every two days, and the first execution is the first execution time point 1 day after the start date. like time_unit for week，frequency If it is 2, it means that the push is triggered every two weeks, and the first execution is the first execution time point 7 days after the start date.
        • point a list, this item is the same as time_unit Corresponds to:

Create a scheduled task

Calling address

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

        

Request example

Request Header

          POST /v3/schedules
 Authorization: Basic (base64 auth string)
 Content-Type: application/json
 Accept: application/json

        

Request data

          {
 "name": "定时普通推送示例", 
 "enabled": true, 
 "trigger": { 
 "periodical": { 
 "start":"2014-09-17 12:00:00", 
 "end": "2014-10-18 12:00:00", 
 "time": "12:00:00", 
 "time_unit": "WEEK", //month, week, day；大小写不敏感 
 "frequency": 2, 
 "point": ["WED","FRI"] //time_unit 为 day 的时候，point 不能存在。WED,FRI 大小写不敏感。month:"01","02" 
 }
 },
 "push": {
 "platform": "all",
 "audience": "all", 
 "notification": {
 "ios": {
 "alert":"this a test",
 "sound":"default",
 "badge":"+1"
 }
 },
 "message": {}, 
 "options": {"apns_production":false}
 } 
}

        

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

        

Request parameter description

• Since scheduled tasks are relatively simple, we only explain scheduled tasks in this example.
• The above example of scheduled normal push means creating a regular task with a start time of '2014-09-17 12:00:00', the expiration time is '2014-10-18 12:00:00', execution time point time for "12:00:00"，time_unit for week，frequency is 2,point for["WED","FRI"] means that push will be executed once every two weeks on Wednesdays and Fridays at 12 noon during the validity period.
• The first execution is the first execution time point 7 days after the start date, start date'2014-09-17'The day is Wednesday, then the first execution time point is'2014-09-24 12:00:00' (Wednesday at 12 noon).
• When a periodic task is first created, its trigger time must not be later than its end the time specified in. Otherwise the creation fails
• When a periodic task (including a scheduled task) is first created, it enabled Item must be true. cannot create enabled:false task, otherwise the creation fails
• push Must be valid and legal push action, otherwise the creation fails.

Return example

Return successfully

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

        

          {
 "schedule_id":"0eac1b80-c2ac-4b69-948b-c65b34b96512",
 "name":"定时推送示例" //长度最大 255 字节，数字、字母、下划线、汉字。
}

        

return on failure

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

        

          {
 "error":
 {
 "code":8400,
 "message":"error message"
 }
}

        

Get a valid scheduled task list

• Get the currently valid (endtime not expired) schedule list.

Calling address

          GET https://api.jpush.cn/v3/schedules?page=

        

Request example

Request Header

          GET /v3/schedules?page=
 Authorization: Basic (base64 auth string) 
 Content-Type: application/json
 Accept: application/json

        

• Returns the details of the current requested page schedule-task list, if not specified page but page is 1.
• Sort by: Creation time, by schedule-service Finish.
• If the number of requested pages is greater than the total number of pages, then page is the request value,schedules is empty.
• Maximum of 50 returned per page task, such as the actual request page task If the number is less than 50, the actual number of task。

Return example

Return successfully

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

        

          {
 "total_count":1000, //表示总数
 "total_pages":5, //总页数。
 "page":4, //当前为第四页。
 "schedules":[
 {"schedule_id":"0eac1b80-c2ac-4b69-948b-c65b34b96512","name":"","enabled":...},{}, //详细信息列表。
 ]
}

        

• The above represents the total 1000 indivual schedule-task, 5 pages in total, currently on page 4, containing 50 schedule-task information.
• returned schedules for schedule-task list of detailed information.

Get scheduled task details

• Get the current user's schedule The task id is {schedule_id} details of the scheduled task.

Calling address

           GET https://api.jpush.cn/v3/schedules/{schedule_id}

        

Request example

Request Header

          GET /v3/schedules/{schedule_id}
 Authorization: Basic (base64 auth string)
 Content-Type: application/json
 Accept: application/json

        

Return example

Return successfully

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

        

return data

          { 
 "schedule_id":"0eac1b80-c2ac-4b69-948b-c65b34b96512"
 "name": "定时推送示例", 
 "enabled": true, 
 "trigger": {...
 },
 "push": {... }
}

        

• like schedule_id If it does not exist, return 404, otherwise return the actual schedule-task details.

Get all message IDs of a scheduled task

• Get the current user's schedule The task id is {schedule_id} A list of all corresponding message ids.

Calling address

           GET https://api.jpush.cn/v3/schedules/{schedule_id}/msg_ids

        

Request example

Request Header

          GET /v3/schedules/{schedule_id}/msg_ids
 Authorization: Basic (base64 auth string)
 Content-Type: application/json
 Accept: application/json

        

Return example

Return successfully

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

        

New return data

          {
    "count":3,
    "msgids":[
 "{"msg_id":"1076080897","error":{"code":0,"message":""},"needRetry":false,"ts":1647331621836}",
 "{"msg_id":"1076080898","error":{"code":0,"message":""},"needRetry":false,"ts":1647331641022}",
 "{"msg_id":"1076080899","error":{"code":0,"message":""},"needRetry":false,"ts":1647331669510}",
    ]
}

        

Old return data

          {
 "count":3,
 "msgids":["12345567","2234567","3234567"]
}

        

• The new return data format is in 2018-09-12 to 2018-09-13 number is online, if schedule_id is 12 days ago, the old return data format will be returned; if schedule_id If it is after 13 days, the new return data format will be returned; developers need to make compatibility.
• The ts field in the new returned data format represents the timestamp of successful execution of the scheduled task, accurate to milliseconds. 2022-03-17 For scheduled tasks created later, this field will be added to the returned content.

Update scheduled tasks

• Update the specified id schedule Task.

Calling address

          PUT https://api.jpush.cn/v3/schedules/{schedule_id}

        

Request example

          PUT /v3/schedules/{schedule_id}
 Authorization: Basic (base64 auth string) 
 Content-Type: application/x-www-form-urlencoded
 Accept: application/json

        

          {
 "name": "task", 
 "enabled": true, 
 "trigger": {... 
 },
 "push": {... } 
}

        

• The update operation can be "name"，"enabled"、"trigger" or "push" One or more of the four items.
• Partial updates are not supported. For example, the tasks before the update are:

          { 
 "name": "定时推送示例", 
 "enabled": true, 
 "trigger": {
 "periodical": { 
 "start":"2014-09-17 12:00:00", 
 "end": "2014-10-18 12:00:00", 
 "time": "12:00:00", 
 "time_unit": "WEEK",
 "frequency": 2, 
 "point": ["WED","FRI"]
 }
 },
 "push": {
 "platform":"ios",
 "options":{"apns_production":false},
 "audience":"all",
 "notification": {"alert":"定时任务更新"}
 }
}

        

• The following are examples of incorrect updates and corresponding correct updates:

          ## WRONG: 更新 push 中的平台为安卓：
 { 
 "push":{"platform":"android"}
 }
## RIGHT: 更新 push 中的平台为安卓：
 {
 "push":{ 
 "platform":"android",
 "options":{"apns_production":false},
 "audience":"all",
 "notification": {"alert":"定时任务更新"}
 }
 }
 ## 此处的 push 更新后必须仍是有效的，否则也会更新失败。
 
## WRONG： 更新 periodical 中的过期时间延后一个月:
 {
 "trigger":{
 "end":"2014-11-18 12:00:00"
 }
## RIGHT: 更新 periodical 中的过期时间延后一个月：
 {
 "trigger":{
 "periodical": { 
 "start":"2014-09-17 12:00:00", 
 "end": "2014-11-18 12:00:00", 
 "time": "12:00:00", 
 "time_unit": "WEEK",
 "frequency": 2, 
 "point": ["WED","FRI"]
 }
 }
 }
 ## time、time_unit、frequency、point 的更新同上。
 ## 更新后的 trigger 必须仍是有效合法的，否则即使 trigger 整体更新也会失败。可以更新 enable:false 的任务。
 ## 定时任务（single）与定期任务（periodical）之间不能进行相互更新，即，原先为 single 类任务，则不能更新为 periodical 任务，反之亦然。
 ## 不能更新已过期的 schedule 任务

        

Return example

Return successfully

          HTTP/1.0 200 CREATED
 Content-Type: application/json

        

          { 
 "name": "定时推送示例", 
 "enabled": true, 
 "trigger": { 
 "periodical": { 
 "start":"2014-09-17 12:00:00",
 "end": "2014-11-18 12:00:00",
 "time": "12:00:00",
 "time_unit": "WEEK", 
 "frequency": 2, 
 "point": ["WED","FRI"] }
 }, 
 "push": {
 "platform":"android", 
 "options":{"apns_production":false}, 
 "audience":"all", 
 "notification": {"alert":"定时任务更新"}
 }
}

        

return on failure

• schedule_id Invalid, not valid uuid。

          HTTP/1.0 404 Not Found
 Content-Type: application/json

        

• The update operation is illegal

          HTTP/1.0 400 BAD REQUEST
 Content-Type: application/json

        

Delete scheduled tasks

• delete specified schedule_id task,schedule_id for the created schedule The id of the task, if schedule_id Illegal means not valid uuid,but 404。

Calling address

          DELETE https://api.jpush.cn/v3/schedules/{schedule_id}

        

Request example

          DELETE /v3/schedules/{schedule_id}
 Authorization: Basic (base64 auth string)
 Content-Type: application/json
 Accept: application/json

        

Return example

Return successfully

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

        

return on failure

          HTTP/1.0 404 Not Found 
 Content-Type: application/json
 Content-Length: 0

        

          {
 "error":{
 "code":8404,
 "message":"..."
 }
}

        

Error code description

Error return format

          {"error":{"code":errcode, "message":"error message"}}

        

call limit

• The maximum number of valid times (currently unexpired) and the maximum number of periodic (currently unexpired) are 50 in total (from2025.01.23At the beginning, the free application limit is 50 adjustments), and it will fail after exceeding it.
• VIP Customers can apply to increase the total limit, up to 2000 indivual,contact businessOpen.
• Scheduled tasks (single) and the latest time of the periodic task (periodical) cannot exceed 1 year.