Server APIs

Generating UserSig
RESTful APIs
- RESTful API Overview
- RESTful API List
- Message Related
  - Send Message
    - Sending One-to-One Messages to One User
    - Sending One-to-One Messages to Multiple Users
    - Sending Ordinary Messages in a Group
    - Sending System Messages in a Group
    - Broadcast Message of Audio-Video Group
    - Importing One-to-One Messages
    - Importing Group Messages
  - Historical Message
    - Modifying Historical One-to-one Messages
    - Modifying Historical Group Messages
    - Pulling Historical One-to-one Messages
    - Pulling Historical Group Messages
  - Delete Message
    - Deleting Messages Sent by a Specified User
  - Withdraw Message
    - Recalling One-to-One Messages
    - Recalling Group Messages
  - Read Receipt
    - Marking One-to-One Messages as Read
    - Pulling Group Message Read Receipt Details
    - Pulling Read Receipts for Group Messages
  - Message Extension
    - Pulling the Message Extension of a One-to-One Message
    - Configuring Message Extension for a One-to-One Message
    - Pulling Message Extension of a Group Message
    - Configuring Message Extension for a Group Message
  - Pushing to All Users
    - API for Pushing to All Users
    - Pushing to All Users
    - Setting Application Attribute Names
    - Getting Application Attribute Names
    - Getting User Attributes
    - Setting User Attributes
    - Deleting User Attributes
    - Getting User Tags
    - Adding User Tags
    - Deleting User Tags
    - Deleting All Tags of a User
- Session Related
  - Conversation List
    - Pulling a conversation list
  - Session Unread Count
    - Setting the Unread Message Count of a Member
    - Querying Unread One-to-One Message Count
  - Delete Session
    - Deleting a conversation
  - Session Grouping Tag
    - Creating Conversation Group Data
    - Updating Conversation Group Data
    - Deleting Conversation Group Data
    - Creating or Updating Conversation Mark Data
    - Searching for Conversation Group Marks
    - Pulling Conversation Group Mark Data
- Group Related
  - Group Management
    - Getting All Groups in an App
    - Creating a Group
    - Disbanding a Group
    - Getting the Groups a User Has Joined
  - Group Information
    - Getting Group Profiles
    - Modifying the Profile of a Group
    - Importing a Group Profile
  - Group Member Management
    - Adding Group Members
    - Deleting Group Members
    - Banning Group Members
    - Unbanning Group Members
    - Bulk Muting and Unmuting
    - Getting the List of Muted Group Members
    - Changing Group Owner
    - Querying the Roles of Users in a Group
    - Importing Group Members
  - Group Member Information
    - Getting Group Member Profiles
    - Modifying the Profile of a Group Member
  - Group Custom Attributes
    - Getting Group Custom Attributes
    - Modifying Group Custom Attributes
    - Clearing Group Custom Attributes
    - Resetting Group Custom Attributes
    - Deleting Group Custom Attributes
  - Live Group Management
    - Getting the Number of Online Users in an Audio-Video Group
    - Getting the List of Online Members in Audio-Video Group
    - Setting Audio-Video Group Member Marks
    - Getting the List of Banned Group Members.
  - Community Management
    - Creating Topic
    - Deleting Topic
    - Getting Topic Profile
    - Modifying Topic Profile
    - Importing Topic Profiles
  - Group Counter
    - Getting Group Counters
    - Updating Group Counters
    - Deleting Group Counters
- User Management
  - Account Management
    - Importing a Single Account
    - Importing Multiple Accounts
    - Deleting Accounts
    - Querying Accounts
  - User Information
    - Setting Profiles
    - Pulling Profiles
  - User Status
    - Invalidating Account Login States
    - Querying Account Online Status
  - Friend Management
    - Adding Friends
    - Importing Friends
    - Updating Friends
    - Deleting Friends
    - Deleting All Friends
    - Verifying Friends
    - Pulling Friends
    - Pulling Specified Friends
  - Friend Lists
    - Adding Lists
    - Deleting Lists
    - Pulling Lists
  - Blocklist
    - Blocklisting Users
    - Unblocklisting Users
    - Pulling a Blacklist
    - Verifying Users on a Blocklist
- Global Mute Management
  - Setting Global Mute
  - Querying Global Mute
- Operations Management
  - Pulling Operations Data
  - Downloading Recent Messages
  - Getting Server IP Addresses
