<strong>Scheduled Tasks API</strong>

Overview

The API level supports the timing function.

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

notice： Call Api Function to Query/Update/Delete Schedule info.

Call Validation

For more information, see the Authentication method

Schedule Parameter Description

Every schedule task includes name、enabled、trigger、push those four fields.

Keyword	Type	Optianlal	Description
name	string	required	The name of the schedule task, which cannot exceed 255 bytes and consists of Chinese characters, letters, numbers and underscores.
enabled	bool	required	The current status of the task. It must be true when creating a task.
trigger	JSOS Object	required	Timing task trigger time and trigger conditions. Currently, only scheduled tasks (single) are supported. Please refer to the single description for details.
push	JSOS Object	required	For push content information.

Single Description

Describes the triggering conditions for the schedule task, including the trigger time and type of scheduled task.

Parameter	Type	Optional	Description
time	String	No	The trigger time for the scheduled task, in the standard time format "yyyy-mm-dd hh:mm:ss", such as "2014-02-15 13:16:59". Incomplete formats like "2014-2-15 13:16:59" or "2014-12-15 13:16" are not acceptable. The latest time for a scheduled task cannot exceed one year.
zone_type	Int	No	Indicates the type of scheduled task: 1 for triggering according to the time zone set by the main site, 2 for triggering according to the time zone of the user's terminal.

Periodical Description

Parameter	Type	Optional	Description
start	String	No	The effective start time of the periodic task, strictly in the format "yyyy-MM-dd HH:mm:ss", and must be in the 24-hour clock.
end	String	No	The expiration time of the periodic task, same format as above. The maximum span for a periodic task should not exceed one year.
time	String	No	The specific time when the periodic task is triggered, strictly in the format "HH:mm:ss", and must be in the 24-hour clock.
time_unit	String	No	The smallest time unit for the periodic task execution, with three options: "day", "week", and "month". Case insensitive.
point	String	No	A list corresponding to time_unit: see the table below.
zone_type	Int	No	Indicates the type of scheduled task: 1 for triggering according to the time zone set by the main site, 2 for triggering according to the time zone of the user's terminal.

Detailed information about the point parameter:

time_unit	point	Description
day	NULL	When time_unit is day, the point is not applicable.
week	"MON","TUE","WED","THU","FRI","SAT","SUN"	For week, point can be one or more days indicating when to trigger, case insensitive.
month	"01","02","03" ... "31"	For month, point corresponds to valid dates of the month, will not trigger on invalid dates, such as the 31st or 30th in February.

Create a scheduled task

request api task

POST v4/schedules

Call restrictions

The total number of valid scheduled tasks (currently unexpired) is 1000 by default. If the total number is exceeded, the new scheduled task will prompt failure.
The maximum span time of the task is unlimited, 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

このコードブロックは、フローティングウィンドウに表示されます

request body

{ "name":"schedule 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":"web", "notification":{ "web": { "alert": "welcome to engagelab", "title": "welcome to engagelab", "url": "https://www.engagelab.com/", "extras": { "key1": "value1" } } }, "message":{ }, "options":{ "time_to_live":60 } }, "request_id":"12345", "custom_args":{ "Engagelab": "push to you" } } }

          {
    "name":"schedule 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":"web",
            "notification":{
                "web": {
                    "alert": "welcome to engagelab",
                    "title": "welcome to engagelab",
                    "url": "https://www.engagelab.com/",
                    "extras": {
                        "key1": "value1"
                    }
                }
            },
            "message":{

            },
            "options":{
                "time_to_live":60
            }
        },
        "request_id":"12345",
        "custom_args":{
             "Engagelab": "push to you"
    }
    }
}

このコードブロックは、フローティングウィンドウに表示されます

request body description

zone_type is the required field, the value is 1 or 2, Otherwise, it will be pushed according to the time zone of the server
The enabled field must be true when it is first created. Cannot create a task with enabled: false, otherwise the creation will fail.
pUse must be a valid and legal push action, or the creation fails.

Return Example：

Return Success

< 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

このコードブロックは、フローティングウィンドウに表示されます

{ "schedule_id": "a9b85590-6cec-4f91-b277-2d82b0e20ef6", "name": "the schedule task name" }

          {
    "schedule_id": "a9b85590-6cec-4f91-b277-2d82b0e20ef6",
    "name": "the schedule task name"
}

このコードブロックは、フローティングウィンドウに表示されます

Return Error

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

このコードブロックは、フローティングウィンドウに表示されます

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

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

このコードブロックは、フローティングウィンドウに表示されます

Repeated scheduled task request example

