下载消息记录

最近更新时间:2019-08-02 18:40:21

功能说明

App 管理员可以通过该接口获取 App 中某天某小时的所有单发或群组消息记录的下载地址。

注意:

  1. 下载消息记录里的图片、语音、文件和短视频,此功能仅适用于4.X 版本 IM SDK,可通过聊天记录中的 URL 字段进行下载。如您使用 2.X 或 3.X 版本的 IM SDK,您将无法通过该方法获取到以上信息,如您需要此功能,请您升级至 4.X 版本;
  2. 消息记录以日志文件形式保存并使用 GZip 压缩,通过该接口获取到下载地址后,请自行下载并处理;消息记录文件每小时产生一次,例如 0 点(00:00~00:59)的数据在 01:00 后开始处理,一般 1 小时内处理完毕(消息较多则处理时间较长);文件有效期 3 天,无论是否下载过,都会在 3 天后删除;获取到的下载地址存在有效期,请在过期前进行下载,若地址失效,请通过该接口重新获取。

接口调用说明

请求 URL 示例

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

请求参数说明

下表仅列出调用本接口时涉及修改的参数及其说明,更多参数详情请参考 REST API 简介

参数 说明
v4/open_msg_svc/get_history 请求接口
sdkappid 创建应用时即时通信 IM 控制台分配的 SDKAppID
identifier 必须为 App 管理员帐号,更多详情请参见 App 管理员
usersig App 管理员帐号生成的签名,具体操作请参见 生成 UserSig
random 请输入随机的32位无符号整数

最高调用频率

100次/秒。如需提升调用频率,请根据 工单模板 提交工单申请处理。

请求包示例

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

请求包字段说明

字段 类型 属性 说明
ChatType String 必填 消息类型,C2C 表示单发消息 Group 表示群组消息
MsgTime String 必填 需要下载的消息记录的时间段,2015120121表示获取2015年12月1日21:00 - 21:59的消息的下载地址

应答包体示例

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

应答包字段说明

字段 类型 说明
ActionStatus String 请求处理的结果,“OK” 表示处理成功,“FAIL” 表示失败
ErrorCode Integer 错误码,0表示成功,非0表示失败
ErrorInfo String 错误信息
File Array 消息记录文件下载信息
URL String 消息记录文件下载地址
ExpireTime String 下载地址过期时间,请在过期前进行下载,若地址失效,请通过该接口重新获取
FileSize Integer GZip 压缩前的文件大小(单位 Byte)
FileMD5 String GZip 压缩前的文件 MD5
GzipSize Integer GZip 压缩后的文件大小(单位 Byte)
GzipMD5 String GZip 压缩后的文件 MD5

错误码说明

除非发生网络错误(例如502错误),否则该接口的 HTTP 返回码均为200。真正的错误码,错误信息是通过应答包体中的 ErrorCode、ErrorInfo 来表示的。
公共错误码(60000到79999)参见 错误码 文档。
本 API 私有错误码如下:

错误码 含义说明
1001 请求非法;请检查“请求 URL”是否正确
1002 参数非法;请检查是否管理员帐号,必填字段是否填充,或者字段的填充是否满足协议要求
1003 系统错误
1004 文件尚未生成,或者请求时段内没有消息
1005 文件已过期

消息记录文件格式

//单发消息
{"SdkAppId":1104620500,"ChatType":"C2C","MsgTime":"2015120121","MsgList":[
{"From_Account":"peakerdong","To_Account":"qiyueliuhuo2018","MsgTimestamp":1448974806,"MsgSeq":3452069198,"MsgRandom":45838,"MsgBody":[{"MsgType":"TIMTextElem","MsgContent":{"Text":"四等分"}}]},
{"From_Account":"group_root","To_Account":"group_test4","MsgTimestamp":1448974808,"MsgSeq":462709847,"MsgRandom":19196437,"MsgBody":[{"MsgType":"TIMTextElem","MsgContent":{"Text":"hi, beauty"}}]}
]}

//群组消息
{"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"}}]}
]}

文件第一行记录了该文件的基本信息,接下来的每一行记录一条消息,直到最后一行“]}”结束,每条消息格式可参考 TIMMsgElement对象 的定义;
若文件较小,可直接使用 JSON 库解析整个文件,MsgList 是该时段的消息数组。例如 :

# Python 示例代码
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

若文件较大,建议逐行解析。例如 :

# Python 示例代码
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

接口调试工具

通过 REST API 在线调试工具 调试本接口。