Scheduled Tasks API

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, refer to the fields in the Create a push API

Single Description

The trigger conditions of the schedule task, including the trigger time and the scheduled task type.

Keyword	Type	Option	Description
time	string	required	The trigger time of the scheduled task, using the yyyy-mm-dd hh:mm:ss format, eg: "2014-02-15 13:16:59" can not be "2014-2-15 13:16:59" or "2014-12-15 13:16", The latest time for scheduled tasks cannot exceed one year
zone_type	int	required	the type of the scheduled task: value 1 is the push according to the time zone set by the web service value 2 is the push according to the time zone set by the user's location

Create a scheduled task

request api task

POST https://webpush.api.engagelab.cc/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":{ "alert":"Api web timed task", //optional "web":{ "alert":"Api web timed task", "title":"Api web timed task", "extras":{ "key1":"value1" } } }, "message":{ }, "options":{ "time_to_live":60 } }, "request_id":"12345", "custom_args":"business info" } }

          {
    "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":{
                "alert":"Api web timed task", //optional
                "web":{
                    "alert":"Api web timed task",
                    "title":"Api web timed task",
                    "extras":{
                        "key1":"value1"
                    }
                }
            },
            "message":{

            },
            "options":{
                "time_to_live":60
            }
        },
        "request_id":"12345",
        "custom_args":"business info"
    }
}

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

Get a valid scheduled task list

Gets the list of currently valid (unexpired) schedules.

Request Api Url

GET https://webpush.api.engagelab.cc/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 https://webpush.api.engagelab.cc/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 https://webpush.api.engagelab.cc/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

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 Error

{ "count": 3, "msgids": [ "12345567", "2234567", "3234567" ] }

          {
    "count": 3,
    "msgids": [
        "12345567",
        "2234567",
        "3234567"
    ]
}

This code block in the floating window

Update the Scheduled Task

Update the schedule task of the specified id

Request Api Url

PUT https://webpush.api.engagelab.cc/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":{ "alert":"api web scheduled task", "web":{ "title":"api web scheduled task", "extras":{ "key1":"value1" } } }, "message":{ }, "options":{ "time_to_live":60 } }, "request_id":"12345", "custom_args":"business info" } }

          {
    "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":{
                "alert":"api web scheduled task",
                "web":{
                    "title":"api web scheduled task",
                    "extras":{
                        "key1":"value1"
                    }
                }
            },
            "message":{

            },
            "options":{
                "time_to_live":60
            }
        },
        "request_id":"12345",
        "custom_args":"business info"
    }
}

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":{ "alert":"web ", "web":{ "title":"api web scheduled task", "extras":{ "key1":"value1" } } }, "message":{ }, "options":{ "time_to_live":60 } }, "request_id":"12345", "custom_args":"business info" } } ## 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":{
                "alert":"web ",
                "web":{
                    "title":"api web scheduled task",
                    "extras":{
                        "key1":"value1"
                    }
                }
            },
            "message":{

            },
            "options":{
                "time_to_live":60
            }
        },
        "request_id":"12345",
        "custom_args":"business info"
    }
}

## 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":{ "alert":"Web scheduled task", "web":{ "title":"Web scheduled task", "extras":{ "key1":"value1" } } }, "message":{ }, "options":{ "time_to_live":60 } }, "request_id":"12345", "custom_args":"business info" } }

          {
    "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":{
                "alert":"Web scheduled task",
                "web":{
                    "title":"Web scheduled task",
                    "extras":{
                        "key1":"value1"
                    }
                }
            },
            "message":{

            },
            "options":{
                "time_to_live":60
            }
        },
        "request_id":"12345",
        "custom_args":"business info"
    }
}

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

Delete schedule Task

Request Api Url

DELETE https://webpush.api.engagelab.cc/v4/schedules/{schedule_id}

The schedule_id is the id of the created schedule task. If the schedule_id is illegal or not a valid id, then 404.

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.