文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>即时通信 IM>推送服务（Push）>服务端 API>定时任务 API>创建定时任务

创建定时任务

最近更新时间：2026-04-07 16:52:11

我的收藏

本页目录：

功能说明

本接口用于创建一个定时推送任务，支持全员/标签推送、单发推送。任务创建后将在指定的调度时间自动执行推送。

接口调用说明

请求 URL 示例

https://xxxxxx/v4/timpush/add_sched_task?usersig=xxx&identifier=admin&sdkappid=88888888&random=99999999&contenttype=json

请求参数说明

参数
说明
https
请求协议为：HTTPS。
请求方式为：POST。
xxxxxx
SDKAppID 所在国家/地区对应的专属域名。
中国：console.tim.qq.com
新加坡：adminapisgp.im.qcloud.com
首尔： adminapikr.im.qcloud.com
法兰克福：adminapiger.im.qcloud.com
硅谷：adminapiusa.im.qcloud.com
雅加达：adminapiidn.im.qcloud.com
v4/timpush/add_sched_task
请求接口。
usersig
App 管理员账号生成的签名，参见 UserSig 后台 API。
identifier
必须为 App 管理员账号，更多详情请参见 App 管理员。
sdkappid
创建应用时即时通信控制台分配的 SdkAppid。
random
请输入随机的32位无符号整数，取值范围0 - 4294967295。
contenttype
固定值为：json。

调用频率限制

每秒5次。

请求包示例

标签推送定时任务
{
    "Sdkappid": 88888888,
    "Type": "Tag",
    "SchedAt": "2025-06-01 10:00:00",
    "Content": {
        "From_Account": "administrator",
        "Condition": {
            "TagsAnd": ["股票A","股票B"]
        },
        "OfflinePushInfo": {
            "Title": "离线推送标题",
            "Desc": "离线推送内容"
        }
    }
}
全员推送定时任务
{
    "Sdkappid": 88888888,
    "Type": "All",
    "SchedAt": "2025-06-01 10:00:00",
    "Content": {
        "From_Account": "administrator",
        "OfflinePushInfo": {
            "Title": "离线推送标题",
            "Desc": "离线推送内容"
        }
    }
}

单发推送定时任务
{
    "Sdkappid": 88888888,
    "Type": "User",
    "SchedAt": "2025-06-01 10:00:00",
    "Content": {
        "From_Account": "administrator",
        "To_Account": ["user1","user2"], // 数组大小范围在[1,500]之间
        "OfflinePushInfo": {
            "Title": "离线推送标题",
            "Desc": "离线推送内容"
        }
    }
}

请求包字段说明

字段
类型
必填
说明
Sdkappid
Integer
是
应用的 SDKAppID，必须与 URL 中的 sdkappid 一致。
Type
String
是
推送任务类型：All 代表全员推送，Tag 代表标签推送，User 代表单发推送。
SchedAt
String
是
定时调度时间，格式为 YYYY-MM-DD HH:MM:SS（UTC 时间），例如 2025-06-01 10:00:00。
Content
Object
是
Content 的具体内容根据 Type 字段的值不同而不同：
Type 为 All 或 Tag 时：Content 结构与 全员/标签推送 的请求包一致，但无需填写 MsgRandom 。
Type 为 User 时：Content 结构与单发推送 的请求包一致，但无需填写 MsgRandom 。

应答包体示例

创建成功
{
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 0,
    "TaskID": 1234567890
}
创建失败
{
    "ActionStatus": "FAIL",
    "ErrorInfo": "invalid request! check failed: invalid type: xxx, parse to tasktype failed: invalid type: xxx",
    "ErrorCode": 90104,
    "TaskID": 0
}

应答包字段说明

字段
类型
说明
ActionStatus
String
请求处理的结果，OK 表示处理成功，FAIL 表示失败。
ErrorCode
Integer
错误码，0 表示成功，非 0 表示失败。
ErrorInfo
String
错误信息。
TaskID
Integer
创建成功后返回的定时任务 ID，后续可用于查询、修改、删除操作。
InvalidUserID
Array
无效的用户 ID 列表（仅在存在无效账号时返回）。

错误码说明

除非发生网络错误（例如502错误），否则该接口的 HTTP 返回码均为200。真正的错误码，错误信息是通过应答包体中的 ErrorCode、ErrorInfo 来表示的。公共错误码（60000到79999）参见 错误码 文档。
本 API 私有错误码如下：
错误码
说明
90105
内部错误。
90108
部分账号无效（请求中包含不存在的用户 ID）。
90109
定时任务配额超限。
90110
调度时间无效（如调度时间已过期）。

中国站