- Chatbots
  - Pulling Chatbot Accounts
  - Creating Chatbot Accounts
  - Deleting Chatbot Accounts
Webhooks
- Webhook Overview
- Webhook Command List
- Operations Management Callbacks
  - API Overclocking Alarm Callbacks
- Online Status Webhooks
  - Status Change Webhooks
- Relationship Chain Webhooks
  - After a Profile Is Updated
  - Before a Friend Is Added
  - Before a Friend Request Is Responded
  - After a Friend Is Added
  - After a Friend Is Deleted
  - After a User Is Added to Blocklist
  - After a User Is Removed from Blocklist
- One-to-One Message Webhooks
  - Before a One-to-One Message Is Sent
  - After a One-to-One Message Is Sent
  - After a One-to-One message Is Marked as Read
  - After A One-to-One Message Is Recalled
- Group Webhooks
  - Before a Group Is Created
  - After a Group Is Created
  - Before Applying to Join a Group
  - Before Inviting a User to a Group
  - After a User Joins a Group
  - After a User Leaves a Group
  - Before Group Message Is Sent
  - After a Group Message Is Sent
  - After a Group Is Full
  - After a Group Is Disbanded
  - After Group Profile Is Modified
  - Callback After Recalling Group Messages
  - Webhook for Online and Offline Status of Audio-Video Group Members
  - Webhook for Exceptions When Group Messages Are Sent
  - Before a Topic Is Created
  - After a Topic Is Created
  - After a Topic Is Deleted
  - Topic Profile Change Webhook
  - Callback After Group Member Profile Changed
  - Callback After Group Attribute Changed
  - Callback After Read Receipt
  - Callback After the Group Owner Changed
- Webhook Mutual Authentication Configuration Guide
  - Apache Mutual Authentication Configuration
  - Nginx Mutual Authentication Configuration
- Chatbot webhooks
  - Chatbot Passthrough Message Callback

Pushing to All Users