{ "name":"Timed Push Example_periodical", "enabled":true, "trigger":{ "periodical": { "start": "2024-01-01 00:00:00", "end": "2024-02-10 00:00:00", "time": "12:00:00", "time_unit": "day", "point": [], "zone_type": 1 } }, "push":{ "from":"push", "to":{ "registration_id":[ "1a0018970ab49abda3e", "100d85590955c1d2793" ] }, "body":{ "platform":"web", "notification":{ "web": { "alert": "welcome to engagelab", "title": "welcome to engagelab", "url": "https://www.engagelab.com/", "extras": { "key1": "value1" } } }, "message":{ }, "options":{ "time_to_live":60 } }, "request_id":"67890", "custom_args":{ "Engagelab": "push to you" } } }

          {
    "name":"Timed Push Example_periodical",
    "enabled":true,
    "trigger":{
        "periodical": {
            "start": "2024-01-01 00:00:00",
            "end": "2024-02-10 00:00:00",
            "time": "12:00:00",
            "time_unit": "day",
            "point": [],
            "zone_type": 1
        }
    },
    "push":{
        "from":"push",
        "to":{
            "registration_id":[
                "1a0018970ab49abda3e",
                "100d85590955c1d2793"
            ]
        },
        "body":{
            "platform":"web",
            "notification":{
                "web": {
                    "alert": "welcome to engagelab",
                    "title": "welcome to engagelab",
                    "url": "https://www.engagelab.com/",
                    "extras": {
                        "key1": "value1"
                    }
                }
            },
            "message":{

            },
            "options":{
                "time_to_live":60
            }
        },
        "request_id":"67890",
        "custom_args":{
             "Engagelab": "push to you"
    }
    }
}

このコードブロックは、フローティングウィンドウに表示されます

Get a valid scheduled task list

Gets the list of currently valid (unexpired) schedules.

Request Api Url

GET v4/schedules?page=

Request Example

Request Header

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

このコードブロックは、フローティングウィンドウに表示されます

Returns the detailed schedule-task list of the current request page. If no page is specified, the page is 1.
Sorting rule: creation time, completed by schedule-service.
If the number of requested pages is greater than the total number of pages, the page is the request value and the schedule 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.

Return Example

Return success

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

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

このコードブロックは、フローティングウィンドウに表示されます

{ "total_count": 1000, "total_pages": 5 "page": 4, // current page "schedules": [ { "schedule_id": "0eac1b80-c2ac-4b69-948b-c65b34b96512", "name": "", "enabled":ture }, {}, // detail info list] }

          {
    "total_count": 1000,
    "total_pages": 5
    "page": 4, // current page
    "schedules": [
        {
            "schedule_id": "0eac1b80-c2ac-4b69-948b-c65b34b96512",
            "name": "",
            "enabled":ture
        },
        {}, // detail info list]
    }

このコードブロックは、フローティングウィンドウに表示されます

1000 schedule-tasks，5 total pages, the current page is 4，including 50 schedule-tasks info。
the schedules array is the schedule-tasks detail list

Get scheduled task details

Get the details of the scheduled task with the current user's schedule task id {schedule_id}

Request Api Url

GET v4/schedules/{schedule_id}

Request Example

Request Header

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

このコードブロックは、フローティングウィンドウに表示されます

Return Example

Return Success

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

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

このコードブロックは、フローティングウィンドウに表示されます

Return Data

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

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

このコードブロックは、フローティングウィンドウに表示されます

if the schedule_id is not exists, then return 404, or it will return the detail of schedule-task

Get all the message ids of the scheduled task

get all the message ids of the current user's scheduled task that is id {schedule_id}

Request Api Url

GET 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

このコードブロックは、フローティングウィンドウに表示されます

Response Example

Successful 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

このコードブロックは、フローティングウィンドウに表示されます

Response Data

The return data format was updated after the repeat scheduled task feature went online on February 22, 2024, adding the return MsgIds data to replace the old msgids. Please make sure your code are compatible.
The ts field indicates the timestamp when the scheduled task is executed successfully, accurate to milliseconds.

{ "count": 1, "MsgIds": [ "{\"msg_id\":\"1088009\",\"error\":{\"code\":0,\"message\":\"\"},\"needRetry\":false,\"ts\":1707278411611}", "{\"msg_id\":\"0\",\"error\":{\"code\":1011,\"message\":\"Cannot find sending target\"},\"needRetry\":false,\"ts\":1707278411611}" ] }

          {
    "count": 1,
    "MsgIds": [
        "{\"msg_id\":\"1088009\",\"error\":{\"code\":0,\"message\":\"\"},\"needRetry\":false,\"ts\":1707278411611}",
        "{\"msg_id\":\"0\",\"error\":{\"code\":1011,\"message\":\"Cannot find sending target\"},\"needRetry\":false,\"ts\":1707278411611}"
    ]
}

このコードブロックは、フローティングウィンドウに表示されます

Updating a Scheduled Task

Update the schedule task of the specified id

Request Api Url

PUT 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

このコードブロックは、フローティングウィンドウに表示されます

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

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

このコードブロックは、フローティングウィンドウに表示されます

Can not update the scheduled task that had expired
The timing tasks pushed by the terminal time zone and the timing tasks pushed by the master time zone cannot be updated with each other, and vice versa.
Can update the one or mulitples fileds in ["name", "enabled", "trigger", "push"] array. The update body can not a part, need to be a whole body. List below:

{ "name":"the scheduled 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":"web", "notification":{ "web": { "alert": "welcome to engagelab", "title": "welcome to engagelab", "url": "https://www.engagelab.com/", "extras": { "key1": "value1" } } }, "message":{ }, "options":{ "time_to_live":60 } }, "request_id":"12345", "custom_args":{ "Engagelab": "push to you" } } }

          {
    "name":"the scheduled 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":"web",
            "notification":{
                "web": {
                    "alert": "welcome to engagelab",
                    "title": "welcome to engagelab",
                    "url": "https://www.engagelab.com/",
                    "extras": {
                        "key1": "value1"
                    }
                }
            },
            "message":{

            },
            "options":{
                "time_to_live":60
            }
        },
        "request_id":"12345",
        "custom_args":{
             "Engagelab": "push to you"
    }
    }
}

