https://console.tim.qq.com/v4/openim/admin_getroammsg?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json
The list below contains only the parameters commonly used when calling this API and their descriptions. For more parameters, see the RESTful API Overview.
Parameter | Description |
---|---|
v4/openim/admin_getroammsg | The request API that is 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
For example, user1 and user2 had a chat, and we want to query the chat history generated within the time range from 2020-03-20 10:00:00 to 2020-03-20 11:00:00.
{
"From_Account":"user2",
"To_Account":"user1",
"MaxCnt":100,
"MinTime":1584669600,
"MaxTime":1584673200
}
{
"ActionStatus":"OK",
"ErrorInfo":"",
"ErrorCode": 0,
"Complete": 0,
"MsgCnt": 12, //12 messages were returned for this pull.
"LastMsgTime": 1584669680,
"LastMsgKey": "549396494_2578554_1584669680",
"MsgList": [
{
"From_Account": "user1",
"To_Account": "user2",
"MsgSeq": 549396494,
"MsgRandom": 2578554,
"MsgTimeStamp": 1584669680,
"MsgFlagBits": 0,
"MsgKey": "549396494_2578554_1584669680",
"MsgBody": [
{
"MsgType": "TIMTextElem",
"MsgContent": {
"Text": "msg 1"
}
}
]
},
{
"From_Account": "user2",
"To_Account": "user1",
"MsgSeq": 1054803289,
"MsgRandom": 7201,
"MsgTimeStamp": 1584669689,
"MsgFlagBits": 0,
"MsgKey": "1054803289_7201_1584669689",
"MsgBody": [
{
"MsgType": "TIMTextElem",
"MsgContent": {
"Text": "msg 2"
}
}
]
},
{ ... } //To save space, the remaining 10 messages are not listed here.
]
}
In the response, "Complete": 0
indicates that not all messages generated within the time range have been pulled. Therefore, continued pulling is required.
In the subsequent pulling request, the value of MaxTime must be changed to the value of the LastMsgTime field in the response, and the LastMsgKey field in the response must be specified, as shown below:
{
"From_Account":"user2",
"To_Account":"user1",
"MaxCnt":100,
"MinTime":1584669600,
"MaxTime":1584669680,
"LastMsgKey": "549396494_2578554_1584669680"
}
{
"ActionStatus":"OK",
"ErrorInfo":"",
"ErrorCode": 0,
"Complete": 1,
"MsgCnt": 5, //5 messages were returned for this pull.
"LastMsgTime": 1584669601,
"LastMsgKey": "1456_23287_1584669601",
"MsgList": [
{
"From_Account": "user1",
"To_Account": "user2",
"MsgSeq": 1456,
"MsgRandom": 23287,
"MsgTimeStamp": 1584669601,
"MsgFlagBits": 0,
"MsgKey": "1456_23287_1584669601",
"MsgBody": [
{
"MsgType": "TIMTextElem",
"MsgContent": {
"Text": "msg 13"
}
}
]
},
{
"From_Account": "user2",
"To_Account": "user1",
"MsgSeq": 9806,
"MsgRandom": 14,
"MsgTimeStamp": 1584669602,
"MsgFlagBits": 0,
"MsgKey": "9806_14_1584669602",
"MsgBody": [
{
"MsgType": "TIMTextElem",
"MsgContent": {
"Text": "msg 14"
}
}
]
},
{ ... } //To save space, the remaining 3 messages are not listed here.
]
}
In the response, "Complete": 1
indicates that all messages generated within the time range have been pulled.
If the value of Complete in the response is 0, you need to continue pulling messages until the value of Complete becomes 1.
Field | Type | Required | Description |
---|---|---|---|
From_Account | String | Required | The UserID of either party in the conversation. If the message sender account has been specified, this parameter indicates the message sender. |
To_Account | String | Required | The UserID of either party in the conversation. |
MaxCnt | Integer | Required | The number of messages that you want to query. |
MinTime | Integer | Required | The minimum value of the time range of the requested messages. |
MaxTime | Integer | Required | The maximum value of the time range of the requested messages. |
LastMsgKey | String | Optional | The MsgKey of the last message that was pulled previously. This field is required when you enable continued pulling. For more information, see the preceding Example. |
Response to a successful recall
{
"ActionStatus":"OK",
"ErrorInfo":"",
"ErrorCode": 0,
"Complete": 1,
"MsgCnt": 1,
"LastMsgTime": 1584669680,
"LastMsgKey": "549396494_2578554_1584669680",
"MsgList": [
{
"From_Account": "user1",
"To_Account": "user2",
"MsgSeq": 549396494,
"MsgRandom": 2578554,
"MsgTimeStamp": 1584669680,
"MsgFlagBits": 0,
"MsgKey": "549396494_2578554_1584669680",
"MsgBody": [
{
"MsgType": "TIMTextElem",
"MsgContent": {
"Text": "1"
}
}
]
}
]
}
Abnormal response
{
"ActionStatus": "FAIL",
"ErrorInfo": "Fail to Parse json data of body, Please check it",
"ErrorCode": 90001
}
Field | Type | Description |
---|---|---|
ActionStatus | String | The result the request. OK means the request was successful. FAIL means the request failed. |
ErrorCode | Integer | Error code. 0 means the request was successful. Any non-zero value means the request failed. |
ErrorInfo | String | Detailed information on the error. |
Complete | Integer | Indicates whether all messages have been pulled. 0: no, continued pulling is required. 1: yes. |
MsgCnt | Integer | The number of messages that were pulled this time. |
LastMsgTime | Integer | The time when the last message was pulled this time. |
LastMsgKey | String | The identifier of the last message that was pulled this time. |
MsgList | Array | The list of returned messages. |
MsgFlagBits | Integer | The property of the message. 0: normal message. 8: recalled message. |
MsgBody | Object | The body of the message. For more information on the format, see Message Format Description. Note: a message can contain multiple message elements, in which case the value of MsgBody is of the Array type. |
MsgKey | String | The identifier of the message. You can use this parameter when Recalling one-to-one messages by using a RESTful API. |
Unless a network error (such as error 502) occurs, the returned HTTP status code for this API is always 200. The specific error code and details can be found in the response fields such as ResultCode
, ResultInfo
.
For public error codes (60000 to 79999), see Error Codes.
The list below contains only error codes specific to this API:
Error Code | Description |
---|---|
90001 | Failed to parse the JSON request packet. Make sure the format of the request is valid. |
90003 | The To_Account field is missing in the JSON request packet or To_Account is not a string. |
90008 | The JSON request packet does not contain the From_Account field or the account specified by the From_Account field does not exist. |
90009 | The request requires the app admin’s permissions. |
91000 | An internal service error occurs. Please try again. |
To debug this API, you can use the Online RESTful API Debugging Tool.
Was this page helpful?