Overview

• This API is used by the app admin to query the history of a one-to-one chat based on a specified time range.
• The one-to-one chat to be queried is specified by From_Account and To_Account in the request. The query result contains the messages sent between both sides. The specific sender and recipient of each message are specified by From_Account and To_Account, respectively.
• In most cases, if you exchange the values of From_Account and To_Account in the request, the query result will remain unchanged. However, to query a message sent through the API for sending a one-to-one message or batch sending one-to-one messages, if you set SyncOtherMachine to 2, you must specify From_Account and To_Account correctly.
  For example, call the API for sending a one-to-one message to enable account A to send a message to account B and set SyncOtherMachine to 2. When calling this API to query the message history of the one-to-one chat, you must set From_Account to account B and To_Account to account A.
• The query result contains recalled messages indicated by the MsgFlagBits field.
• If you want to recall a message by calling the RESTful API for recalling one-to-one messages, you can first call this API to query the MsgKey of the message and then call the recall API to recall the message.
• The time range of message records that can be queried depends on the roaming message storage period, which is 7 days by default. You can modify the message roaming period in the IM console. Extending the message roaming period is a value-added service. For more information, see Roaming Message Storage.
• If the total size of the messages within the requested time range exceeds the maximum size limit of the response packet (currently 13 KB), continued pulling is needed. You can check whether all the requested messages have been pulled based on the Complete field in the response.

API Call Description

Sample request URL

https://console.tim.qq.com/v4/openim/admin_getroammsg?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json

Request parameters

The list below contains only the parameters commonly used when calling this API and their descriptions. For more parameters, see the RESTful API Overview.

Maximum call frequency

200 calls per second

Sample requests and responses

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.

Sample request

{
    "From_Account":"user2",
    "To_Account":"user1",
    "MaxCnt":100,
    "MinTime":1584669600,
    "MaxTime":1584673200
}

Sample response

{
    "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:

Sample continued pulling request

{
    "From_Account":"user2",
    "To_Account":"user1",
    "MaxCnt":100,
    "MinTime":1584669600,
    "MaxTime":1584669680,
    "LastMsgKey": "549396494_2578554_1584669680"
}

Sample response

{
    "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.

Request packet fields

Sample response packets

• 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
  }

Response packet fields

Error Codes

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:

API Debugging Tool

To debug this API, you can use the Online RESTful API Debugging Tool.

References

• Sending a one-to-one message (v4/openim/sendmsg)
• Batch sending one-to-one messages (v4/openim/batchsendmsg)
• Recalling one-to-one messages (v4/openim/admin_msgwithdraw)