# 获取历史消息记录# 功能说明你可以从服务端获取用户发送的历史消息的记录。
单次请求获取从指定起始时间开始一小时内的发送的历史消息记录。你最多可以获取最近 3 天的历史消息记录。若要提升该限制，你需要联系环信商务。当平台消息分发量较大时，服务器生成历史消息记录需要一定时间，建议 24 小时后拉取这些记录。若对时效性有较高要求，推荐使用 发送后回调服务。若调用了 REST API 单向删除会话 或 单向删除漫游消息，不影响通过该接口的获取的历史消息记录。调用频率上限：10 次/分钟/App Key
# 前提条件要调用环信即时通讯 REST API，请确保满足以下要求：
已在环信即时通讯控制台 开通配置环信即时通讯 IM 服务。了解环信 IM REST API 的调用频率限制，详见 接口频率限制。# 公共参数# 请求参数参数类型是否必需描述hostString是环信即时通讯 IM 分配的用于访问 RESTful API 的域名。详见 获取环信即时通讯 IM 的信息。org_nameString是环信即时通讯 IM 为每个公司（组织）分配的唯一标识。详见 获取环信即时通讯 IM 的信息。app_nameString是你在环信即时通讯云控制台创建应用时填入的应用名称。详见 获取环信即时通讯 IM 的信息。# 响应参数参数类型描述actionString请求方法。organizationString环信即时通讯 IM 为每个公司（组织）分配的唯一标识，与请求参数 org_name 相同。applicationString应用在系统内的唯一标识。该标识由系统生成，开发者无需关心。applicationNameString你在环信即时通讯云控制台创建应用时填入的应用名称，与请求参数 app_name 相同。uriString请求 URL。pathString请求路径，属于请求 URL 的一部分，开发者无需关注。timestampLongHTTP 响应的 Unix 时间戳，单位为毫秒。durationInt从发送 HTTP 请求到响应的时长，单位为毫秒。# 认证方式环信即时通讯 REST API 要求 Bearer HTTP 认证。每次发送 HTTP 请求时，都必须在请求头部填入如下 Authorization 字段：
Authorization: Bearer YourAppToken
为提高项目的安全性，环信使用 Token（动态密钥）对即将登录即时通讯系统的用户进行鉴权。本篇涉及的所有消息管理 REST API 都需要使用 App Token 的鉴权方式，详见 使用 App Token 鉴权。
# HTTP 请求GET https://{host}/{org_name}/{app_name}/chatmessages/{time}
# 路径参数参数类型是否必需描述timeString是历史消息记录查询的起始时间。 - 国内集群：采用北京时间，格式为 yyyyMMddHH。例如 time 为 2018112717，则表示查询 2018 年 11 月 27 日 17 时至 2018 年 11 月 27 日 18 时期间的历史消息。 - 海外集群：采用 UTC 时间，格式为 yyyyMMddHH，你需要根据自己所在的时区进行时间转换。其他参数及描述详见 公共参数。
# 请求 header参数类型是否必需描述AcceptString是内容类型，请填 application/json。AuthorizationString是App 管理员的鉴权 token，格式为 Bearer YourAppToken，其中 Bearer 为固定字符，后面为英文空格和获取到的 app token。# HTTP 响应# 响应 body如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：
参数类型描述dataJSON实际获取的数据详情。data.urlString历史消息记录的下载地址。该 URL 由历史消息记录的存储地址、到期 Unix 时间戳（Expires，单位为秒）、第三方云存储访问密钥（OSSAccessKeyId）和第三方云存储验证签名（Signature）组成。URL 仅在一定时间内有效，请及时通过 URL 下载聊天记录文件，URL 过期后会下载失败，需要重新调用该接口获取新的 URL。其他参数及说明详见 公共参数。
如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考 响应状态码 了解可能的原因。
# 示例# 请求示例# 将
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer
# 响应示例{
"action": "get",
"application": "8be024f0-XXXX-XXXX-b697-5d598d5f8402",
"uri": "'https://XXXX/XXXX/XXXX/chatmessages/2018112717",
"data": [
{
"url": "https://XXXX?Expires=1543316122&OSSAccessKeyId=XXXX&Signature=XXXX"
}
],
"timestamp": 1543314322601,
"duration": 0,
"organization": "XXXX",
"applicationName": "testapp"
}
# 历史消息记录的内容查询历史消息记录成功后，你可以访问 URL 下载历史消息记录文件，查看历史消息记录的具体内容。
一条历史消息记录包含以下字段：
参数类型描述msg_idString消息 ID。timestampLong消息发送完成的 UNIX 时间戳，单位为毫秒，UTC 时间。directionString消息方向，值为 outgoing，即当前用户发送的消息。toString内部字段，开发者可忽略。fromString内部字段，开发者可忽略。chat_typeString会话类型： - chat: 单聊； - groupchat: 群聊； - chatroom: 聊天室。payloadJSON消息的具体内容。例如，消息扩展信息等。payload.fromString消息发送方的用户 ID。payload.toString消息接收方： - 单聊为接收方用户 ID； - 群聊为群组 ID； - 聊天室聊天为聊天室 ID。历史消息记录为 JSON 类型，示例如下：
{
"msg_id": "5I02W-XX-8278a",
"timestamp": 1403099033211,
"direction": "outgoing",
"to": "XXXX",
"from": "XXXX",
"chat_type": "chat",
"payload":
{
"bodies": [ {
//下面会将不同的消息类型进行说明
}
],
"ext":
{
"key1": "value1", ... },
"from":"XXXX",
"to":"XXXX"
}
}
# 文本消息文本消息的 bodies 包含如下字段：
参数类型描述msgString消息内容。typeString消息类型，文本消息类型为 txt。示例
"bodies": [{"msg":"welcome to easemob!", "type":"txt"}]
# 图片消息图片消息的 bodies 包含如下字段：
参数类型描述file_lengthLong图片附件大小，单位为字节。filenameString图片文件名称，包含文件后缀名。secretString图片文件访问密钥。如果 文件上传 时设置了文件访问限制，则该字段存在。sizeJSON图片的尺寸。单位为像素。 - height：图片高度。 - width：图片宽度。typeString消息类型。图片消息为 img。urlString图片 URL 地址。示例
{
"bodies": [
{
"file_length": 128827,
"filename": "test1.jpg",
"secret": "DRGM8OZrEeO1vaXXXXXXXXHBeKlIhDp0GCnFu54xOF3M6KLr",
"size": {
"height": 1325,
"width": 746
},
"type": "img",
"url": "https://XXXX/XXXX/chatdemoui/chatfiles/65e54a4a-XXXX-XXXX-b821-ebde7b50cc4b"
}
]
}
# 位置消息位置消息的 bodies 包含如下字段：
参数类型描述addrString位置的地址描述。latLong位置的纬度。lngLong位置的经度。typeString消息类型。位置消息为 loc。示例
"bodies": [
{
"addr":"西城区西便门桥 ",
"lat":39.9053,
"lng":116.36302,
"type":"loc"
}]
# 语音消息语音消息的 bodies 包含如下字段：
参数类型描述file_lengthLong语音附件大小。单位为字节。filenameString语音文件名称，包含文件后缀名。secretString语音文件访问密钥。如果 文件上传 时设置了文件访问限制，则该字段存在。lengthInt语音时长。单位为秒。typeString消息类型。语音消息为 audio。urlString语音文件的 URL 地址。示例
"bodies":
[
{
"file_length":6630,
"filename":"test1.amr",
"length":10,
"secret":"DRGM8OZrEeO1vafuJSo2IjHBeKlIhDp0GCnFu54xOF3M6KLr",
"type":"audio",
"url":"https://XXXX/XXXX/chatdemoui/chatfiles/0637e55a-f606-XXXX-XXXX-51f25fd1215b"
}
]
# 视频消息视频消息的 bodies 包含如下字段：
参数类型描述file_lengthLong视频附件大小。单位为字节。filenameString视频文件名称，包含文件后缀名。secretString视频文件的访问密钥。如果 文件上传 时设置了文件访问限制，则该字段存在。lengthInt视频时长。单位为秒。sizeJSON视频缩略图尺寸。单位为像素。 - width：视频缩略图的宽度； - height：视频缩略图的高度。thumbString视频缩略图的 URL 地址，格式为 https://{host}/{org_name}/{app_name}/chatfiles/{file_uuid}。其中，file_uuid 为视频缩略图上传后，环信服务器返回的缩略图的 UUID。thumb_secretString缩略图文件访问密钥。如果文件上传时设置了文件访问限制，则该字段存在。typeString消息类型。视频消息为 video。urlString视频文件的 URL 地址。示例如下：
"bodies":
[
{
"file_length": 58103,
"filename": "14XXXX.mp4",
"length": 10,
"secret": "VfEpSmSvEeS7yU8dwa9rAQc-DIL2HhmpujTNfSTsrDt6eNb_",
"size":{"height":480,"width":360},
"thumb": "https://XXXX/XXXX/chatdemoui/chatfiles/67279b20-XXXX-XXXX-8eee-21d3334b3a97",
"thumb_secret": "ZyebKn9pEeSSfY03ROk7ND24zUf74s7HpPN1oMV-1JxN2O2I",
"type": "video",
"url": "https://XXXX/XXXX/chatdemoui/chatfiles/671dfe30-XXXX-XXXX-ba67-8fef0d502f46" }]
# 文件消息文件消息的 bodies 包含如下字段：
参数类型描述file_lengthLong文件大小。单位为字节。filenameString文件名称，包含文件后缀名。secretString文件访问密钥。如果 文件上传 时设置了文件访问限制，则该字段存在。typeString消息类型。文件消息为 file。urlString文件的 URL 地址。你可以访问该 URL 下载历史消息文件。示例如下：
"bodies":
[
{
"file_length":3279,
"filename":"record.md",
"secret":"2RNXCgeeEeeXXXX-XXXXbtZXJH4cgr2admVXn560He2PD3RX",
"type":"file",
"url":"https://XXXX/XXXX/XXXX/chatfiles/d9135700-XXXX-XXXX-b000-a7039876610f"
}
]
# 透传消息透传消息的 bodies 包含如下字段：
参数类型描述actionString命令内容。typeString消息类型。透传消息为 cmd。示例如下：
"bodies":
[
{
"action":"run",
"type":"cmd"
}
]
# 自定义消息自定义消息的 bodies 包含如下字段：
参数类型描述customExts/v2:customExtsArray/JSON用户自定义的事件属性。该参数为可选，不需要可以不传。 - customExts 为旧版参数，数组类型，最多可包含 16 个元素。 - v2:customExts 为新版参数，Map
"bodies":
[
{
"v2:customExts": {
"name": "flower",
"size": "16",
"price": "100"
},
"customExts": [
{
"name": "flower"
},
{
"size": "16"
},
{
"price": "100"
}
],
"customEvent": "gift_1",
"type": "custom"
}
]
# 合并消息合并消息的 bodies 包含如下字段：
参数类型描述combineLevelInt合并消息的嵌套层级数。file_lengthInt合并消息附件的大小，单位为字节。filenameString合并消息的附件名称。secretString合并消息附件的访问密钥。如果文件上传 时设置了文件访问限制，则该字段存在。subTypeString表示消息类型为合并消息。summaryString合并消息的概要。titleString合并消息的标题。urlString合并消息的附件的 URL 地址。你可以访问该 URL 下载该附件。例如，下面示例为源消息包括文本、图片和文件消息的合并消息格式：
"bodies":
[
{
"combineLevel": 1,
"file_length": 550,
"filename": "17289718748990036",
"secret": "a_OTmoq6Ee-CygH0PRzcUyFniZDmSsX1ur0j-9RtCj3tK6Gr",
"subType": "sub_combine",
"summary": ":yyuu\n:[图片]\n:[文件]\n",
"title": "聊天记录",
"url": "https://XXXX/XXXX/XXXX/chatfiles/6bf39390-8aba-11ef-a8ae-6f545c50ca23"
}
]
# 错误码如果返回的 HTTP 状态码非 200，表示请求失败，可能提示以下错误码：
HTTP 状态码错误类型错误提示可能原因处理建议400illegal_argumentillegal arguments: appkey: XXXX#XXXX, time: xxxxxx请求参数 time 格式不正确。输入正确的请求参数 time:UTC 时间，使用 ISO8601 标准，格式为 yyyyMMddHH。例如 time 为 2018112717，则表示查询 2018 年 11 月 27 日 17 时至 2018 年 11 月 27 日 18 时期间的历史消息。若海外集群为 UTC 时区，需要根据自己所在的时区进行时间转换。400illegal_argumentillegal arguments: appkey: XXXX#XXXX, time: xxxxxx, maybe chat message history is expired or unstored"time 对应时间段内的历史文件已过期或者暂未存储。消息的云存储时间取决于产品套餐，详见 消息存储时长限制。输入正确的请求参数 time。404storage_object_not_foundFailed to find chat message history download url for appkey: XXXX#XXXX, time: xxxxxx"对应 time 对应时间段内不存在历史文件。如果确定设置的时间内有历史消息，请联系 环信技术支持。