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.