Pushing to all users is an excellent tool for application user operations. It 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.
Feature Overview
This API can be used to push messages to all users.
This API can be used to push messages by user attribute.
This API can be used to push messages by user tag.
When the admin pushes messages, the message sender displayed to the recipients is the admin.
When the admin specifies an account to push messages to other accounts, the sender displayed to the recipients is not the admin but the account specified by the admin.
This API supports offline storage of messages, but not message roaming.
It takes time to push messages to all users. The required time depends on the number of accounts. Typically, it is within one minute.
This API allows you to push messages only to online users by setting the MsgLifeTime parameter to 0.
Note: 
The "pushing to all users" feature is only available on the IM Ultimate edition. To use it, purchase the Ultimate edition. For more information, see Pricing.
API Call Description
The feature of pushing to all users is available only to users with Ultimate edition accounts. See Configuration Change Ticket to apply for this feature. The feature will be enabled 48 hours after your application is approved.
Sample request URL
https://xxxxxx/v4/all_member_push/im_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
Domain name corresponding to the country/region where your SDKAppID is located.
Chinese mainland: 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/all_member_push/im_push
Request API
usersig
Signature generated in the app admin account. For more information, see Generating UserSig.
identifier
The app administration account.
sdkappid
The SDKAppID assigned by the IM console when an app is created
random
A random 32-bit unsigned integer
contenttype
The value is always json.
Calling frequency
This API includes pushing to all and by attribute and tag. By default, it can be called 100 times every day. The interval between two pushes must be greater than one second.
Sample request
Pushing messages to all users
The admin pushes messages to all users and retains the messages offline for 120 seconds.
{
  "From_Account": "admin",
  "MsgRandom": 56512,
  "MsgLifeTime": 120,
  "MsgBody":[
      {
          "MsgType": "TIMTextElem",
          "MsgContent":{
              "Text": "hi, beauty"
          }
      }
  ]
}
The admin specifies an account for pushing to all users and retains the messages offline for 120 seconds. In the sample, the sender account is xiaoming:
{
  "From_Account": "xiaoming",
  "MsgRandom": 3674128,
  "MsgLifeTime": 120,
  "MsgBody":[
      {
          "MsgType": "TIMTextElem",
          "MsgContent":{
              "Text": "hi, beauty"
          }
      }
  ]
}
The admin specifies an account for pushing to all users, sets offline push information, and retains the messages offline for 120 seconds.
{
  "From_Account": "xiaoming",
  "MsgRandom": 3674128,
  "MsgLifeTime": 120,
  "MsgBody":[
      {
          "MsgType": "TIMTextElem",
          "MsgContent":{
              "Text": "hi, beauty"
          }
      }
  ],
  "OfflinePushInfo": {
      "PushFlag": 0,
      "Desc": "Content to push offline",
      "Ext": "Passthrough content",
      "AndroidInfo": {
          "Sound": "android.mp3"
      },
      "ApnsInfo": {
          "Sound": "apns.mp3",
          "BadgeMode": 1, // If this field is left as default or is set to `0`, the message is counted. If this field is set to `1`, the message is not counted, that is, the badge counter in the upper-right corner does not increase.
          "Title":"apns title", // APNs title
          "SubTitle":"apns subtitle", // APNs subtitle
          "Image":"www.image.com" // Image URL
      }
  }
}
The admin pushes messages to all users and retains the messages offline for 120 seconds.
{
  "From_Account": "admin",
  "MsgRandom": 21302570,
  "MsgLifeTime": 120,
  "MsgBody":[
      {
          "MsgType": "TIMTextElem",
          "MsgContent":{
              "Text": "hi, beauty"
          }
      }
  ]
}
Pushing messages by user tag
The admin pushes messages to users tagged with "Stock A" and "Stock B" and retains the messages offline for 120 seconds.
{
  "From_Account": "admin",
  "MsgRandom": 214,
  "MsgLifeTime": 120,
  "Condition":{
      "TagsAnd": ["Stock A","Stock B"]
  },
  "MsgBody":[
      {
          "MsgType": "TIMTextElem",
          "MsgContent":{
              "Text": "hi, beauty"
          }
      }
  ]
}
The admin pushes messages to users tagged with "Stock A" and "Stock B" and retains the messages offline for 120 seconds.
{
  "From_Account": "admin",
  "MsgRandom": 124032,
  "MsgLifeTime": 120,
  "Condition":{
      "TagsOr": ["Stock A","Stock B"]
  },
  "MsgBody":[
      {
          "MsgType": "TIMTextElem",
          "MsgContent":{
              "Text": "hi, beauty"
          }
      }
  ]
}
Pushing messages by user attribute
The admin pushes messages to Shenzhen Platinum Premier users and retains the messages offline for 120 seconds.
{
  "From_Account": "admin",
  "MsgRandom": 389475,
  "MsgLifeTime": 120,
  "Condition":{
      "AttrsAnd": {
          "Membership Level": "Platinum Premier members",
          "city": "Shenzhen"
      }
  },
  "MsgBody":[
      {
          "MsgType": "TIMTextElem",
          "MsgContent":{
              "Text": "hi, beauty"
          }
      }
  ]
}
The admin pushes messages to Shenzhen Platinum Premier users and retains the messages offline for 120 seconds.
{
  "From_Account": "admin",
  "MsgRandom": 9312457,
  "MsgLifeTime": 120,
  "Condition":{
      "AttrsAnd": {
          "Membership Level": "Platinum Premier users",
          "city": "Shenzhen"
      }
  },
  "MsgBody":[
      {
          "MsgType": "TIMTextElem",
          "MsgContent":{
              "Text": "hi, beauty"
          }
      }
  ]
}
Request fields
Field
Type
Attribute
Description
Condition
Object
Optional
Valid values:
AttrsOr
AttrsAnd
TagsOr
TagsAnd
AttrsOr and AttrsAnd can coexist, and TagsOr and TagsAnd can coexist. However, tag conditions and attribute conditions cannot coexist. If no condition is specified, messages are pushed to all users.
MsgRandom
Integer
Required
Random number (32-bit unsigned integer) of the message. It is used by the backend for message deduplication within a second. Make sure a random number is entered.
MsgBody
Array
Required
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
Required
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
Required
Different message object types (MsgType) have different formats (MsgContent). For more information, see the Message Element TIMMsgElement section in Message Formats.
MsgLifeTime
Integer
Optional
Offline message storage duration, in seconds. The maximum duration is 604,800 seconds (7 days). The default value is 0, which indicates that messages are not stored offline and will be pushed only to online users.
From_Account
String
Optional
Account of the message sender
AttrsOr
Object
Optional
A set of attribute conditions connected by OR. Note that attribute conditions and tag conditions cannot be used at the same time.
AttrsAnd
Object
Optional
A set of attribute conditions connected by AND. Note that attribute conditions and tag conditions cannot be used at the same time.
TagsOr
Array
Optional
Union of tag conditions. A tag is a string of up to 50 bytes. Note that attribute conditions and tag conditions cannot be used at the same time. The TagsOr condition can contain up to ten tags.
TagsAnd
Array
Optional
Intersection of tag conditions. A tag is a string of up to 50 bytes. Note that attribute conditions and tag conditions cannot be used at the same time. The TagsAnd condition can contain up to ten tags.
OfflinePushInfo
Object
Optional
The information to be pushed offline. For more information, see Message Formats.
Sample response
{
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 0,
    "TaskId": "1400123456_144115212910570789_4155518400_15723514"
}
Response fields
Field
Type
Description
ActionStatus
String
Request result. OK: Successful; FAIL: Failed
ErrorCode
Integer
Error code
ErrorInfo
String
Error message
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 represent the actual error code and error message. For public 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 JSON request meets JSON specifications.
90002
The MsgBody field in the JSON request does not meet message format requirements or it is not an array. For more information, see the Message Element TIMMsgElement section in Message Formats.
90005
The MsgRandom field is missing in the JSON request or it is not an integer.
90007
The MsgBody field in the JSON request is not an array. Change it to an array.
90009
The request requires app admin permissions.
90010
The JSON request does not meet message format requirements. For more information, see the Message Element 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 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
API for Pushing to All Users
Setting Application Attribute Names
Getting Application Attribute Names
Setting User Attributes
Deleting User Attributes
Getting User Attributes
Adding User Tags
Getting User Tags
Deleting User Tags
Deleting All Tags of a User

