From_Account
and To_Account
in the request. The query result contains the messages sent between both parties. The specific sender and recipient of each message are specified by From_Account
and To_Account
respectively.From_Account
and To_Account
in the request, the query result will remain unchanged. However, to query a message sent via the v4/openim/sendmsg API or v4/openim/batchsendmsg API, if you set SyncOtherMachine
to 2
, you must specify From_Account
and To_Account
correctly.SyncOtherMachine
to 2
. To query the message by calling this API, you must set From_Account
to account B and To_Account
to account A.MsgFlagBits
field.MsgKey
of the message and then call the v4/openim/admin_msgwithdraw API to recall the message.Complete
field in the response.https://xxxxxx/v4/openim/admin_getroammsg?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json
The following table only describes the modified parameters when this API is called. For more information on other parameters, please see RESTful API Overview.
Parameter | Description |
---|---|
https | The request protocol is HTTPS, and the request method is POST. |
xxxxxx | The country/region where your SDKAppID is located.console.tim.qq.com adminapisgp.im.qcloud.com adminapikr.im.qcloud.com adminapiger.im.qcloud.com adminapiind.im.qcloud.com |
v4/openim/admin_getroammsg | Request API |
sdkappid | SDKAppID assigned by the IM console when an app is created |
identifier | App admin account. For more information, please see the App Admin section in Login Authentication. |
usersig | Signature generated in the app admin account. For details on how to generate the signature, please see Generating UserSig. |
random | A random 32-bit unsigned integer ranging from 0 to 4294967295 |
contenttype | Request format. The value is always json . |
200 calls per second
For example, user1
and user2
had a conversation, and you want to query the conversation history 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 the 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"
}
}
],
"CloudCustomData": "your cloud custom data"
},
{
"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"
}
}
],
"CloudCustomData": "your cloud custom data"
},
{ ... } // The remaining 10 messages are not listed for simplicity.
]
}
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 continued pulling request, the value of MaxTime
must be changed to the value of LastMsgTime
in the response, and the LastMsgKey
in the response must be entered, 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, // Five messages were returned for the 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"
}
}
],
"CloudCustomData": "your cloud custom data"
},
{
"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"
}
}
],
"CloudCustomData": "your cloud custom data"
},
{ ... } // The remaining three messages are not listed for simplicity.
]
}
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 | Yes | UserID of either party in the conversation. If the message sender account has been specified, this field indicates the sender. |
To_Account | String | Yes | UserID of the other party in the conversation |
MaxCnt | Integer | Yes | Number of messages to query |
MinTime | Integer | Yes | Minimum value of the time range of the messages to query |
MaxTime | Integer | Yes | Maximum value of the time range of the messages to query |
LastMsgKey | String | No | MsgKey of the last message that was pulled previously. This field is required for continued pulling. For more information, see the preceding sample. |
Response to a successful request
{
"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"
}
}
],
"CloudCustomData": "your cloud custom data"
}
]
}
Response to a failed request
{
"ActionStatus": "FAIL",
"ErrorInfo": "Fail to Parse json data of body, Please check it",
"ErrorCode": 90001
}
Field | Type | Description |
---|---|---|
ActionStatus | String | Request result. OK : successful; FAIL : failed |
ErrorCode | Integer | Error code. 0 : successful; other values: failed |
ErrorInfo | String | Error information |
Complete | Integer | Whether all messages have been pulled. 0 : no, continued pulling is required; 1 : yes |
MsgCnt | Integer | Number of messages that were pulled this time |
LastMsgTime | Integer | Time when the last message was pulled this time |
LastMsgKey | String | Identifier of the last message pulled this time |
MsgList | Array | List of returned messages |
MsgFlagBits | Integer | Message attribute. 0 : normal message; 8 : recalled message |
MsgBody | Array | Message body. For details on formats, please see Message Formats. (Note: a message can contain multiple message elements, in which case MsgBody is an array.) |
CloudCustomData | String | Custom message data. It is saved in the cloud and will be sent to the peer end. Such data can be pulled after the app is uninstalled and reinstalled. |
MsgKey | String | Message identifier. You can use this field when calling the v4/openim/admin_msgwithdraw API to recall this message. |
The returned HTTP status code for this API is always 200 unless a network error (such as error 502) occurs. The specific error code and details can be found in the response fields ErrorCode
and ErrorInfo
respectively.
For public error codes (60000 to 79999), please see Error Codes.
The following table describes the error codes specific to this API:
Error Code | Description |
---|---|
90001 | Failed to parse the JSON request. Make sure the format is valid. |
90003 | The To_Account field is missing in the JSON request or it is not a string. |
90008 | The From_Account field is missing in the JSON request or the account it specifies does not exist. |
90009 | The request requires app admin permissions. |
91000 | Internal service error. Try again. |
Use the RESTful API online debugging tool to debug this API.
Was this page helpful?