Querying one-to-one chat messages

Last updated: 2020-05-22 16:33:44

    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.

    Parameter Description
    v4/openim/admin_getroammsg The request API.
    sdkappid The SDKAppID assigned by the IM console when an 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 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

    Field Type Property Description
    From_Account String Required The UserID of either party in the chat. 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 chat.
    MaxCnt Integer Required The number of messages that you want to query.
    MinTime Integer Required The minimum time range of the requested messages.
    MaxTime Integer Required The maximum time range of the requested messages.
    LastMsgKey String Optional The MsgKey of the last message that was pulled previously. This field is required when continued pulling is required. For more information, see the preceding Example.

    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

    Field Type Description
    ActionStatus String The request processing result. OK: succeeded. FAIL: failed.
    ErrorCode Integer The error code. 0: succeeded. Other values: failed.
    ErrorInfo String The error information.
    Complete Integer Indicates whether all messages have been pulled. 0: no, and 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 Integer 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 message body. For more information on the format, see Message Format Description. A message can contain multiple message elements, and MsgBody is of the Array type.
    MsgKey String The message identifier. You can use this parameter in the Recalling One-to-One Messages RESTful API.

    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.

    Error Code Description
    90001 Failed to parse the JSON request packet. Make sure that the request packet meets JSON specifications.
    90003 The JSON request packet body does not contain the To_Account field or the To_Account field is not a String.
    90008 The JSON request packet body 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 occurred. Please try again.

    Commissioning Tool

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

    References

    Was this page helpful?

    Was this page helpful?

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