下载最新消息

功能说明

App 管理员可以通过该接口获取 App 中最近7天中某天某小时的所有单发或群组消息记录的下载地址。
注意
下载消息记录里的图片、语音、文件和短视频,此功能仅适用于 4.X 及以上版本的 IM SDK,可通过聊天记录中的 URL 字段进行下载。如您使用 2.X 或 3.X 版本的 IM SDK,您将无法通过该方法获取到以上信息,如您需要此功能,请您升级至 4.X 及以上的版本。
消息记录以日志文件形式保存并使用 GZip 压缩,通过该接口获取到下载地址后,请自行下载并处理;消息记录文件按照北京时间每小时产生一次,例如0点(00:00~00:59)的数据在01:00后开始处理,一般1小时内处理完毕(消息较多则处理时间较长);文件有效期7天,无论是否下载过,都会在7天后删除,被删除后不支持重新导出;获取到的下载地址存在有效期,请在过期前进行下载,若地址失效,请通过该接口重新获取。
此接口仅用于下载最近7天的聊天记录文件,用于备份或数据统计等。不建议使用该接口用于线上实时业务。

接口调用说明

请求 URL 示例

https://xxxxxx/v4/open_msg_svc/get_history?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json

请求参数说明

下表仅列出调用本接口时涉及修改的参数及其说明,更多参数详情请参见 REST API 简介
参数
说明
xxxxxx
SDKAppID 所在国家/地区对应的专属域名:
中国:console.tim.qq.com
新加坡:adminapisgp.im.qcloud.com
首尔: adminapikr.im.qcloud.com
法兰克福:adminapiger.im.qcloud.com
硅谷:adminapiusa.im.qcloud.com
雅加达:adminapiidn.im.qcloud.com
v4/open_msg_svc/get_history
请求接口
sdkappid
创建应用时即时通信 IM 控制台分配的 SDKAppID
identifier
必须为 App 管理员账号,更多详情请参见 App 管理员
usersig
App 管理员账号生成的签名,具体操作请参见 生成 UserSig
random
请输入随机的32位无符号整数,取值范围0 - 4294967295
contenttype
请求格式固定值为json

最高调用频率

10次/秒。

请求包示例

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

请求包字段说明

字段
类型
属性
说明
ChatType
String
必填
消息类型,C2C 表示单发消息 Group 表示群组消息
MsgTime
String
必填
需要下载的消息记录的时间段,MsgTime 使用的是北京时间,不支持其他时区。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 在线调试工具 调试本接口。