Pushing to All/Tagged Users
Pushing to all/tagged users not only supports sending specific content to all users, but also can send personalized content to specific user groups based on tags and attributes, such as member events and regional notifications. This helps effectively attract, convert, and activate new users. It also supports pushing delivery reports and self-service troubleshooting tools. Refer to Feature Overview for the effect.
Note:
The account must have been logged in or manually imported before it can receive push messages.
Feature Overview
Supports sending push messages to all users.
Supports sending push messages based on user attributes.
Supports sending push messages based on user tags.
The administrator pushes a message, and the recipient sees that the sender of the message is the administrator.
The administrator specifies an account to push a message to other accounts, and the recipient sees that the sender is not the administrator, but the account specified by the administrator.
Supports roaming, with the same storage duration as regular messages.
Due to the large number of accounts that need to be delivered for pushing to all/tagged users, it takes a certain amount of time (depending on the total number of accounts) to complete the delivery of all accounts.
By setting OnlineOnlyFlag to 1, push messages can only be sent without saving sessions, roaming, and unread messages.
API Call Description
Sample Request URL
https://xxxxxx/v4/timpush/push?usersig=xxx&identifier=admin&sdkappid=88888888&random=99999999&contenttype=json
Request Parameters
Parameter | Description |
https | The request protocol is HTTPS and the request method is POST. |
xxxxxx | The dedicated domain name corresponding to the country/region of the 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/push | Request API. |
usersig | |
identifier | The app admin account. |
sdkappid | The SDKAppID assigned by the Chat console when an application is created. |
random | A random 32-bit unsigned integer. |
contenttype | The value is always json . |
Call Frequency
This API includes pushing to all users and pushing to users by attribute or tag. By default, it can be called 100 times per day. The interval between two pushes must be greater than 1 second.
Note:
By default, the API can be called 100 times per day for free. For each additional call per day, the cost will increase by 10 USD per day. If you need to adjust the frequency of API calls, go to the Chat console to modify it.
Sample Request Packets
Pushing Messages to All Users
The administrator pushes messages to all users:
{"From_Account": "admin","MsgRandom": 3674128,"OnlineOnlyFlag": 0, // 0: Saves roaming and unread messages. In this case, the push concurrency limit is 200 users/second;// 1: Does not save roaming or unread messages. In this case, there is no push concurrency limit."MsgBody": [{"MsgType": "TIMTextElem","MsgContent": {"Text": "hi, beauty"}}],"OfflinePushInfo": {"PushFlag": 0, // 0: Enables offline push; 1: Disables offline push."Title": "offline push title","Desc": "offline push content"}}
The administrator specifies an account for pushing messages to all users. In the example, the sender account is
xiaoming
:{"From_Account": "xiaoming","MsgRandom": 3674128,"OnlineOnlyFlag": 0, // 0: Saves roaming and unread messages. In this case, the push concurrency limit is 200 users/second;// 1: Does not save roaming or unread messages. In this case, there is no push concurrency limit."MsgBody": [{"MsgType": "TIMTextElem","MsgContent": {"Text": "hi, beauty"}}],"OfflinePushInfo": {"PushFlag": 0, // 0: Enables offline push; 1: Disables offline push."Title": "offline push title","Desc": "offline push content"}}
Note:
From_Account is the message sender account and can be specified as any existing account. If no sender is specified or the specified sender does not exist, the API caller account will be taken by default.
The administrator pushes messages only to online users (online push):
{"From_Account": "xiaoming","MsgRandom": 3674128,"OnlineOnlyFlag": 1, // 0: Saves roaming and unread messages. In this case, the push concurrency limit is 200 users/second;// 1: Does not save roaming or unread messages. In this case, there is no push concurrency limit."MsgBody": [{"MsgType": "TIMTextElem","MsgContent": {"Text": "hi, beauty"}}],"OfflinePushInfo": {"PushFlag": 1, // 0: Enables offline push; 1: Disables offline push.}}
Note:
Setting OnlineOnlyFlag to 1 indicates only push (online push+offline push). Setting OfflinePushInfo.PushFlag to 1 indicates no offline push. Therefore, the above example indicates that messages are pushed only to online users.
Pushing Messages by User Tag
The administrator pushes messages to users tagged with "Stock A" and "Stock B":
{"From_Account": "admin","MsgRandom": 124032,"OnlineOnlyFlag": 0, // 0: Saves roaming and unread messages. In this case, the push concurrency limit is 200 users/second;// 1: Does not save roaming or unread messages. In this case, there is no push concurrency limit."Condition": {"TagsAnd": ["Stock A","Stock B"]},"MsgBody": [{"MsgType": "TIMTextElem","MsgContent": {"Text": "hi, beauty"}}],"OfflinePushInfo": {"PushFlag": 0, // 0: Enables offline push; 1: Disables offline push."Title": "offline push title","Desc": "offline push content"}}
The administrator pushes messages to users tagged with "Stock A" or "Stock B":
{"From_Account": "admin","MsgRandom": 124032,"OnlineOnlyFlag": 0, // 0: Saves roaming and unread messages. In this case, the push concurrency limit is 200 users/second;// 1: Does not save roaming or unread messages. In this case, there is no push concurrency limit."Condition": {"TagsOr": ["Stock A","Stock B"]},"MsgBody": [{"MsgType": "TIMTextElem","MsgContent": {"Text": "hi, beauty"}}],"OfflinePushInfo": {"PushFlag": 0, // 0: Enables offline push; 1: Disables offline push."Title": "offline push title","Desc": "offline push content"}}
Pushing Messages by User Attribute
The administrator pushes messages to Platinum Premier membership in Shenzhen:
{"From_Account": "admin","MsgRandom": 389475,"OnlineOnlyFlag": 0, // 0: Saves roaming and unread messages. In this case, the push concurrency limit is 200 users/second;// 1: Does not save roaming or unread messages. In this case, there is no push concurrency limit."Condition": {"AttrsAnd": {"level": "Platinum Premier Membership","city": "Shenzhen"}},"MsgBody": [{"MsgType": "TIMTextElem","MsgContent": {"Text": "hi, beauty"}}],"OfflinePushInfo": {"PushFlag": 0, // 0: Enables offline push; 1: Disables offline push."Title": "offline push title","Desc": "offline push content"}}
Note:
From_Account is the message sender account and can be specified as any existing account. If no sender is specified or the specified sender does not exist, the API caller account will be taken by default.
The administrator pushes messages to Platinum Premier users in Shenzhen:
{"From_Account": "admin","MsgRandom": 389475,"OnlineOnlyFlag": 0, // 0: Saves roaming and unread messages. In this case, the push concurrency limit is 200 users/second;// 1: Does not save roaming or unread messages. In this case, there is no push concurrency limit."Condition": {"AttrsAnd": {"level": "Platinum Premier Users","city": "Shenzhen"}},"MsgBody": [{"MsgType": "TIMTextElem","MsgContent": {"Text": "hi, beauty"}}],"OfflinePushInfo": {"PushFlag": 0, // 0: Enables offline push; 1: Disables offline push."Title": "offline push title","Desc": "offline push content"}}
Request Fields
Field | Type | Required | Description |
From_Account | String | No | Account of the message sender, which can be specified as any existing account. Note: If no sender is specified or the specified sender does not exist, the API caller account will be taken by default. |
MsgRandom | Integer | Yes | A random number (32-bit unsigned integer) of the message. It is used by the backend for message deduplication within the same second. Make sure a random number is entered. |
OnlineOnlyFlag | Integer | No | The default value is 0, which means to save roaming and unread messages. In this case, the push concurrency limit is 200 users/second. 1 means not to save historical messages and not to count unread messages. In this case, there is no push concurrency limit. |
Condition | Object | No | Valid values: The or condition of attributes: AttrsOr The and condition of attributes: AttrsAnd The or condition of tags: TagsOr The and condition of tags: TagsAnd Note: AttrsOr, AttrsAnd, TagsOr, and TagsAnd cannot coexist. If no condition is specified, messages are pushed to all users. |
TagsOr | Array | No | The union of tag conditions. A tag is a string of up to 50 bytes. Note: Attributes and tags cannot be used as push conditions at the same time. The TagsOr condition can contain up to 10 tags. |
TagsAnd | Array | No | The intersection of tag conditions. A tag is a string of up to 50 bytes. Note: Attributes and tags cannot be used as push conditions at the same time. The TagsAnd condition can contain up to 10 tags. |
AttrsOr | Object | No | The union of attribute conditions. |
AttrsAnd | Object | No | The intersection of attribute conditions. |
MsgBody | Array | Yes | Message body. For more information on the message format, see Message Formats. Note that MsgBody is an array that can contain multiple message elements. |
MsgType | String | Yes | TIM message object type. Valid values: TIMTextElem (text message)TIMLocationElem (location message)TIMFaceElem (emoji message)TIMCustomElem (custom message)TIMSoundElem (voice message)TIMImageElem (image message)TIMFileElem (file message)TIMVideoFileElem (video message) |
MsgContent | Object | Yes | Different message object types ( MsgType ) have different formats (MsgContent ). For more information, see the TIMMsgElement section in Message Formats. |
OfflinePushInfo | Object | No |
Sample Response Packets
{"ActionStatus": "OK","ErrorInfo": "","ErrorCode": 0,"TaskId": "53743040_144115212910570789_4155518400_15723514"}
Response Fields
Field | Type | Description |
ActionStatus | String | Processing result. OK : succeeded. FAIL : failed. |
ErrorCode | Integer | Error code. |
ErrorInfo | String | Error information. |
TaskId | String | Push task ID. |
Error Codes
Unless a network error (such as error 502) occurs, the HTTP return code for this API is always 200.
ErrorCode
and ErrorInfo
in the response packets represent the actual error code and error information. For common error codes (60000 to 79999), see Error Codes.
The following table describes the error codes specific to this API:Error Code | Description |
90001 | Failed to parse the JSON format. Check whether the request packets meet JSON specifications. |
90002 | The MsgBody field in the JSON request packets does not meet message format requirements or it is not an array. For more information, see the TIMMsgElement section in Message Formats. |
90005 | The MsgRandom field is missing in the JSON request packets or it is not an integer. |
90007 | The MsgBody field in the JSON request packets is not an array. Change it to an array. |
90009 | The request requires app admin permissions. |
90010 | The JSON request packets do not meet message format requirements. For more information, see the TIMMsgElement section in Message Formats. |
90020 | The tag length exceeds the limit (the maximum length allowed is 50 bytes). |
90022 | TagsOr and TagsAnd in the push conditions contain repeated tags. |
90024 | Pushes are too frequent. The interval between two pushes must be greater than 1 second. |
90026 | Incorrect offline message storage period. The value cannot exceed 7 days. |
90032 | The number of tags in the push conditions exceeds 10, or the number of tags in the tag adding request exceeds 10. |
90033 | Invalid attribute. |
90039 | Message push by attribute and message push by tag are mutually exclusive. |
90040 | A tag in the push conditions is null. |
90045 | The feature of pushing to all/tagged users is not enabled. |
90047 | The number of pushes exceeds the daily quota (default quota: 100). |
91000 | Internal service error. Try again. |
API Debugging Tool
References