このページは現在英語版のみで提供されており、日本語版も近日中に提供される予定です。ご利用いただきありがとうございます。
ドキュメンテーション概要/
Chat/
サーバー API/
RESTful インターフェース/
All/Tagged Push/
Pushing to All/Tagged Users/

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 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

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