tencent cloud

Pushing to All/Tagged Users
Download PDF
Last updated: 2025-10-27 10:39:23
Pushing to All/Tagged Users
Last updated: 2025-10-27 10:39:23
Download PDF
All-user/Tag Push supports sending specific content and can also send personalized content to specific user groups based on Tags and attributes, for example, membership activities, regional notifications, etc. This helps in user acquisition, conversion, activation promotion, and other operational phases, while also supporting push delivery reports and self-service push troubleshooting tools. For specific effects, please refer to Effect Display.

Feature Overview

Support pushing to all users.
Support pushing by user attributes.
Support pushing by user Tags.
Support online channels and vendor channels (APNS, Huawei, Honor, OPPO, vivo, Xiaomi, Meizu, Google).
Due to the large number of accounts that need to be delivered for All-user/Tag Push, it takes a certain amount of time to deliver all accounts (depending on the total number of accounts).
Note:
This API supports both online and offline push. Online push is supported only in SDK Version >= 8.2.6325.

API Calling Description

Sample request URL

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

Request parameters

Parameter
Description
https
Request protocol: HTTPS
Request method: POST
xxxxxx
The country/region where your SDKAppID is located.
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/push
Request API
usersig
The signature generated by the App Administrator Account. For details on the procedure, see Generate UserSig
identifier
Must be an App Administrator Account. For more details, see App Administrator
sdkappid
SdkAppid assigned by the Chat console when an app is created
random
A random 32-bit unsigned integer ranging from 0 to 4294967295
contenttype
Fixed value: json

Call frequency limit

This API includes all-user, attribute, and Tag Push. By default, it can be invoked up to 100 times per day, with an interval of more than 1 second between each push.
Note:
API Frequency Limit. By default, you can make 100 free calls per day. Each additional call will cost an extra $10 per day. If you need to adjust the API frequency, please go to the Chat Console.

Sample request packets

Note:
This API supports both online and offline push. Online push is supported only in SDK Version >= 8.2.6325.

All-user Push Examples

The administrator pushes to all users:
{
  "From_Account": "administrator",
  "MsgRandom": 3674128,
  "OfflinePushInfo": {
      "PushFlag": 0,  // 0 means offline push enabled, 1 means offline push disabled
      "Title": "Offline Push Title",
      "Desc": "Offline Push Content"
  }
}
Push only to online users (Online Push):
{
  "From_Account": "administrator",
  "MsgRandom": 3674128,
  "OfflinePushInfo": {
      "PushFlag": 1,  // 0 means offline push enabled, 1 means offline push disabled
      "Ext": "Transparent content"
  }
}

Push by User Tag Examples

The administrator pushes to users tagged with "Stock A" and "Stock B":
{
  "From_Account": "administrator",
  "MsgRandom": 124032,
  "Condition": {
      "TagsAnd": ["Stock A","Stock B"]
  },
  "OfflinePushInfo": {
      "PushFlag": 0, // 0 means offline push enabled, 1 means offline push disabled
      "Title": "Offline Push Title",
      "Desc": "Offline Push Content"
  }
}
The administrator pushes to users tagged with "Stock A" or "Stock B":
{
  "From_Account": "administrator",
  "MsgRandom": 124032,
  "Condition": {
      "TagsOr": ["Stock A","Stock B"]
  },
  "OfflinePushInfo": {
      "PushFlag": 0, // 0 means offline push enabled, 1 means offline push disabled
      "Title": "Offline Push Title",
      "Desc": "Offline Push Content"
  }
}
Admin pushes messages to users following "Stock A" or "stock B" and not following "Stock C" or "stock D":
{
  "From_Account": "administrator",
  "MsgRandom": 124032,
  "Condition": {
      "TagsOr": ["Stock A","stock B"],
      "TagsNot": ["Stock C","Stock D"] // Push scope: ("Stock A" or "stock B") and not ("Stock C" and "Stock D")
  },
  "OfflinePushInfo": {
      "PushFlag": 0, // 0 means perform offline push, 1 means do not perform offline push
      "Title": "Offline Push Title",
      "Desc": "Offline push content"
  }
}

Push by User Attribute

