이 페이지는 현재 영어로만 제공되며 한국어 버전은 곧 제공될 예정입니다. 기다려 주셔서 감사드립니다.
Docs Overview/
Pushing to All/Tagged Users/

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
The signature generated by the app admin account. For details, see Generating 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
The information to be pushed offline. For more information, see Message Formats.

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

Use the RESTful API online debugging tool to debug this API.

References

Pushing to All/Tagged Users
Setting Application Attribute Names
Obtaining Application Attribute Names
Setting User Attributes
Deleting User Attributes
Obtaining User Attributes
Obtaining User Tags
Adding User Tags
Deleting User Tags
Deleting All User Tags
Recalling Push