Scheduled Tasks API
Last updated:2023-02-27

Scheduled Tasks API

Overviews

The API supports the timing function.

This is a relatively independent task execution module, which maintains a Schedule object.

tips: Scheduled tasks created by calling API can only be called API Query/Modify/Delete.

Request Authentication

See REST API overview for details: Authentication method .

Schedule Parameter Description

Each schedule task consists of four fields: name, enabled, trigger, and push

parameter type option description
name String required Schedule name, which cannot exceed 255 bytes, consists of Chinese characters, letters, numbers and underscores
enabled Boolean required Schedule task status,Must be true when creating a task
trigger JSON Object required Timing task trigger time and trigger conditions. Currently, only scheduled tasks (single) are supported,See the single description for details
push JSON Object required Push content,see the Create Push API for details

single description

Indicates the trigger condition of schedule task, including trigger time and scheduled task type.

parameters type option description
time String required Indicates the trigger time of the scheduled task, which is expressed in the standard time format of yyyy mm dd hh: mm: ss. For example, "2014-02-15 13:16:59" cannot be "2014-2-15 13:16:59" or "2014-12-15 13:16", that is, the date time format must be complete. The latest time of scheduled tasks cannot exceed one year.
zone_type Int required Indicates the type of timed task, 1 indicates push according to the time zone set by the master station, and 2 indicates push according to the time zone where the user terminal is located.

Create schedule task

Request Api Url

POST https://push.api.engagelab.cc/v4/schedules

Request api limit

  • The total number of valid scheduled tasks (currently unexpired) is 1000 by default. If the total number is exceeded, a new scheduled task will prompt failure.
  • The maximum span time of fixed time tasks is not limited, but it is recommended not to exceed 1 year.

Request example

request header

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

        
This code block in the floating window

request body

{ "name":"the schedule task example", "enabled":true, "trigger":{ "single":{ "time":"2022-11-23 19:20:00", "zone_type":1 } }, "push":{ "from":"push", "to":{ "registration_id":[ "1a0018970ab49abda3e", "100d85590955c1d2793" ] }, "body":{ "platform":"android", "notification":{ "alert":"api schedule task example", "android":{ "title":"api schedule task example", "extras":{ "key1":"value1" } } }, "message":{ }, "options":{ "time_to_live":60 } }, "request_id":"12345", "custom_args":"business info" } }
          {
    "name":"the schedule task example",
    "enabled":true,
    "trigger":{
        "single":{
            "time":"2022-11-23 19:20:00",
            "zone_type":1
        }
    },
    "push":{
        "from":"push",
        "to":{
            "registration_id":[
                "1a0018970ab49abda3e",
                "100d85590955c1d2793"
            ]
        },
        "body":{
            "platform":"android",
            "notification":{
                "alert":"api schedule task example",
                "android":{
                    "title":"api schedule task example",
                    "extras":{
                        "key1":"value1"
                    }
                }
            },
            "message":{

            },
            "options":{
                "time_to_live":60
            }
        },
        "request_id":"12345",
        "custom_args":"business info"
    }
}

        
This code block in the floating window

Request Data Description

  • zone_type must be filled in as the specified field value (1 or 2), otherwise it will be pushed according to the time zone of the server
  • The enabled item of a scheduled task must be true when it is first created. Cannot create the enabled: false task, otherwise the creation fails.
  • The push must be a valid and legal push action, otherwise the creation fails.

Response example

Success response

< HTTP/1.1 200 OK < Server: fasthttp < Date: Thu, 01 Dec 2022 07:17:45 GMT < Content-Type: application/json < Content-Length: 85
          < HTTP/1.1 200 OK
< Server: fasthttp
< Date: Thu, 01 Dec 2022 07:17:45 GMT
< Content-Type: application/json
< Content-Length: 85

        
This code block in the floating window
{ "schedule_id": "a9b85590-6cec-4f91-b277-2d82b0e20ef6", "name": "the schedule task name" }
          {
    "schedule_id": "a9b85590-6cec-4f91-b277-2d82b0e20ef6",
    "name": "the schedule task name"
}

        
This code block in the floating window

failed response

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

        
This code block in the floating window
{ "error": { "code": 28400, "message": "error message" } }
          {
    "error": {
        "code": 28400,
        "message": "error message"
    }
}

        
This code block in the floating window

Get a valid scheduled task list

  • Get a valid scheduled task list

request api url

GET https://push.api.engagelab.cc/v4/schedules?page=

Request example

request headers

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

        
This code block in the floating window
  • Returns the detailed schedule task list of the current request page. If no page is specified, the page is 1
  • Collation: creation time, completed by schedule service.
  • If the number of request pages is greater than the total number of pages, page is the request value and schedules is empty.
  • Each page can return up to 50 tasks. If the actual number of tasks on the request page is less than 50, the actual number of tasks will be returned.

Response example

Success response

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

        
This code block in the floating window
{ "total_count": 1000, // the total count of schedule task is 1000 "total_pages": 5, // total page is 5 "page": 4, // the current page is 4 "schedules": [ { "schedule_id": "0eac1b80-c2ac-4b69-948b-c65b34b96512", "name": "", "enabled":ture }, {}, // Detailed list of information.] }
          {
    "total_count": 1000, // the total count of schedule task is 1000
    "total_pages": 5, // total page is 5
    "page": 4, // the current page is 4
    "schedules": [
        {
            "schedule_id": "0eac1b80-c2ac-4b69-948b-c65b34b96512",
            "name": "",
            "enabled":ture
        },
        {}, // Detailed list of information.]
    }

        
This code block in the floating window
  • The above indicates that there are 1000 schedule tasks in total, 5 pages in total. Currently, it is the fourth page, containing 50 schedule tasks.
  • Schedules field is the detailed information list of schedule task

Get scheduled task details

  • Get the details of the scheduled task whose schedule task id is {schedule_id} for the current user

Request api url

GET https://push.api.engagelab.cc/v4/schedules/{schedule_id}

Request example

request headers

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

        
This code block in the floating window

response example

Success response

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

        
This code block in the floating window

response data

{ "schedule_id": "0eac1b80-c2ac-4b69-948b-c65b34b96512", "name": "schedule push task example", "enabled": true, "trigger": {...}, "push": {...} }
          {
    "schedule_id": "0eac1b80-c2ac-4b69-948b-c65b34b96512",
    "name": "schedule push task example",
    "enabled": true,
    "trigger": {...},
    "push": {...}
}

        
This code block in the floating window
  • if schedule_id does not exist,return code 404, or return the detail of the schedule-task.

Get all message ids of a scheduled task

  • Get the list of all message ids corresponding to the schedule task id {schedule_id} of the current user.

request api url

GET https://push.api.engagelab.cc/v4/schedules/{schedule_id}/msg-ids

request example

request header

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

        
This code block in the floating window

response example

Success response

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

        
This code block in the floating window

response data

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

        
This code block in the floating window

Update scheduled tasks

  • Update the schedule task with the specified id.

Request api url

PUT https://push.api.engagelab.cc/v4/schedules/{schedule_id}

Request example

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

        
This code block in the floating window
{ "name": "task", "enabled": true, "trigger": {...}, "push": {...} }
          {
  "name": "task", 
  "enabled": true, 
  "trigger": {...},
  "push": {...} 
}

        
This code block in the floating window
  • You cannot update an expired schedule task.
  • Timed tasks pushed by terminal time zone cannot be updated with those pushed by master station time zone.
  • The update operation can be one or more of "name", "enabled", "trigger" or "push". The message body need include all the fields, does not suport the part of the task.
{ "name":"Timed Push Example", "enabled":true, "trigger":{ "single":{ "time":"2022-11-23 19:20:00", "zone_type":1 } }, "push":{ "from":"push", "to":{ "registration_id":[ "1a0018970ab49abda3e", "100d85590955c1d2793" ] }, "body":{ "platform":"android", "notification":{ "alert":"api device scheduled tasks", "android":{ "title":"api device scheduled tasks", "extras":{ "key1":"value1" } } }, "message":{ }, "options":{ "time_to_live":60 } }, "request_id":"12345", "custom_args":"business info" } }
          {
    "name":"Timed Push Example",
    "enabled":true,
    "trigger":{
        "single":{
            "time":"2022-11-23 19:20:00",
            "zone_type":1
        }
    },
    "push":{
        "from":"push",
        "to":{
            "registration_id":[
                "1a0018970ab49abda3e",
                "100d85590955c1d2793"
            ]
        },
        "body":{
            "platform":"android",
            "notification":{
                "alert":"api device scheduled tasks",
                "android":{
                    "title":"api device scheduled tasks",
                    "extras":{
                        "key1":"value1"
                    }
                }
            },
            "message":{

            },
            "options":{
                "time_to_live":60
            }
        },
        "request_id":"12345",
        "custom_args":"business info"
    }
}

        
This code block in the floating window
  • The following are examples of incorrect updates and corresponding correct updates:
## WRONG: Update the platform in push to ios: { "push": { "body": { "platform": "ios" } } } ## RIGHT: Update the platform in push to ios: { "push":{ "from":"push", "to":{ "registration_id":[ "1a0018970ab49abda3e", "100d85590955c1d2793" ] }, "body":{ "platform":"ios", "notification":{ "alert":"api device scheduled tasks", "ios":{ "title":"api device scheduled tasks", "extras":{ "key1":"value1" } } }, "message":{ }, "options":{ "time_to_live":60 } }, "request_id":"12345", "custom_args":"business info" } } ## The push here must still be valid after updating, otherwise the update will fail.
          ## WRONG: Update the platform in push to ios:
{
    "push": {
        "body": {
            "platform": "ios"
        }
    }
}
## RIGHT: Update the platform in push to ios:
{
    "push":{
        "from":"push",
        "to":{
            "registration_id":[
                "1a0018970ab49abda3e",
                "100d85590955c1d2793"
            ]
        },
        "body":{
            "platform":"ios",
            "notification":{
                "alert":"api device scheduled tasks",
                "ios":{
                    "title":"api device scheduled tasks",
                    "extras":{
                        "key1":"value1"
                    }
                }
            },
            "message":{

            },
            "options":{
                "time_to_live":60
            }
        },
        "request_id":"12345",
        "custom_args":"business info"
    }
}

## The push here must still be valid after updating, otherwise the update will fail.

        
This code block in the floating window

Response example

Success response

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

        
This code block in the floating window
{ "name":"Timed Push Example", "enabled":true, "trigger":{ "single":{ "time":"2022-11-23 19:20:00", "zone_type":1 } }, "push":{ "from":"push", "to":{ "registration_id":[ "1a0018970ab49abda3e", "100d85590955c1d2793" ] }, "body":{ "platform":"ios", "notification":{ "alert":"api device scheduled tasks", "ios":{ "title":"api device scheduled tasks", "extras":{ "key1":"value1" } } }, "message":{ }, "options":{ "time_to_live":60 } }, "request_id":"12345", "custom_args":"business info" } }
          {
    "name":"Timed Push Example",
    "enabled":true,
    "trigger":{
        "single":{
            "time":"2022-11-23 19:20:00",
            "zone_type":1
        }
    },
    "push":{
        "from":"push",
        "to":{
            "registration_id":[
                "1a0018970ab49abda3e",
                "100d85590955c1d2793"
            ]
        },
        "body":{
            "platform":"ios",
            "notification":{
                "alert":"api device scheduled tasks",
                "ios":{
                    "title":"api device scheduled tasks",
                    "extras":{
                        "key1":"value1"
                    }
                }
            },
            "message":{

            },
            "options":{
                "time_to_live":60
            }
        },
        "request_id":"12345",
        "custom_args":"business info"
    }
}

        
This code block in the floating window

Failed response

  • schedule_id is invalid, is not a valid id。
HTTP/1.0 404 Not Found Content-Type: application/json
          HTTP/1.0 404 Not Found
 Content-Type: application/json

        
This code block in the floating window
  • Illegal update operation
HTTP/1.0 400 BAD REQUEST Content-Type: application/json
          HTTP/1.0 400 BAD REQUEST
 Content-Type: application/json

        
This code block in the floating window

Delete scheduled task

Request api url

DELETE https://push.api.engagelab.cc/v4/schedules/{schedule_id}

The schedule_id is the ID of the created schedule task. If the schedule_id is illegal, that is, it is not a valid ID. And then returen 404

Request response

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

        
This code block in the floating window

Response example

Success response

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 in the floating window

Failed response

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

        
This code block in the floating window
{ "error":{ "code":28404, "message":"error message" } }
          {
  "error":{
    "code":28404,
    "message":"error message"
  }
}

        
This code block in the floating window

Error Code

Code HTTP Description Error Message Detail Description
28000 200 return success nil Success status code
28100 400 Invalid parameter The schedule-task is invalid:section is invalid;has been at term;expired;request data is not json;update target task;Delete target task;schedule request is not exist
  • The parameter is illegal or invalid
  • The push exceeds the limit (for example, the push broadcast exceeds the limit, the number of scheduled tasks exceeds the limit, and the fixed speed tasks exceed the limit).
  • The parameter body is too long.
  • 28101 401 Authentication failed Basic authentication failed. The appkey and mastersketch do not match.
    28104 404 The requested schedule task does not exist Request schedule operation doesn't exist The corresponding task has been sent, or the schedule id is wrong.
    28105 404 Setting time has no corresponding push target The push task is invalid. There is no push target for the scheduled time Wrong push time parameter
    28200 500 System internal error Server Internal error. An unexpected error occurred.
    28203 503 System internal error, please try again later Execute action timeout, please try later again Communication error with schedule server.
    在文档中心打开