The administrator pushes messages to ultra-platinum members in Shenzhen:
{
  "From_Account": "administrator",
  "MsgRandom": 389475,
  "Condition": {
      "AttrsAnd": {
          "Membership Level": "Ultra-Platinum Member",
          "city": " Shenzhen "
      }
  },
  "OfflinePushInfo": {
      "PushFlag": 0, // 0 means offline push enabled, 1 means offline push disabled
      "Title": "Offline Push Title",
      "Desc": "Offline Push Content"
  }
}
The administrator pushes messages to ultra-platinum users in Shenzhen:
{
  "From_Account": "administrator",
  "MsgRandom": 389475,
  "Condition": {
      "AttrsAnd": {
          "Membership Level": "Ultra-Platinum User",
          "city": " Shenzhen "
      }
  },
  "OfflinePushInfo": {
      "PushFlag": 0, // 0 means offline push enabled, 1 means offline push disabled
      "Title": "Offline Push Title",
      "Desc": "Offline Push Content"
  }
}

Request packet fields

Field
Type
Attribute
Description
From_Account
String
Optional
Message Sender Account (supports specifying any existing account)
If the sender is not specified or the specified sender does not exist, the default will be the caller's account.
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.
Condition
Object
Optional
Push the filter criteria for the current audience. If the Condition is not filled, it pushes to all users. For details, see Condition Field Description.
OfflinePushInfo
Object
Optional
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.

Condition Field Description

Field
Type
Attribute
Description
TagsOr
String Array
Optional

Union of tag conditions, array length not exceeding 10.
TagsAnd
String Array
Optional
Intersection of tag conditions, array length not exceeding 10.
TagsNot
String Array
Optional
Negation of tag conditions (first take the union of multiple tags, then complement the result), array length not exceeding 10.
AttrsOr
Object
Optional
Union of attribute conditions, array length not exceeding 10.
AttrsAnd
Object
Optional
Intersection of attribute conditions, array length not exceeding 10.
Note: It is advisable not to mix Tags and attributes, as the scope of push targets may become chaotic. Different Tag conditions and different attribute conditions can be used together.
"Condition": {"TagAnd": ["tag1", "tag2"], "TagOr": ["tag3", "tag4"], "TagNot": ["tag5", "tag6"]}
First compute the result of the "TagAnd" field: tag1 and tag2=A.
Then compute the result of the "TagOr" field: tag3 or tag4=B.
Then compute the result of the "TagNot" field: not (tag5 or tag6)=C.
Note: The final result of "Condition" is A and B and C.

Sample response packets

{
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 0,
    "TaskId": "53743040_144115212910570789_4155518400_15723514"
}

Response packet fields description

Field
Type
Description
ActionStatus
String
Result of request processing:
OK: Indicates successful processing
FAIL: Indicates failure
ErrorCode
Integer
Error code
ErrorInfo
String
Error message
TaskId
String
Push task ID

Error codes

Unless a network error occurs (e.g., 502 error), the HTTP return code for this interface is always 200. The actual error codes and error messages are indicated by ErrorCode and ErrorInfo in the response body. Common error codes (60000 to 79999) can be found in the Error Codes documentation.
The private error codes for this API are as follows:
Error code
Description of Meaning
90001
Failed to parse the JSON string, please check if the request packet conforms to JSON format.
90005
The MsgRandom field is missing in the JSON format request body or the MsgRandom field is not of Integer type.
90009
The request requires App Administrator access.
90020
Tag length exceeds the limit (cannot exceed 50 bytes).
90022
Duplicate Tag in TagsOr and TagsAnd in push conditions.
90024
Excessive Frequency of Push, the interval between two pushes must be greater than 1 second.
90026
Message offline storage time error (must not exceed 7 days).
90032
The number of tags in push conditions exceeds 10, or the number of tags in the add tag request exceeds 10.
90033
Invalid attribute.
90039
Attribute push and Tag push cannot coexist.
90040
One of the tags in the push conditions is empty.
90045
The all-staff/Tag push feature is not activated.
90047
The number of pushes has exceeded the daily limit (default is 100 times).
90056
The request body for universal push notification is too large. Currently, a maximum length of 10K is supported.
90057
The provided DataId exceeds the maximum allowed length of 64 bytes.
91000
Internal service error. Please try again.

API Debugging Tool

Use the REST API online testing tool to debug this API.

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