このページは現在英語版のみで提供されており、日本語版も近日中に提供される予定です。ご利用いただきありがとうございます。

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
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
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 Chat 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
Use the RESTful API Online Test tool to debug this interface.
Reference
﻿All-user/Tag Push﻿
﻿Set application attribute name﻿
﻿Get application attribute name﻿
﻿Set user attributes﻿
﻿Delete user attributes﻿
﻿Get User Attributes﻿
﻿Add User Tags﻿
﻿Get User Tags﻿
﻿Delete User Tags﻿
﻿Clear User Tags﻿
﻿Push Recall﻿
﻿

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	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	32-bit unsigned integer random number
contenttype	Fixed value: json

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

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.