SMS

OTP

Marketing Automation

EngageLab Docs >AppPush >REST API >Scheduled Tasks API

Scheduled Tasks API

Last updated：2024-02-22

The API layer supports timed functions, maintaining a Schedule object for independent task execution.

Note: Scheduled tasks created through the API can only be retrieved, modified, or deleted through API calls.

Authentication

Please refer to the authentication methods in the REST API overview for details.

Schedule Parameter Descriptions

Each schedule task comprises four sections: name, enabled, trigger, and push.

Parameter	Type	Optional	Description
name	String	No	The name of the schedule task, must not exceed 255 bytes, consisting of Chinese characters, letters, numbers, and underscores.
enabled	Boolean	No	Indicates the current status of the task; it must be true when creating a task.
trigger	JSON Object	No	The trigger conditions and timing for the scheduled task. Currently supports one-time tasks (`single`) , periodic tasks (`periodical`) and Intelligent delivery(`intelligent`). See single description for details.
push	JSON Object	No	The content information for the push, refer to the fields in the app push documentation.

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.

Creating a Scheduled Task

Endpoint

POST v4/schedules

Limitations

The total number of effective scheduled tasks (not yet expired) is by default limited to 1000. Creating new tasks will fail if this number is exceeded.
There's no restriction on the maximum span of a scheduled task, but it's recommended not to exceed 1 year.

Request Example

Request Headers

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

Single scheduled task request example

