Querying one-to-one chat messages

Feature Description

• This API is used by the app admin to query the message records of a one-to-one chat based on a specified time range.
• The one-to-one chat to query 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 in the message, respectively.
• In most cases, if you exchange the values of From_Account and to_Account in a request, the query result will remain unchanged. However, to query a message sent through the Sending a One-to-One Message or Batch Sending One-to-One Messages API, if you set SyncOtherMachine to 1, you must specify From_Account and to_Account correctly.
  For example, you have called the Sending a One-to-One Message API to enable account A to send a message to account B and set SyncOtherMachine to 1. When calling this API to query the message records of the one-to-one chat, you must set From_Account to account A and to_Account to account B.
• The query result contains recalled messages, which are indicated by the MsgFlagBits field.
• To recall a message by calling the Recalling One-to-One Messages RESTful API, 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 seven 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.
• For first-time queries, we recommend that you set MaxCnt to 20. In the response, the Complete field indicates whether all messages within the time range have been pulled.

Call Description

Example request URL

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

Request parameters

The following table only describes the parameters that are modified when this API is called. For more information on other parameters, see RESTful API Overview.

Maximum call frequency

200 times/second

Example requests and responses

Returning all data through one request (Continued pulling is not required)

For example, two messages were sent between user1 and user2 within the time range from 2020-03-20 10:00:00 to 2020-03-20 11:00:00 and we want to query the chat history in this time range.

Example request

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

Example response

{
    "ActionStatus":"OK",
    "ErrorInfo":"",
    "ErrorCode": 0,
    "Complete": 1,
    "MsgCnt": 2,
    "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"
                    }
                }
            ]
        },
        {
            "From_Account": "user2",
            "To_Account": "user1",
            "MsgSeq": 1054803289,
            "MsgRandom": 7201,
            "MsgTimeStamp": 1584669689,
            "MsgFlagBits": 0,
            "MsgKey": "1054803289_7201_1584669689",
            "MsgBody": [
                {
                    "MsgType": "TIMTextElem",
                    "MsgContent": {
                        "Text": "2"
                    }
                }
            ]
        }
    ]
}

Return all data through multiple requests (continued pulling is required)

For example, 100 messages were sent between user1 and user2 within the time range from 2020-03-20 10:00:00 to 2020-03-20 11:00:00 and we want to query the chat history in this time range.

Example first request packet

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

Example response

{
    "ActionStatus":"OK",
    "ErrorInfo":"",
    "ErrorCode": 0,
    "Complete": 0,
    "MsgCnt": 17,
    "LastMsgTime": 1584672269,
    "LastMsgKey": "1259_93754093_1584672269",
    "MsgList": [ ... ] //To indicate a continued pulling process, the result of MsgList is not listed.
}

In the response, "Complete": 0 indicates that not all messages generated within the time range have been pulled, and continued pulling is required.
In the continued 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:

Continued pulling request

{
    "From_Account":"user2",
    "To_Account":"user1",
    "MaxCnt":100,
    "MinTime":1584669600,
    "MaxTime":1584672269,
    "LastMsgKey": "1259_93754093_1584672269"
}

Request packet fields

Example response packet body

• Normal response

  {
    "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"
                    }
                }
            ]
        }
    ]
  }

• Exceptional 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 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 table describes the error codes specific to this API.

Commissioning Tool

Use the RESTful API online commissioning tool to commission this API.

References

• Sending a One-to-one Chat Message (v4/openim/sendmsg)
• Batch Sending One-to-one Chat Messages (v4/openim/batchsendmsg)
• Recalling One-to-one Chat Messages (v4/openim/admin_msgwithdraw)