logo
English
English
繁體中文
简体中文
日本語
ภาษาไทย
Contact Us
Login
icon AppPushicon WebPushicon WhatsAppicon Emailicon SMSicon OTP
EngageLab Docs >WebPush >REST API >Scheduled Tasks API
EngageLab Docs >WebPush >REST API >Scheduled Tasks API

Scheduled Tasks API

Last updated：2024-02-22

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