Downloading the Latest Message History

Last updated: 2020-07-07 18:23:49

    Feature Description

    The app admin can use this API to obtain the download addresses for all one-to-one or group message records in the app that occur at a specified point in time for the last 7 days.

    • Downloads images, audio, files, and videos from message records. This feature is only applicable to IM SDK 4.X. The download can be performed based on the URL fields in chat records. If you are using IM SDK 2.X or 3.X, you cannot obtain the preceding information in this method. If you need this feature, upgrade your IM SDK to version 4.X.
    • Stores message records as logs and compresses them by using GZip. After obtaining the download addresses through the API, you can download and process the message records yourself. Message record files are generated every hour. For example, the data generated at midnight (00:00-00:59) will be processed from 01:00. Typically, the data can be processed within one hour. However, if the message quantity is large, it will take longer to process them. The message record files are valid for only seven days and will be deleted after seven days regardless of the download status. The deleted record cannot be exported again.
    • This API is used only to download historical chat records for the last 7 days, for backup, statistics, or other purposes. We do not recommend that you use it for real-time online businesses.

    API Invocation Description

    Request URL example

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

    Request parameters

    The following table only describes parameters that are modified when this API is invoked. For details on other parameters, see RESTful API Overview.

    Parameter Description
    v4/open_msg_svc/get_history Request API
    sdkappid SDKAppID assigned by the IM console when an app is created
    identifier The value of this parameter must be an app admin account. For details, see App Admins.
    usersig The signature generated by the app admin account. For details on the operation, see Generating UserSig.
    random A random 32-bit unsigned integer ranging from 0 to 4294967295

    Maximum invocation frequency

    The maximum invocation frequency is 10 times per second.

    Request packet example

    {
        "ChatType": "C2C",
        "MsgTime": "2015120121"
    }

    Request packet fields

    Field Type Attribute Description
    ChatType String Required The message type. C2C indicates a one-to-one message, whereas Group indicates a group message.
    MsgTime String Required The period for downloading message records. For example, 2015120121 indicates that messages in the period of 21:00 to 21:59 on December 1, 2015 will be downloaded. This field needs to be accurate to the hour. Each request can only be used to obtain all one-to-one or group message records that occur at the specified hour on the specific day.

    Response packet example

    {
        "File": [
            {
                "URL": "https://download.tim.qq.com/msg_history/2/9b8f8f063b73f61698ce11e58207e89ade40.gz",
                "ExpireTime": "2015-12-02 16:45:23",
                "FileSize": 65207,
                "FileMD5": "cceece008bb7f469a47cf8c4b7acb84e",
                "GzipSize": 1815,
                "GzipMD5": "c3a0269dde393fd7a8bb18bfdeaeee2e"
            }
        ],
        "ActionStatus": "OK",
        "ErrorInfo": "",
        "ErrorCode": 0
    }

    Response packet fields

    Field Type Description
    ActionStatus String The request processing result. OK: succeeded. FAIL: failed.
    ErrorCode Integer The error code. 0: succeed. Others: failed.
    ErrorInfo String Error information
    File Array Download information for message record files
    URL String Download address of message record files
    ExpireTime String The expiry time of the download address. Always download files before the address expires. If the address expires, obtain a new address through the API.
    FileSize Integer File size before GZip compression (in bytes)
    FileMD5 String MD5 code of the file before GZip compression
    GzipSize Integer File size after GZip compression (in bytes)
    GzipMD5 String MD5 code of the file after GZip compression

    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, respectively.
    For common error codes (60000 to 79999), see Error Codes.
    Private error codes for this API are as follows:

    Error Code Description
    1001 The request is invalid. In this case, check whether "Request URL" is correct.
    1002 A parameter is invalid. In this case, check whether the account is an admin account, whether required fields are specified, and whether the specified fields meet protocol requirements.
    1003 A system error has occurred.
    1004 The file has not been generated, or no messages can be found in the requested period.
    1005 The file has expired.

    Format of Message Record Files

    //For one-to-one messages
    {"SdkAppId":1104620500,"ChatType":"C2C","MsgTime":"2015120121","MsgList":[
    {"From_Account":"peakerdong","To_Account":"qiyueliuhuo2018","MsgTimestamp":1448974806,"MsgSeq":3452069198,"MsgRandom":45838,"MsgBody":[{"MsgType":"TIMTextElem","MsgContent":{"Text":"Quartering"}}]},
    {"From_Account":"group_root","To_Account":"group_test4","MsgTimestamp":1448974808,"MsgSeq":462709847,"MsgRandom":19196437,"MsgBody":[{"MsgType":"TIMTextElem","MsgContent":{"Text":"hi, beauty"}}]}
    ]}
    
    //For group messages
    {"SdkAppId":1104620500,"ChatType":"Group","MsgTime":"2015120121","MsgList":[
    {"From_Account":"Test_1","GroupId":"@TGS#1FDFVPAE2","MsgTimestamp":1448975384,"MsgSeq":1,"MsgBody":[{"MsgType":"TIMTextElem","MsgContent":{"Text":"Private activate"}}]},
    {"From_Account":"Test_1","GroupId":"@TGS#1FDFVPAE2","MsgTimestamp":1448975384,"MsgSeq":1,"MsgBody":[{"MsgType":"TIMTextElem","MsgContent":{"Text":"Private activate"}}]}
    ]}

    The first line of the file records basic information about the file. Each following line records a message until the last line that ends with "]}". For the format of each message, see the definitions in TIMMsgElement Objects.
    If the file is small, you can use the JSON database to parse the entire file. MsgList indicates the message array for the specified period. For example:

    # Python Example Code
    import gzip, json
    with gzip.open('1104620500_Group_2015120121.gz', 'rb') as fp:
        info = json.load(fp)
    for msg in info['MsgList']:
        pass #do sth with msg

    If the file is large, we recommend that you parse it line by line. For example:

    # Python Example Code
    import gzip, json
    with gzip.open('1104620500_Group_2015120121.gz', 'rb') as fp:
        cnt = -1
        for line in fp:
            line = line.strip().rstrip(b',')
            if line == b']}': break
            if cnt < 0:
                info = json.loads(line + b']}')
            else:
                msg = json.loads(line)
                #do sth with msg
            cnt += 1

    API Commissioning Tool

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

    Was this page helpful?

    Was this page helpful?

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