logo
ภาษาไทย
English
繁體中文
简体中文
日本語
ภาษาไทย
Español
ติดต่อเรา
เข้าสู่ระบบ
icon AppPushicon WebPushicon WhatsAppicon Emailicon SMSicon OTPicon Marketing Automation
EngageLab ไฟล์ >WebPush >REST API >Scheduled Tasks API
EngageLab ไฟล์ >WebPush >REST API >Scheduled Tasks API

Scheduled Tasks API

อัพเดทล่าสุด ：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 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
    โค้ดนี้โชว์เป็นหน้าต่างลอย

    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"
    }
    }
}
    โค้ดนี้โชว์เป็นหน้าต่างลอย

    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
    โค้ดนี้โชว์เป็นหน้าต่างลอย
    { "schedule_id": "a9b85590-6cec-4f91-b277-2d82b0e20ef6", "name": "the schedule task name" }
              {
    "schedule_id": "a9b85590-6cec-4f91-b277-2d82b0e20ef6",
    "name": "the schedule task name"
}
    โค้ดนี้โชว์เป็นหน้าต่างลอย

    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
    โค้ดนี้โชว์เป็นหน้าต่างลอย
    { "error": { "code": 28400, "message": "error message" } }
              {
    "error": {
        "code": 28400,
        "message": "error message"
    }
}
    โค้ดนี้โชว์เป็นหน้าต่างลอย

    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"
    }
    }
}
    โค้ดนี้โชว์เป็นหน้าต่างลอย

    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
    โค้ดนี้โชว์เป็นหน้าต่างลอย
    • 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
    โค้ดนี้โชว์เป็นหน้าต่างลอย
    { "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]
    }
    โค้ดนี้โชว์เป็นหน้าต่างลอย
    • 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
    โค้ดนี้โชว์เป็นหน้าต่างลอย

    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
    โค้ดนี้โชว์เป็นหน้าต่างลอย

    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": {...}
}
    โค้ดนี้โชว์เป็นหน้าต่างลอย
    • 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
    โค้ดนี้โชว์เป็นหน้าต่างลอย

    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 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
    โค้ดนี้โชว์เป็นหน้าต่างลอย
    { "name": "task", "enabled": true, "trigger": {...}, "push": {...} }
              {
  "name": "task", 
  "enabled": true, 
  "trigger": {...},
  "push": {...} 
}
    โค้ดนี้โชว์เป็นหน้าต่างลอย
    • 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"
    }
    }
}
    โค้ดนี้โชว์เป็นหน้าต่างลอย
    • 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
    โค้ดนี้โชว์เป็นหน้าต่างลอย

    Return Example

    Return Success

    HTTP/1.0 200 CREATED Content-Type: application/json
              HTTP/1.0 200 CREATED
 Content-Type: application/json
    โค้ดนี้โชว์เป็นหน้าต่างลอย
    { "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"
    }
    }
}
    โค้ดนี้โชว์เป็นหน้าต่างลอย

    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
    โค้ดนี้โชว์เป็นหน้าต่างลอย
    • Illegal update operation
    HTTP/1.0 400 BAD REQUEST Content-Type: application/json
              HTTP/1.0 400 BAD REQUEST
 Content-Type: application/json
    โค้ดนี้โชว์เป็นหน้าต่างลอย

    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
    โค้ดนี้โชว์เป็นหน้าต่างลอย

    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
    โค้ดนี้โชว์เป็นหน้าต่างลอย

    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
    โค้ดนี้โชว์เป็นหน้าต่างลอย
    { "error":{ "code":28404, "message":"error message" } }
              {
  "error":{
    "code":28404,
    "message":"error message"
  }
}
    โค้ดนี้โชว์เป็นหน้าต่างลอย

    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
    ติดต่อฝ่ายขาย