AppPush
WebPush
WhatsApp
Email
SMS
OTP
Scheduled Tasks API
最新の更新：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
このコードブロックは、フローティングウィンドウに表示されます
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"
}
}
}
このコードブロックは、フローティングウィンドウに表示されます
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"
}
}
}
このコードブロックは、フローティングウィンドウに表示されます
Request Data Explanation
zone_typemust 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
enabledfield must be true. Creation of a task withenabled: falsewill fail. pushmust 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
このコードブロックは、フローティングウィンドウに表示されます
{
"schedule_id": "a9b85590-6cec-4f91-b277-2d82b0e20ef6",
"name": "Timed Task Name"
}
{
"schedule_id": "a9b85590-6cec-4f91-b277-2d82b0e20ef6",
"name": "Timed Task Name"
}
このコードブロックは、フローティングウィンドウに表示されます
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
このコードブロックは、フローティングウィンドウに表示されます
{
"error": {
"code": 28400,
"message": "error message"
}
}
{
"error": {
"code": 28400,
"message": "error message"
}
}
このコードブロックは、フローティングウィンドウに表示されます
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
このコードブロックは、フローティングウィンドウに表示されます
- 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
pagewill be the requested value, andscheduleswill 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
このコードブロックは、フローティングウィンドウに表示されます
{
"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 indicates a total of 1000 schedule-tasks, across 5 pages, with the current page being page 4, including information on 50 schedule-tasks.
- The
schedulesreturned 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
このコードブロックは、フローティングウィンドウに表示されます
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
{
"schedule_id": "0eac1b80-c2ac-4b69-948b-c65b34b96512",
"name": "定时推送示例",
"enabled": true,
"trigger": {...},
"push": {...}
}
{
"schedule_id": "0eac1b80-c2ac-4b69-948b-c65b34b96512",
"name": "定时推送示例",
"enabled": true,
"trigger": {...},
"push": {...}
}
このコードブロックは、フローティングウィンドウに表示されます
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
このコードブロックは、フローティングウィンドウに表示されます
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 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
このコードブロックは、フローティングウィンドウに表示されます
Request Body
{
"name": "task",
"enabled": true,
"trigger": {...},
"push": {...}
}
{
"name": "task",
"enabled": true,
"trigger": {...},
"push": {...}
}
このコードブロックは、フローティングウィンドウに表示されます
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"
}
}
}
このコードブロックは、フローティングウィンドウに表示されます
// 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"
}
}
}
このコードブロックは、フローティングウィンドウに表示されます
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"
}
}
}
このコードブロックは、フローティングウィンドウに表示されます
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
このコードブロックは、フローティングウィンドウに表示されます
Response Data
{
"name": "Timed Push Example",
"enabled": true,
"trigger": {...},
"push": {...}
}
{
"name": "Timed Push Example",
"enabled": true,
"trigger": {...},
"push": {...}
}
このコードブロックは、フローティングウィンドウに表示されます
Failure Response
- If
schedule_idis 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
このコードブロックは、フローティングウィンドウに表示されます
- 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
このコードブロックは、フローティングウィンドウに表示されます
Deleting a Scheduled Task
Endpoint
DELETE v4/schedules/{schedule_id}
schedule_idis the id of an existing schedule task. Ifschedule_idis 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
このコードブロックは、フローティングウィンドウに表示されます
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
このコードブロックは、フローティングウィンドウに表示されます
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
このコードブロックは、フローティングウィンドウに表示されます
{
"error": {
"code": 28404,
"message": "error message"
}
}
{
"error": {
"code": 28404,
"message": "error message"
}
}
このコードブロックは、フローティングウィンドウに表示されます
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. |
