Querying one-to-one chat messages

Last updated: 2020-10-19 15:23:18

    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.

    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.

    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

    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.

    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

    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.

    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:

    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.

    API Debugging Tool

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

    References

    Was this page helpful?

    Was this page helpful?

    • Not at all
    • Not very helpful
    • Somewhat helpful
    • Very helpful
    • Extremely helpful
    Send Feedback
    Help