このコードブロックは、フローティングウィンドウに表示されます

The following are examples of incorrect updates and corresponding correct updates：

## Incorrect: only update the alert in the push field： { "push": { "alert": "web scheduled task" } } ## Correct: update the alert in the push field： { "push":{ "from":"push", "to":{ "registration_id":[ "1a0018970ab49abda3e", "100d85590955c1d2793" ] }, "body":{ "platform":"web scheduled task", "notification":{ "web": { "alert": "welcome to engagelab", "title": "welcome to engagelab", "url": "https://www.engagelab.com/", "extras": { "key1": "value1" } } }, "message":{ }, "options":{ "time_to_live":60 } }, "request_id":"12345", "custom_args":{ "Engagelab": "push to you" } } } ## the push field must be valid, or it will update failed

          ## Incorrect: only update the alert in the push field：
{
    "push": {
        "alert": "web scheduled task"
    }
}
## Correct: update the alert in the push field：
{
    "push":{
        "from":"push",
        "to":{
            "registration_id":[
                "1a0018970ab49abda3e",
                "100d85590955c1d2793"
            ]
        },
        "body":{
            "platform":"web scheduled task",
            "notification":{
                "web": {
                    "alert": "welcome to engagelab",
                    "title": "welcome to engagelab",
                    "url": "https://www.engagelab.com/",
                    "extras": {
                        "key1": "value1"
                    }
                }
            },
            "message":{

            },
            "options":{
                "time_to_live":60
            }
        },
        "request_id":"12345",
        "custom_args":{
             "Engagelab": "push to you"
    }
    }
}

## the push field must be valid, or it will update failed

このコードブロックは、フローティングウィンドウに表示されます

Return Example

Return Success

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

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

このコードブロックは、フローティングウィンドウに表示されます

{ "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":"web", "notification":{ "web": { "alert": "welcome to engagelab", "title": "welcome to engagelab", "url": "https://www.engagelab.com/", "extras": { "key1": "value1" } } }, "message":{ }, "options":{ "time_to_live":60 } }, "request_id":"12345", "custom_args":{ "Engagelab": "push to you" } } }

          {
    "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":"web",
            "notification":{
                "web": {
                    "alert": "welcome to engagelab",
                    "title": "welcome to engagelab",
                    "url": "https://www.engagelab.com/",
                    "extras": {
                        "key1": "value1"
                    }
                }
            },
            "message":{

            },
            "options":{
                "time_to_live":60
            }
        },
        "request_id":"12345",
        "custom_args":{
             "Engagelab": "push to you"
    }
    }
}

このコードブロックは、フローティングウィンドウに表示されます

Return Error

schedule_id is invalid

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

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

このコードブロックは、フローティングウィンドウに表示されます

Illegal update operation

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

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

このコードブロックは、フローティングウィンドウに表示されます

Deleting a Scheduled Task

Request Api Url

DELETE v4/schedules/{schedule_id}

schedule_id is the id of an existing schedule task. If schedule_id is invalid or not a valid id, the result will be a 404 error.

request example

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

このコードブロックは、フローティングウィンドウに表示されます

return example

Return Success

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

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

このコードブロックは、フローティングウィンドウに表示されます

Return Error

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

このコードブロックは、フローティングウィンドウに表示されます

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

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

このコードブロックは、フローティングウィンドウに表示されます

Error Code

Code	HTTP	Description	Error Message	Detail Desciption
28000	200	return success	nil	success status
28100	400	parameter is invalid	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.	appkey、masterscrect are schedule servernot match
28104	404	the schedule task is not exists	Request schedule operation doesn't exist	The corresponding task has been sent, or the schedule id is incorrect.
28105	404	Set time without corresponding push target	The push task is invalid. There is no push target for the scheduled time	push time parameter is invalid
28200	500	internal error	Server Internal error.	An unexpected error occurred.
28203	503	Internal system error, please try again later	Execute action timeout, please try later again	Communication error with schedule-server.