tencent cloud

UserID-Targeted Push
Download PDF
Last updated:2026-02-28 10:42:43
UserID-Targeted Push
Last updated: 2026-02-28 10:42:43
Download PDF
Feature Overview
Push to the specified recipient account list, which should contain between [1, 500] accounts.
Supports Online Channel, Manufacturer Channel (APNS, Huawei, Honor, OPPO, vivo, Xiaomi, Meizu, Google).
Does not increment unread count by default.
Note:
This interface supports both Online Push and Offline Push. Online Push is supported only in SDK Version ≥ 8.2.6325.

API Calling Description

Sample request URL

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

Request parameters

Parameter
Description
https
Request protocol: 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
v4/timpush/batch
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 Chat console when creating an app
random
A random 32-bit unsigned integer ranging from 0 to 4294967295
contenttype
Fixed value: json

Call frequency limit

The default free edition supports 10 times/s, standard version 30 times/s, and advanced edition 40 times/s.

Sample request packets

{
  "From_Account": "administrator",
  "To_Account": ["user1","user2"], // Array size range between [1,500]
  "MsgRandom": 3674128,
  "OfflinePushInfo": {
      "PushFlag": 0,  // 0 means offline push enabled, 1 means offline push disabled
      "Title": "Offline Push Title",
      "Desc": "Offline Push Content"
  }
}
Note:
This interface supports both Online Push and Offline Push. Online Push is supported only in SDK Version ≥ 8.2.6325.

Request packet fields

Field
Type
Attribute
Description
From_Account
String
Required
Sender account, support UserID or RegistrationID.
To_Account
Array
Required
Target user account list, support UserID or RegistrationID.
MsgRandom
Integer
Required
32-bit unsigned integer random number, with a value range from 0 to 4294967295
Backend uses message deduplication within the same second. Please ensure it is a random number.
OfflinePushInfo
Object
Required
Offline push notification configuration, please refer to OfflinePushInfo Description
DataId
String
Optional
The customer's business custom identifier. This field will be passed through to the app backend during the callback. The field is limited to a maximum of 64 bytes.

Sample response packets

All successful:
{
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 0,
    "TaskId": "batch_667015d4_537529d8_2000005e80aa873_d03ac87_56f5e750"
}
All failed:
{
    "ActionStatus": "FAIL",
    "ErrorInfo": "Invalid format of MsgRandom", // MsgRandom is invalid or not set
    "ErrorCode": 90001,
    "TaskId": ""
}
Partially successful:
{
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 0,
    "TaskId": "batch_667015d4_537529d8_2000005e80aa873_d03ac87_56f5e750",
    "ErrorList": [
        {
            "ErrorCode": 70107, // account does not exist
            "To_Account": "user"
        }
    ]
}

Response packet field description

Field
Type
Description
ActionStatus
String
Request processing result:
OK: means processing is successful.
FAIL: processing failed.
ErrorCode
Integer
Error code.
ErrorInfo
String
Error message.
TaskId
String
Push task ID.
ErrorList
Object Array
Account list with sending failed. If all sent successfully, ErrorList is empty.
Field description of the json Object in the ErrorList array
Field
Type
Description
To_Account
String
Target user account: UserID or RegistrationID.
ErrorCode
Integer
Error code.
ErrorInfo
String
Error description, which may be empty.

Error codes

Unless a network error occurs (e.g., a 502 error), the HTTP status code for this interface will always be 200.The real error codes and messages are indicated in the response body by ErrorCode and ErrorInfo. For common error codes (60000 to 79999), see the Error Code document.
Private error codes for this API are as follows:
Error code
Description
90001
Failed to parse the JSON format. Please ensure the request packet conforms to the JSON specification.
90009
The request requires App Administrator permissions.
90045
All-user/Tags/Single Push is Not Enabled.
90057
The provided DataId exceeds the maximum allowed length of 64 bytes.
91000
Internal service error, please try again.

API Debugging Tool

Use the RESTful API Online Test tool to debug this interface.

Reference

All-user/Tag Push
Single push with userID
Obtaining Application Attribute Names
Setting Application Attribute Names
Getting User Attributes
Setting User Attributes
Deleting User Attributes
Getting User Tags
Adding User Tags
Deleting User Tags
Clearing User Tags
Recall Push


Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback