获取历史消息日志
融云即时通讯(IM)服务端可以保存应用内所有会话的历史消息记录,历史消息记录以日志文件方式提供,并已经过压缩。您可以使用服务端 API 获取指定应用的历史消息日志。
此接口仅返回消息记录文件的下载地址,获取地址后请您自行下载。
开通服务
使用获取历史消息日志功能前,请确认已为当前 App Key 开通服务。详见消息管理服务配置。
如未开通服务,服务端 API 将返回 1009
错误。注意,在未开通服务时,如果连续请求导致 API 请求频率超过限制,服务端 API 会返回 HTTP 429 Too Many Requests 错误(错误码为 1008
)。
可获取日志的时间范围
历史消息日志中包含以下会话类型的消息数据:单聊、讨论组、群组、超级群、聊天室、客服和系统通知。
在控制台开通历史消息日志下载服务后,服务端会立即开始保存当前小时的消息日志数据。例如,您在 10:00~11:00 之间开通服务,融云 IM 服务端可提供从 10:00 开始的历史消息日志。
提示
- IM 服务端每小时打包一次历史消息日志数据,仅支持按小时获取。详见 API 接口的
date
参数说明。 - 获取数据有一定延迟。10:00~11:00 的数据文件在 11:00 之后才能生成。因文件压缩打包等原因,通常在 1 小时内(即 12:00 前)可获取到下载地址。
- 获取的历史消息日志为指定时间段内所有会话的全量日志;此接口不支持按用户或按会话获取。
日志保存时限
服务端保存的消息记录日志文件仅保留 3 天,3 天后将自动删 除。
如需获取图片、视频等文件信息,可通过消息中的地址进行下载。如果文件保存在融云 IM 服务端,文件存储有效期为 6 个月。
您也可以通过 IM 服务端 API 主动删除历史消息日志。接口返回成功后,日志文件将在 10 分钟内被永久删除。详见删除历史消息日志。
日志格式
名称 | 类型 | 说明 |
---|---|---|
appId | String | App Key。 |
fromUserId | String | 发送者用户 ID。 |
targetId | String | 接收者用户 ID,在消息路由中为 toUserId ,当发送聊天室广播消息、全量用户落地通知时此字段为空。 |
targetType | Int | 会话类型:1 (单聊会话)、2 (讨论组会话)、3 (群组会话)、4 (聊天室会话)、5 (客服会话)、6 (系统通知)、7 (应用公众服务)、8 (公众服务)、10 (超级群会话)。targetType 在 SDK 中为 ConversationType 。 |
GroupId | String | 根据不同的 targetType ,可能是讨论组 ID、群组 ID、超级群 ID 或聊天室 ID。如 targetType 为 1 时可忽略 GroupId 。 |
busChannel | String | 超级群的频道 ID。 |
classname | String | 消息的类型,例如文本消息 RC:TxtMsg 、图片消息 RC:ImgMsg 。详见消息类型概述。 |
content | String | 消息的内容。详见消息类型概述 中各类消息内容的结构。 |
extraContent | Object | 消息扩展的内容,JSON 结构的 Key、Value 对,如:{"type":"3"} 。Key 最大 32 个字符,支持大小写英文字母、数字、 特殊字符+ = - _ 的组合方式,不支持汉字。Value 最大 4096 个字符。 |
dateTime | String | 消息时间。 |
source | String | 消息的来源,包括:iOS、Android、HarmonyOS、Websocket、MiniProgram(小程序)、PC、Server。 |
isDiscard | String | 消息是否被丢弃,true 为是,false 为否,只针对聊天室会话类型存在。 |
isSensitiveWord | String | 消息是否含有被屏蔽的敏感词,true 为含有、false 为不含有。只针对聊天室会话类型存在。 |
isForbidden | String | 消息是否为被禁言后发送,只针对聊天室会话类型存在。 |
isNotForward | String | 消息是否不分发,true 为不分发、false 为分发。只针对聊天室会话类型存在。 |
msgUID | String | 消息的唯一标识。可通过 msgUID 确定消息唯一。 |
groupUserIds | String[] | targetType 为 3 时此参数有效,为群组中指定接收消息的用户 ID 数组,该条消息为群组定向消息。非定向消息时内容为空,如指定的用户不在群组中内容也为空。 |
请求方法
POST: https://数据中心域名/message/history.json
频率限制:每秒 100 次
签名规则:所有服务端 API 请求均需要进行规则校验,详见 API 请求签名。
正文参数
HTTP 请求正文数据格式为 application/x-www-form-urlencoded
,支持以下 HTTP 表单参数:
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
date | String | 是 | 指定时间,精确到某天某小时,格式为 YYYYMMDDHH 。例如 2014010101 表示需要获取 2014 年 1 月 1 日凌晨 1 点至 2 点的数据。注意: date 的值与应用所属数据中心有关。如果您的应用业务使用新加坡数据中心,则获取消息日志时使用的时间(date ), 及日志中的消息时间(dateTime )均为 UTC 时间。如您仍需根据北京时间下载数据,请自行转换。例如,如需下载北京时间 2019120109 的日志,需要输入 2019120101 。 |
返回结果
返回值 | 返回类型 | 说明 |
---|---|---|
code | Int | 返回码,200 为正常。 |
url | String | 历史记录下载地址。如没有消息记录数据时,则 url 值为空。 |
date | String | 历史记录时间。 |
请求示例
HTTP
POST /message/history.json HTTP/1.1
Host: api.rong-api.com
App-Key: uwd1c0sxdlx2
Timestamp: 1408710653491
Nonce: 14314
Signature: 45beb7cc7307889a8e711219a47b7cf6a5b000e8
Content-Type: application/x-www-form-urlencoded
date=2014010101
返回结果示例
HTTP
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"code":200,
"url":"http://aa.com/1/c6720eea-452b-4f93-8159-7af3046611f1.gz",
"date":"2014010101"
}