<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	The trigger conditions and timing for the scheduled task. Currently supports one-time tasks (`single`) , periodic tasks (`periodical`) and Intelligent delivery(`intelligent`).
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.

Intelligent Description

Parameter	Type	Optional or Not	Meaning
backup_time	String	Required	Intelligent delivery is a unique feature of EngageLab, designed to optimize the click-through rate of notifications. Every time a user accesses your service through a website or mobile App with the EngageLab SDK installed, we will track the user's most recent active time. The system will record this data and, based on the user's past usage habits, send notifications to each user at an appropriate time according to each user's terminal time zone. For users without active historical data, you need to choose whether to send it immediately or specify a time to send it (based on the end-user's time zone). For immediate sending: now For scheduled sending: The format must be strictly: "yyyy-MM-dd HH:mm:ss", and the time must be in 24-hour format.

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

This code block in the floating window

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

This code block in the floating window

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

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

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

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

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

This code block in the floating window

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

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.
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

This code block in the floating window

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

This code block in the floating window

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

This code block in the floating window

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

This code block in the floating window

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

This code block in the floating window

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

This code block in the floating window

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

This code block in the floating window

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

This code block in the floating window

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

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

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

This code block in the floating window

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

This code block in the floating window

Return Example

Return Success

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

This code block in the floating window

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

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

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

This code block in the floating window

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

This code block in the floating window

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

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 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.