Create Scheduled Task

Description
This API is used to create a scheduled push task, supporting push to all users / tag-based push / single-user push. After creation, the task will be automatically executed at the specified scheduled time.
API Call Description
Sample Request URL
https://xxxxxx/v4/timpush/add_sched_task?usersig=xxx&identifier=admin&sdkappid=88888888&random=99999999&contenttype=json
Request parameters
Parameter
Description
https
The request protocol is: HTTPS
Request method: POST
xxxxxx
The dedicated domain corresponding to the country/region of your SDKAppID.
China: console.tim.qq.com
Singapore: adminapisgp.im.qcloud.com
Seoul: adminapikr.im.qcloud.com
Frankfurt: adminapiger.im.qcloud.com
Silicon Valley: adminapiusa.im.qcloud.com
Jakarta: adminapiidn.im.qcloud.com
Riyadh: adminapiksa.im.qcloud.com
v4/timpush/add_sched_task
Request API
usersig
The Signature generated by the App admin account. For details, see Generating UserSig﻿
identifier
You must be an App admin account. For more details, see App Admins﻿
sdkappid
SdkAppid assigned by the Instant Messaging Console when an application is created
random
A random 32-bit unsigned integer ranging from 0 to 4294967295
contenttype
Fixed value: json
Call frequency limit
5 requests per second.
Sample Request Body
Tag-based push scheduled task
{
    "Sdkappid": 88888888,
    "Type": "Tag",
    "SchedAt": "2025-06-01 10:00:00",
    "Content": {
        "From_Account": "administrator",
        "Condition": {
            "TagsAnd": ["Stock A","Stock B"]
        },
        "OfflinePushInfo": {
            "Title": "Offline Push Title",
            "Desc": "Offline Push Content"
        }
    }
}
Push to all users scheduled task
{
    "Sdkappid": 88888888,
    "Type": "All",
    "SchedAt": "2025-06-01 10:00:00",
    "Content": {
        "From_Account": "administrator",
        "OfflinePushInfo": {
            "Title": "Offline Push Title",
            "Desc": "Offline Push Content"
        }
    }
}
﻿
Single-user push scheduled task
{
    "Sdkappid": 88888888,
    "Type": "User",
    "SchedAt": "2025-06-01 10:00:00",
    "Content": {
        "From_Account": "administrator",
        "To_Account": ["user1","user2"], // Array size range: [1, 500]
        "OfflinePushInfo": {
            "Title": "Offline Push Title",
            "Desc": "Offline Push Content"
        }
    }
}
Request Body Field Description
Field
Type
Required
Description
Sdkappid
Integer
Yes
The SDKAppID of the application. Must match the sdkappid in the URL.
Type
String
Yes
Push task type: All for push to all users, Tag for tag-based push, User for single-user push.
SchedAt
String
Yes
Scheduled time in the format `YYYY-MM-DD HH:MM:SS` (UTC time), e.g. 2025-06-01 10:00:00.
Content
Object
Yes
The content of Content varies depending on the value of the Type field:
When Type is All or Tag: The Content structure is the same as the request body of Push to All / Tag-based Push, but MsgRandom is not required.
When Type is User: The Content structure is the same as the request body of Single-user Push, but MsgRandom is not required.
Sample Response Body
Successful creation
{
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 0,
    "TaskID": 1234567890
}
Failed creation
{
    "ActionStatus": "FAIL",
    "ErrorInfo": "invalid request! check failed: invalid type: xxx, parse to tasktype failed: invalid type: xxx",
    "ErrorCode": 90104,
    "TaskID": 0
}
Response Body Field Description
Field
Type
Description
ActionStatus
String
The result of the request. OK indicates success, FAIL indicates failure.
ErrorCode
Integer
Error code. 0 indicates success, non- 0 indicates failure.
ErrorInfo
String
Error message.
TaskID
Integer
The scheduled task ID returned upon successful creation. Can be used for subsequent query, modify, and delete operations.
InvalidUserID
Array
List of invalid user IDs (returned only when invalid accounts exist).
Error Codes
Unless a network error occurs (e.g. 502 error), the HTTP return code of this API is always 200. The actual error code and error message are indicated by ErrorCode and ErrorInfo in the response body. For common error codes (60000 to 79999), see the Error Codes documentation.
The private error codes for this API are as follows:
Error Code
Description
90105
Internal error.
90108
Some accounts are invalid (the request contains non-existent user IDs).
90109
Scheduled task quota exceeded.
90110
Invalid scheduled time (e.g. the scheduled time has already passed).
﻿

Parameter	Description
https	The request protocol is: HTTPS Request method: POST
xxxxxx	The dedicated domain corresponding to the country/region of your SDKAppID. China: `console.tim.qq.com` Singapore: `adminapisgp.im.qcloud.com` Seoul: `adminapikr.im.qcloud.com` Frankfurt: `adminapiger.im.qcloud.com` Silicon Valley: `adminapiusa.im.qcloud.com` Jakarta: `adminapiidn.im.qcloud.com` Riyadh: `adminapiksa.im.qcloud.com`
v4/timpush/add_sched_task	Request API
usersig	The Signature generated by the App admin account. For details, see Generating UserSig
identifier	You must be an App admin account. For more details, see App Admins
sdkappid	SdkAppid assigned by the Instant Messaging Console when an application is created
random	A random 32-bit unsigned integer ranging from 0 to 4294967295
contenttype	Fixed value: `json`

Field	Type	Required	Description
Sdkappid	Integer	Yes	The SDKAppID of the application. Must match the sdkappid in the URL.
Type	String	Yes	Push task type: `All` for push to all users, `Tag` for tag-based push, `User` for single-user push.
SchedAt	String	Yes	Scheduled time in the format `YYYY-MM-DD HH:MM:SS` (UTC time), e.g. `2025-06-01 10:00:00`.
Content	Object	Yes	The content of Content varies depending on the value of the Type field: When Type is `All` or `Tag`: The Content structure is the same as the request body of Push to All / Tag-based Push, but MsgRandom is not required. When Type is `User`: The Content structure is the same as the request body of Single-user Push, but MsgRandom is not required.

Error Code	Description
90105	Internal error.
90108	Some accounts are invalid (the request contains non-existent user IDs).
90109	Scheduled task quota exceeded.
90110	Invalid scheduled time (e.g. the scheduled time has already passed).