Pushing to All/Tagged Users
All-user/Tag Push supports sending specific content, and also allows for the delivery of personalized content to specific user groups based on Tag, attribute, such as Membership Activities, Regional Notifications, etc. It aids in User Acquisition, Conversion, Activation Promotion, and other operational work phases, while also supporting Push Delivery Reports, Self-service Push Troubleshooting Tool. For more details, please see Effect Display.
Note:
1. An account must have logged in or been manually imported to receive messages from All-staff/Tag Push.
2. Universal Push Notification does not support Message Modification.
Feature Overview
Supports sending pushes to all users.
Supports sending pushes based on user attributes.
Supports sending pushes by user Tag.
When an administrator pushes a message, the recipient sees the message sender as the administrator.
When an administrator specifies an account to push messages to other accounts, the recipient sees the sender not as the administrator, but as the account specified by the administrator.
Supports roaming, with the roaming storage duration consistent with that of regular message storage.
Due to the large number of accounts that need to be issued for All-user/Tag Push, it takes some time to issue all accounts (depending on the total number of accounts).
By setting the OnlineOnlyFlag to 1, push notifications can be sent without saving the session, roaming, and unread messages.
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 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 |
v4/timpush/push | Request API |
usersig | |
identifier | |
sdkappid | SdkAppid assigned by the Chat console when creating an app |
random | 32-bit unsigned integer random number |
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 IM Console.
Sample request packets
Mass Push Example
Administrator conducts a mass push:
{"From_Account": "admin","MsgRandom": 3674128,"OnlineOnlyFlag": 0, // 0 means storing roaming and unread messages with a push concurrency limit of 200 users/second; 1 means not storing roaming and unread messages"MsgBody": [{"MsgType": "TIMTextElem","MsgContent": {"Text": "hi, beauty"}}],"OfflinePushInfo": {"PushFlag": 0, // 0 means offline push enabled, 1 means offline push disabled"Title": "Offline Push Title","Desc": "Offline Push Content"}}
Administrator directs a specific account to conduct a mass push (in the example, the sender's account is xiaoming):
{"From_Account": "xiaoming","MsgRandom": 3674128,"OnlineOnlyFlag": 0, // 0 means storing roaming and unread messages with a push concurrency limit of 200 users/second; 1 means not storing roaming and unread messages"MsgBody": [{"MsgType": "TIMTextElem","MsgContent": {"Text": "hi, beauty"}}],"OfflinePushInfo": {"PushFlag": 0, // 0 means offline push enabled, 1 means offline push disabled"Title": "Offline Push Title","Desc": "Offline Push Content"}}
Note:
From_Account is the message sender account, which supports specifying any existing account. If the sender is not specified or does not exist, the API caller account will be used by default.
Only push to online users (Online Push):
{"From_Account": "xiaoming","MsgRandom": 3674128,"OnlineOnlyFlag": 1, // 0 means storing roaming and unread messages with a push concurrency limit of 200 users/second; 1 means not storing roaming and unread messages"MsgBody": [{"MsgType": "TIMTextElem","MsgContent": {"Text": "hi, beauty"}}],"OfflinePushInfo": {"PushFlag": 1 // 0 means offline push enabled, 1 means offline push disabled}}
Note:
OnlineOnlyFlag set to 1 indicates push operations for both online and offline users, but OfflinePushInfo.PushFlag set to 1 means there will be no offline push. Therefore, the above example signifies that only online users will be pushed to.
Push by User Tag Example
The administrator pushes messages to users tagged with both "Stock A" and "Stock B":
{"From_Account": "admin","MsgRandom": 124032,"OnlineOnlyFlag": 0, // 0 means storing roaming and unread messages with a push concurrency limit of 200 users/second; 1 means not storing roaming and unread messages"Condition": {"TagsAnd": ["Stock A","Stock B"]},"MsgBody": [{"MsgType": "TIMTextElem","MsgContent": {"Text": "hi, beauty"}}],"OfflinePushInfo": {"PushFlag": 0, // 0 means offline push enabled, 1 means offline push disabled"Title": "Offline Push Title","Desc": "Offline Push Content"}}
Note:
From_Account is the message sender account, which supports specifying any existing account. If the sender is not specified or does not exist, the API caller account will be used by default.
The administrator pushes messages to users following either "Stock A" or "Stock B":
{"From_Account": "admin","MsgRandom": 124032,"OnlineOnlyFlag": 0, // 0 means storing roaming and unread messages with a push concurrency limit of 200 users/second; 1 means not storing roaming and unread messages"Condition": {"TagsOr": ["Stock A","Stock B"]},"MsgBody": [{"MsgType": "TIMTextElem","MsgContent": {"Text": "hi, beauty"}}],"OfflinePushInfo": {"PushFlag": 0, // 0 means offline push enabled, 1 means offline push disabled"Title": "Offline Push Title","Desc": "Offline Push Content"}}
User Attribute Push
The administrator sends messages to Super Platinum members in Shenzhen:
{"From_Account": "admin","MsgRandom": 389475,"OnlineOnlyFlag": 0, // 0 means storing roaming and unread messages with a push concurrency limit of 200 users/second; 1 means not storing roaming and unread messages"Condition": {"AttrsAnd": {"Membership Level": "Super Platinum Member","city": " Shenzhen "}},"MsgBody": [{"MsgType": "TIMTextElem","MsgContent": {"Text": "hi, beauty"}}],"OfflinePushInfo": {"PushFlag": 0, // 0 means offline push enabled, 1 means offline push disabled"Title": "Offline Push Title","Desc": "Offline Push Content"}}
Note:
From_Account is the message sender account, which supports specifying any existing account. If the sender is not specified or does not exist, the API caller account will be used by default.
The administrator sends messages to Shenzhen users or Super Platinum members:
{"From_Account": "admin","MsgRandom": 389475,"OnlineOnlyFlag": 0, // 0 means storing roaming and unread messages with a push concurrency limit of 200 users/second; 1 means not storing roaming and unread messages"Condition": {"AttrsOr": {"Membership Level": "Super Platinum User","city": " Shenzhen "}},"MsgBody": [{"MsgType": "TIMTextElem","MsgContent": {"Text": "hi, beauty"}}],"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) Note: If the sender is not specified or the specified sender does not exist, the account of the API caller is used by default. |
MsgRandom | Integer | Required | Message Random Number (32-bit unsigned integer), used by the backend for deduplication of messages within the same second. Please ensure this field is filled randomly |
OnlineOnlyFlag | Integer | Optional | The default is 0, indicating storing roaming and unread messages with a push concurrency limit of 200 people/second. 1 indicates not storing history messages and not counting unread messages Note: If you need to adjust the push concurrency limit, please contact Tencent Cloud customer service or business staff. |
Condition | Object | Optional | Condition has 4 types, which are: Attribute's "Or condition" AttrsOr Attribute's "And condition" AttrsAnd Tag's "Or condition" TagsOr Tag's "And condition" TagsAnd Note: AttrsOr, AttrsAnd, TagsOr, TagsAnd cannot coexist. If there is no Condition, it will be pushed to all users. |
TagsOr | Array | Optional | The union of Tag conditions. A Tag is a string that does not exceed 50 bytes. Note: Attribute pushing and Tag pushing cannot both be used as push conditions at the same time. The number of Tags in TagsOr condition cannot exceed 10. |
TagsAnd | Array | Optional | The intersection of Tag conditions. A Tag is a string that does not exceed 50 bytes. Note: Attribute pushing and Tag pushing cannot both be used as push conditions at the same time. The number of Tags in TagsAnd condition cannot exceed 10. |
AttrsOr | Object | Optional | The union of Attribute conditions. Note: Attribute pushing and Tag pushing cannot both be used as push conditions at the same time. |
AttrsAnd | Object | Optional | The intersection of Attribute conditions. Note: Attribute pushing and Tag pushing cannot both be used as push conditions at the same time. |
MsgBody | Array | Required | Message content, please refer to MsgBody Message Content Description (a message can include multiple message elements, so MsgBody is of Array type) |
MsgType | String | Required | TIM message object types currently supported include: TIMTextElem (Text message) TIMLocationElem (Location message) TIMFaceElem (Expression message) TIMCustomElem(Custom message) TIMSoundElem( VMS ) TIMImageElem(Image message) TIMFileElem(File message) TIMVideoFileElem(Video message) |
MsgContent | Object | Required | For each MsgType, use different MsgContent formats, please refer to TIMMsgElement object's Definition |
OfflinePushInfo | Object | Optional | Offline Push Notification Configuration. For details, please refer to the OfflinePushInfo Description |
Sample response packets
{"ActionStatus": "OK","ErrorInfo": "","ErrorCode": 0,"TaskId": "667015d4_537529d8_2000005e80aa873_d03ac87_56f5e750"}
Response packet field description
Field | Type | Description |
ActionStatus | String | Processed Request Result: 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., 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. |
90002 | The MsgBody in the JSON format request packet does not match the message format description, or MsgBody is not of Array type. Please refer to the Definition of TIMMsgElement Object. |
90005 | The JSON format request packet body is missing the MsgRandom field or the MsgRandom field is not of Integer type. |
90007 | The MsgBody type in the JSON format request packet body is not of Array type. Please change it to Array type. |
90009 | The request requires App Administrator permissions. |
90010 | The JSON format request packet does not conform to the message format description. Please refer to the Definition of TIMMsgElement Object. |
90020 | Tag length exceeds the limit (cannot exceed 50 bytes). |
90022 | There are duplicate Tags in the TagsOr and TagsAnd conditions of the push. |
90024 | Pushes are too frequent; the interval between two pushes must be more than 1 second. |
90026 | Error in offline message storage time. |
90032 | The number of tags in the push conditions exceeds 10, or the number of Tags in the add Tag request exceeds 10. |
90033 | Attribute is invalid. |
90039 | Push by Attribute and Push by Tag cannot coexist. |
90040 | One of the tags in the Push Conditions is empty. |
90045 | All-staff/Tag Push feature is not activated. |
90047 | Push Attempts exceed the Daily Limit (default is 100 times). |
90056 | Request body for all-staff push is too large, currently supports a maximum length of 10K. |
91,000 | Internal service error, please try again. |
API Debugging Tool
Reference