Note:
When the server uses this RESTful API to send one-to-one messages, you can choose whether to synchronize the messages to the sender (admin account or the 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 packets”.
https://console.tim.qq.com/v4/openim/sendmsg?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json
The following table lists and describes only the parameters to be modified when this API is called. For more parameters, see the RESTful API Overview.
Parameter | Description |
---|---|
v4/openim/sendmsg | The request API used. |
sdkappid | The SDKAppID assigned via the IM console when the application is created. |
identifier | The value must be the app admin account. For more information, see App Admin. |
usersig | The signature generated by the app admin account. For more information on the operation, see Generating UserSig. |
random | A random 32-bit unsigned integer ranging from 0 to 4294967295. |
200 calls per 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.
Note:
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, // Do not synchronize messages to the sender.
"To_Account": "lumotuwe2",
"MsgLifeTime":60, // Messages are retained for 60 seconds.
"MsgRandom": 1287657,
"MsgTimeStamp": 1557387418,
"MsgBody": [
{
"MsgType": "TIMTextElem",
"MsgContent": {
"Text": "hi, beauty"
}
}
]
}
Note:
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, // Do not synchronize messages to the sender.
"To_Account": "lumotuwe2",
"MsgLifeTime":60, // Messages are retained for 60 seconds.
"MsgRandom": 1287657,
"MsgTimeStamp": 1557387418,
"ForbidCallbackControl":[
"ForbidBeforeSendMsgCallback",
"ForbidAfterSendMsgCallback"], // Callback forbidding control options
"MsgBody": [
{
"MsgType": "TIMTextElem",
"MsgContent": {
"Text": "hi, beauty"
}
}
]
}
Note:
If you do not want to synchronize messages to From_Account, set SyncOtherMachine to 2.
{
"SyncOtherMachine": 2,
"From_Account": "lumotuwe1",
"To_Account": "lumotuwe2",
"MsgLifeTime":3600, // Messages are retained for one hour.
"MsgRandom": 1287657,
"MsgTimeStamp": 1557387418,
"MsgBody": [
{
"MsgType": "TIMTextElem",
"MsgContent": {
"Text": "hi, beauty"
}
}
],
"OfflinePushInfo": {
"PushFlag": 0,
"Desc": "The content that is pushed offline",
"Ext": "The passthrough content",
"AndroidInfo": {
"Sound": "android.mp3"
},
"ApnsInfo": {
"Sound": "apns.mp3",
"BadgeMode": 1, // If this parameter is not specified or is set to 0, the message is counted. If this parameter is set to 1, the message is not counted, that is, the icon number in the upper-right corner does not increase by 1.
"Title":"apns title", // apns title
"SubTitle":"apns subtitle", // apns subtitle
"Image":"www.image.com" // image url
}
}
}
Note:
To synchronize messages to From_Account, set SyncOtherMachine to 1.
{
"SyncOtherMachine": 1, // Synchronize messages to the sender.
"From_Account": "lumotuwe1",
"To_Account": "lumotuwe2",
"MsgRandom": 1287657,
"MsgTimeStamp": 1557387418,
"MsgBody": [
{
"MsgType": "TIMTextElem",
"MsgContent": {
"Text": "hi, beauty"
}
}
]
}
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 | UserID of the sender (used to specify the sender’s account) |
To_Account | String | Required | UserID of the recipient |
MsgLifeTime | Integer | Optional | The retention period of offline message (in seconds); max period: 7 days (604,800 seconds) |
MsgRandom | Integer | Required | The message random number, which is generated by the random function and used to locate issues at the backend |
MsgTimeStamp | Integer | Optional | Message timestamp in UNIX format (unit: second). |
ForbidCallbackControl | Array | Optional | Message callback forbidding switch, valid only for a single message. ForbidBeforeSendMsgCallback forbids the callback before sending message; ForbidAfterSendMsgCallback forbids the callback after sending messages. |
MsgBody | Object | Required | Message body. For more information on the format, see Message Format Description (note: a message can contain multiple message elements, wherein MsgBody is of the Array type). |
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 | Different message types have different MsgContent formats. For details, see Message Format Description. |
OfflinePushInfo | Object | Optional | Offline push information configuration. For details, see Message Format Description. |
Normal response
{
"ActionStatus":"OK",
"ErrorInfo":"",
"ErrorCode": 0,
"MsgTime": 1497238162,
"MsgKey": "89541_2574206_1572870301"
}
Exceptional response
{
"ActionStatus": "FAIL",
"ErrorInfo": "Fail to Parse json data of body, Please check it",
"ErrorCode": 90001
}
Field | Type | Description |
---|---|---|
ActionStatus | String | The processing result of the request. OK: succeeded. FAIL: failed. |
ErrorCode | Integer | The error code. 0: succeeded. Other values: failed. |
ErrorInfo | String | Error information. |
MsgTime | Integer | Message timestamp in the UNIX format. |
MsgKey | String | The unique identifier of the message. This parameter is used to recall a message. The value 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 indicate the actual error code and error information, respectively.
For public error codes (60000 to 79999), see Error Codes.
The list below contains only error codes specific to this API:
Error Code | Description |
---|---|
20001 | Invalid request packet |
20002 | Invalid UserSig or A2 |
20003 | The UserID of the sender or the recipient is invalid or does not exist. Check whether the UserID has been imported into the IM console. |
20004 | Network exception. Try again later. |
20005 | Internal server error. Try again later. |
20006 | The callback prior to sending a one-to-one chat message was triggered, and the App backend returned a response to forbid the message. |
90001 | Failed to parse the JSON format. Check whether the request packet meets JSON specifications. |
90002 | The format of the MsgBody field in the JSON request packet is invalid or MsgBody is not an array. Refer to TIMMsgElement Object. |
90003 | The JSON request packet does not contain the To_Account field or the To_Account field is not of the String type. |
90005 | The JSON request packet does not contain the MsgRandom field or the MsgRandom field is not of the Integer type. |
90006 | The MsgTimeStamp field in the JSON request packet is not of the Integer type. |
90007 | The MsgBody field in the JSON request packet is not of the Array type. Change the type of the MsgBody field to Array. |
90009 | The request requires app admin permissions. |
90010 | The JSON request packet’s format is invalid. Refer to TIMMsgElement Object for more information. |
90012 | Accounts in To_Account do not exist or have not been registered. Make sure the accounts are IM accounts and are correct. |
90026 | The offline storage time of the message is incorrect. Messages cannot be stored offline for more than 7 days. |
90031 | The SyncOtherMachine field in the JSON request packet is not of the Integer type. |
90044 | The MsgLifeTime field in the JSON request packet is not of the Integer type. |
91000 | Internal service error. Please try again. |
90992 | Internal service error. Please try again. If this error code is returned for all requests and the app has configured a third-party callback, check whether the app server sends the callback result to the IM backend server normally. |
93000 | The JSON data packet exceeds the length limit of 8 KB. |
90048 | The requested account does not exist. |
Use the online RESTful API debugging tool to debug this API.
Batch sending one-to-one messages (v4/openim/batchsendmsg)
Querying one-to-one messages (v4/openim/admin_getroammsg)
Recalling one-to-one messages (v4/openim/admin_msgwithdraw)
Was this page helpful?