When the server-end integrated RESTful API is used to send messages in batches, you can determine whether to synchronize the messages to the sender (admin account or account specified by the admin). The synchronization methods include online terminals and the roaming server. The RESTful API provides the SyncOtherMachine parameter to determine whether to synchronize the messages. For details, see “Sample request packet”.
https://console.tim.qq.com/v4/openim/batchsendmsg?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json
The following is a list of the parameters commonly used when calling this API and their descriptions. For more parameters, see the RESTful API Overview.
Parameter | Description |
---|---|
v4/openim/batchsendmsg | Request API |
sdkappid | The SDKAppID is assigned by the IM console when the app is created. |
identifier | The value must be the admin account of the app. For more information, see App Admin. |
usersig | The signature generated by the app admin account. For details on the operation, see Generating UserSig. |
random | A random 32-bit unsigned integer ranging from 0 to 4294967295. |
200 times/second
Here, we use sending text messages as an example. To send messages of other types, set MsgBody to the corresponding message type. For details, see Message Format Description.
If you do not want to synchronize messages to From_Account, set SyncOtherMachine to 2.
To synchronize messages to From_Account, set SyncOtherMachine to 1.
{
"SyncOtherMachine": 2, // Messages are not synchronized to the sender.
"To_Account": [ // List of target accounts
"bonnie",
"rong"
],
"MsgRandom": 19901224, // Message random number
"MsgBody": [ // Message
{
"MsgType": "TIMTextElem", // Message type. **TIMTextElem** indicates text messages.
"MsgContent": {
"Text": "hi, beauty" // Message text
}
}
]
}
From_Account is the sender specified by the admin. The recipients will see From_Account instead of the admin account. The following JSON request indicates that dave sends a message to the accounts bonnie and rong. When bonnie and rong receive the message, the message sender they see is dave.
If you do not want to synchronize messages to From_Account, set SyncOtherMachine to 2.
To synchronize messages to From_Account, set SyncOtherMachine to 1.
{
"SyncOtherMachine": 1, // Messages are synchronized to the sender.
"From_Account": "dave",
"To_Account": [
"bonnie",
"rong"
],
"MsgRandom": 19901224,
"MsgBody": [
{
"MsgType": "TIMTextElem",
"MsgContent": {
"Text": "hi, beauty"
}
}
],
"OfflinePushInfo": {
"PushFlag": 0,
"Desc": "Offline push content",
"Ext": "This is the passthrough content",
"AndroidInfo": {
"Sound": "android.mp3"
},
"ApnsInfo": {
"Sound": "apns.mp3",
"BadgeMode": 1, // The default value is 0, indicating that a message is counted. The value 1 indicates that the message is not counted, that is, the icon number in the upper right corner does not increase by one.
"Title":"apns title", // apns title
"SubTitle":"apns subtitle", // apns subtitle
"Image":"www.image.com" // image url
}
}
}
Field | Type | Attribute | Description |
---|---|---|---|
SyncOtherMachine | Integer | Optional | 1: messages are synchronized to the From_Account online terminals and roaming server. 2: messages are not synchronized to From_Account. If this parameter is not specified, messages are synchronized to the From_Account roaming server by default. |
From_Account | String | Optional | Sender account specified by the admin for sending messages. (To set From_Account information, this parameter must be specified.) |
To_Account | Array | Required | UserID of a message recipient |
MsgRandom | Integer | Required | Message random number, which is generated by the random function and used to locate issues at the backend |
MsgBody | Object | Required | TIM message. For details, see Message Format Description. |
MsgType | String | Required | TIM message object type. Supported message objects include TIMTextElem (text messages), TIMFaceElem (emoji messages), TIMLocationElem (location messages), and TIMCustomElem (custom messages). |
MsgContent | Object | Required | TIM message object. For details, see Message Format Description. |
OfflinePushInfo | Object | Optional | Offline push information configuration. For details, see Message Format Description. |
Successful response packet
{
"ErrorInfo": "",
"ActionStatus": "OK",
"ErrorCode": 0,
"MsgKey": "128493_903762_1572870301"
}
Error response packet
{
"ActionStatus": "FAIL",
"ErrorInfo": "",
"ErrorList": [ // List of target accounts to which messages failed to be sent
{
"To_Account": "rong", // Target account
"ErrorCode": 90011 // Error code
}
]
}
Field | Type | Description |
---|---|---|
ActionStatus | String | The request processing result. OK: succeeded. FAIL: failed. |
ErrorList | Array | List of target accounts to which messages failed to be sent. If all messages are sent successfully, ErrorList is null. To determine whether all messages were sent successfully, check whether ErrorList is contained in the response packet. |
To_Account | String | Accounts to which messages failed to be sent |
ErrorCode | Number | Error code for a message sending failure |
MsgKey | String | The unique message identifier, which is used to cancel a message. It is a string of up to 50 characters. |
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 packet represent the actual error code and error information.
For public error codes (60000 to 79999), see Error Codes.
The following are error codes specific to this API:
Error code | Description |
---|---|
70107 | The requested UserID does not exist. |
70169 | Server timed out. Try again later. |
90001 | Failed to parse the JSON format. Check whether the JSON request packet meets JSON specifications. |
90002 | Invalid MsgBody format or MsgBody is not an Array. See TIMMsgElement Object. |
90007 | The MsgBody field in the JSON request packet is not of the Array type. Change the type of the MsgBody field to Array. |
90008 | The JSON request packet does not contain the From_Account field or From_Account does not exist. |
90009 | The request requires app admin permissions. |
90010 | The JSON request packet does not meet message format requirements. For details, see the definition of TIMMsgElement Object. |
90011 | The number of target accounts for batch message sending exceeds 500. Please decrease the value of the To_Account field. |
90012 | To_Account is not registered or does not exist. Check whether To_Account has been imported into the IM console or is incorrectly spelled. |
90026 | Invalid message offline storage time. Messages cannot be stored offline for more than 7 days. |
90048 | The requested UserID does not exist. |
90992 | Internal server error. Please try again. If this error code is returned for all requests and the app has configured third-party callback, check whether the app server sends the callback result to the IM backend server normally. |
91000 | Internal server error. Please try again. |
93000 | The JSON packet exceeds the length limit of 8 KB. |
Use the RESTful API online debugging tool to debug this API.
Was this page helpful?