Feature Overview
API Call Description
Error Codes
API Debugging Tool
References

Parameter	Description
https	The request protocol is HTTPS, and the request method is POST.
xxxxxx	Domain name corresponding to the country/region where your SDKAppID is located. Chinese mainland: `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/all_member_push/im_push	Request API
usersig	Signature generated in the app admin account. For more information, see Generating UserSig.
identifier	The app administration account.
sdkappid	The `SDKAppID` assigned by the IM console when an app is created
random	A random 32-bit unsigned integer
contenttype	The value is always `json`.

Field	Type	Attribute	Description
Condition	Object	Optional	Valid values: AttrsOr AttrsAnd TagsOr TagsAnd `AttrsOr` and `AttrsAnd` can coexist, and `TagsOr` and `TagsAnd` can coexist. However, tag conditions and attribute conditions cannot coexist. If no condition is specified, messages are pushed to all users.
MsgRandom	Integer	Required	Random number (32-bit unsigned integer) of the message. It is used by the backend for message deduplication within a second. Make sure a random number is entered.
MsgBody	Array	Required	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	Required	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	Required	Different message object types (`MsgType`) have different formats (`MsgContent`). For more information, see the Message Element TIMMsgElement section in Message Formats.
MsgLifeTime	Integer	Optional	Offline message storage duration, in seconds. The maximum duration is 604,800 seconds (7 days). The default value is 0, which indicates that messages are not stored offline and will be pushed only to online users.
From_Account	String	Optional	Account of the message sender
AttrsOr	Object	Optional	A set of attribute conditions connected by OR. Note that attribute conditions and tag conditions cannot be used at the same time.
AttrsAnd	Object	Optional	A set of attribute conditions connected by AND. Note that attribute conditions and tag conditions cannot be used at the same time.
TagsOr	Array	Optional	Union of tag conditions. A tag is a string of up to 50 bytes. Note that attribute conditions and tag conditions cannot be used at the same time. The `TagsOr` condition can contain up to ten tags.
TagsAnd	Array	Optional	Intersection of tag conditions. A tag is a string of up to 50 bytes. Note that attribute conditions and tag conditions cannot be used at the same time. The `TagsAnd` condition can contain up to ten tags.
OfflinePushInfo	Object	Optional	The information to be pushed offline. For more information, see Message Formats.

Error Code	Description
90001	Failed to parse the JSON format. Check whether the JSON request meets JSON specifications.
90002	The `MsgBody` field in the JSON request does not meet message format requirements or it is not an array. For more information, see the Message Element TIMMsgElement section in Message Formats.
90005	The `MsgRandom` field is missing in the JSON request or it is not an integer.
90007	The `MsgBody` field in the JSON request is not an array. Change it to an array.
90009	The request requires app admin permissions.
90010	The JSON request does not meet message format requirements. For more information, see the Message Element 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 users is not enabled.
90047	The number of pushes exceeds the daily quota (default quota: 100).
91000	Internal service error. Try again.