logo
English
English
繁體中文
简体中文
日本語
ภาษาไทย
Contact Us
Login
icon AppPushicon WebPushicon WhatsAppicon Emailicon SMSicon OTP
EngageLab Docs >AppPush >REST API >Scheduled Tasks API
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) and periodic tasks (periodical). 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.

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

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.
在文档中心打开
icon
Contact Sales