{ "name":"Timed Push Example_single", "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":"Scheduled task from API", "android":{ "title":"Scheduled task from API", "extras":{ "key1":"value1" } } }, "message":{ }, "options":{ "time_to_live":60 } }, "request_id":"12345", "custom_args":{ "Engagelab": "push to you" } } }

          {
    "name":"Timed Push Example_single",
    "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":"Scheduled task from API",
                "android":{
                    "title":"Scheduled task from API",
                    "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

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":"android", "notification":{ "alert":"repeats periodic tasks", "android":{ "title":"repeats periodic tasks", "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":"android",
            "notification":{
                "alert":"repeats periodic tasks",
                "android":{
                    "title":"repeats periodic tasks",
                    "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

Intelligent delivery request example

{ "name":"Intelligent delivery", "enabled":true, "trigger":{ "intelligent": { "backup_time":"2024-01-01 00:00:00" } } , "push":{ "from":"push", "to":{ "registration_id":[ "1a0018970ab49abda3e", "100d85590955c1d2793" ] }, "body":{ "platform":"android", "notification":{ "alert":"Scheduled task from API", "android":{ "title":"Scheduled task from API", "extras":{ "key1":"value1" } } }, "message":{ }, "options":{ "time_to_live":60 } }, "request_id":"12345", "custom_args":{ "Engagelab": "push to you" } } }

          {
    "name":"Intelligent delivery",
    "enabled":true,
    "trigger":{
        "intelligent": {
        "backup_time":"2024-01-01 00:00:00" 
        }
    } ,
    "push":{
        "from":"push",
        "to":{
            "registration_id":[
                "1a0018970ab49abda3e",
                "100d85590955c1d2793"
            ]
        },
        "body":{
            "platform":"android",
            "notification":{
                "alert":"Scheduled task from API",
                "android":{
                    "title":"Scheduled task from API",
                    "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 Data Explanation

zone_type must be filled with specified field values (1 or 2); otherwise, the push will occur according to the server's time zone.
When a scheduled task is initially created, the enabled field must be true. Creation of a task with enabled: false will fail.
push must be a valid and legal push action; otherwise, the creation will fail.

Response Example

Successful Response

HTTP/1.1 200 OK Content-Type: application/json

          HTTP/1.1 200 OK
Content-Type: application/json

This code block in the floating window

{ "schedule_id": "a9b85590-6cec-4f91-b277-2d82b0e20ef6", "name": "Timed Task Name" }

          {
    "schedule_id": "a9b85590-6cec-4f91-b277-2d82b0e20ef6",
    "name": "Timed Task Name"
}

This code block in the floating window

Failure 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

Obtain a list of current effective (not expired) schedules.

Endpoint

GET 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

The details of the schedule-task list for the current request page are returned. If the page is not specified, it defaults to page 1.
Sorting is done by creation time and is handled by the schedule-service.
If the requested page number exceeds the total pages, the page will be the requested value, and schedules will be empty.
A maximum of 50 tasks per page are returned. If the actual number of tasks on the requested page is less than 50, the actual number of tasks is returned.

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

{ "total_count": 1000, "total_pages": 5, "page": 4, "schedules": [ { "schedule_id": "0eac1b80-c2ac-4b69-948b-c65b34b96512", "name": "", "enabled": true }, {} // List of detailed information. ] }

          {
    "total_count": 1000,
    "total_pages": 5,
    "page": 4,
    "schedules": [
        {
            "schedule_id": "0eac1b80-c2ac-4b69-948b-c65b34b96512",
            "name": "",
            "enabled": true
        },
        {} // List of detailed information.
    ]
}

This code block in the floating window

This indicates a total of 1000 schedule-tasks, across 5 pages, with the current page being page 4, including information on 50 schedule-tasks.
The schedules returned are a detailed list of schedule-task information.

Get scheduled task details

Obtain the details of a schedule task with the id {schedule_id} for the current user.

Endpoint

GET 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

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

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

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

This code block in the floating window

Get all the message ids of the scheduled task

Retrieve a list of all message IDs for the scheduled task with the id {schedule_id} belonging to the current user.

Endpoint

GET v4/schedules/{schedule_id}/msg-ids

Request Example

Request Headers

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 a specified schedule task by its id.

Endpoint

PUT v4/schedules/{schedule_id}

Request Example

Request Headers

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

Request Body

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

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

This code block in the floating window

Note:

Expired schedule tasks cannot be updated.
Tasks scheduled by terminal time zone cannot be updated to main site time zone and vice versa.
Update operation can include changes in "name", "enabled", "trigger", or "push". Partial updates are not supported.

Incorrect Update Operation Examples

// WRONG: Only updating the platform to iOS: { "push": { "body": { "platform": "ios" } } }

          // WRONG: Only updating the platform to iOS:
{
    "push": {
        "body": {
            "platform": "ios"
        }
    }
}

This code block in the floating window

// WRONG: Only updating the end date: { "trigger": { "periodical": { "end": "2024-03-10 00:00:00" } } }

          // WRONG: Only updating the end date:
{
    "trigger": {
        "periodical": {
            "end": "2024-03-10 00:00:00"
        }
    }
}

This code block in the floating window

Correct Update Operation Examples

When updating, you need to include all relevant subfields under the push field to ensure the update operation complies with the requirement for a complete update. Here is the updated complete push configuration after changing the platform to iOS:

// RIGHT: Updating the platform to iOS: { "name": "Scheduled Push Example", "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": "ios", "notification": { "alert": "API terminal scheduled task", "ios": { "title": "API terminal scheduled task", "extras": { "key1": "value1" } } }, "message": {}, "options": { "time_to_live": 60 } }, "request_id": "12345", "custom_args": { "Engagelab": "push to you" } } } // RIGHT: Extending the periodical trigger's end date by one month: { "name": "Scheduled Push Example", "enabled": true, "trigger": { "periodical": { "start": "2024-01-01 00:00:00", // Maintain the original start time "end": "2024-03-10 00:00:00", // Extend by one month to March 10 "time": "12:00:00", // Maintain the original trigger time "time_unit": "day", // Maintain the original time unit "point": [], // Maintain the original points configuration "zone_type": 1 // Maintain the original time zone type } }, "push": { "from": "push", "to": { "registration_id": [ "1a0018970ab49abda3e", "100d85590955c1d2793" ] }, "body": { "platform": "android", "notification": { "alert": "API terminal scheduled task", "android": { "title": "API terminal scheduled task", "extras": { "key1": "value1" } } }, "message": {}, "options": { "time_to_live": 60 } }, "request_id": "12345", "custom_args": { "Engagelab": "push to you" } } }

          // RIGHT: Updating the platform to iOS:

{
    "name": "Scheduled Push Example",
    "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": "ios",
            "notification": {
                "alert": "API terminal scheduled task",
                "ios": {
                    "title": "API terminal scheduled task",
                    "extras": {
                        "key1": "value1"
                    }
                }
            },
            "message": {},
            "options": {
                "time_to_live": 60
            }
        },
        "request_id": "12345",
        "custom_args": {
            "Engagelab": "push to you"
        }
    }
}

// RIGHT: Extending the periodical trigger's end date by one month:

{
    "name": "Scheduled Push Example",
    "enabled": true,
    "trigger": {
        "periodical": {
            "start": "2024-01-01 00:00:00",  // Maintain the original start time
            "end": "2024-03-10 00:00:00",  // Extend by one month to March 10
            "time": "12:00:00",  // Maintain the original trigger time
            "time_unit": "day",  // Maintain the original time unit
            "point": [],  // Maintain the original points configuration
            "zone_type": 1  // Maintain the original time zone type
        }
    },
    "push": {
        "from": "push",
        "to": {
            "registration_id": [
                "1a0018970ab49abda3e",
                "100d85590955c1d2793"
            ]
        },
        "body": {
            "platform": "android",
            "notification": {
                "alert": "API terminal scheduled task",
                "android": {
                    "title": "API terminal scheduled task",
                    "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

In these updates, ensure that the push remains valid and effective; otherwise, the update will fail. Always submit a complete structure in your update operations to avoid failures due to partial updates.

Response Example

Successful 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

Response Data

{ "name": "Timed Push Example", "enabled": true, "trigger": {...}, "push": {...} }

          {
    "name": "Timed Push Example",
    "enabled": true,
    "trigger": {...},
    "push": {...}
}

This code block in the floating window

Failure Response

If schedule_id is invalid or 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

If the update operation is invalid:

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

Endpoint

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

Response Example

Successful Response

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

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

This code block in the floating window

Failure 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 Codes

Below is a table of the possible error codes you could encounter when using the Scheduled Task API.

Code	HTTP	Description	Error Message	Detailed Explanation
28000	200	Correct return	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 does not exist	Invalid or illegal parameters, or push exceeds limits.
28101	401	Authentication failed	Basic authentication failed.	Appkey and master secret do not match.
28104	404	The requested schedule task does not exist	Requested schedule operation doesn't exist	Task already sent or schedule id is incorrect.
28105	404	No push target for the set time	The push task is invalid. There is no push target for the scheduledtime	push time parameters are incorrect.
28200	500	Internal server error	Server Internal error.	An unexpected error occurred.
28203	503	Internal server error, retry later	Execute action timeout, please try later again	Communication error with schedule-server.

Catalog

Authentication
Schedule Parameter Descriptions
Creating a Scheduled Task
Get a valid scheduled task list
Get scheduled task details
Get all the message ids of the scheduled task
Updating a Scheduled Task
Deleting a Scheduled Task
Error Codes

在文档中心打开