获取历史消息记录

大约 8 分钟

获取历史消息记录

你可以从服务端获取用户发送的历史消息的记录。

  • 单次请求获取从指定起始时间开始一小时内的发送的历史消息记录。
  • 查询历史消息记录时存在一定延时，无法实时获取。
  • 过期的历史消息记录无法获取。历史消息记录的默认存储时间14天，支持联系商务调整。

前提条件

要调用环信即时通讯 REST API，请确保满足以下要求：

公共参数

请求参数

参数类型是否必需描述
hostString是访问 RESTful API 的域名或服务器信息。
-公有云集成为 环信即时通讯控制台的 即时通讯->服务概览页面下的 域名配置- Rest Api。
-私有化集成为部署后 服务器地址:端口。
org_nameString是每个公司（组织）分配的唯一标识。详见 环信即时通讯控制台的 应用概览->应用详情页面下的 应用信息-Orgname。
app_nameString是创建应用时填入的应用名称。详见 环信即时通讯控制台的 应用概览->应用详情页面下的 应用信息-Appname。

响应参数

参数类型描述
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是历史消息记录查询的起始时间。UTC 时间，使用 ISO8601 标准，格式为 yyyyMMddHH。例如 time 为 2018112717，则表示查询 2018 年 11 月 27 日 17 时至 2018 年 11 月 27 日 18 时期间的历史消息。若海外集群为 UTC 时区，需要根据自己所在的时区进行时间转换。

其他参数及描述详见 公共参数。

请求 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，表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例

# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatmessages/2018112717'

响应示例

{
  "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，即当前用户发送的消息。
fromString消息发送方的用户 ID。
toString消息接收方。
- 单聊为接收方用户 ID；
- 群聊为群组 ID；
- 聊天室聊天为聊天室 ID。
chat_typeString会话类型：
- chat: 单聊；
- groupchat: 群聊；
- chatroom: 聊天室。
payloadJSON消息的具体内容。例如，消息扩展信息等。

历史消息记录为 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 包含如下字段：

参数类型描述
customExtsJSON自定义扩展属性。你可以自行设置扩展属性中的字段。
customEventString自定义事件类型。
typeString消息类型。自定义消息为 custom。

自定义类型消息格式示例如下：

"bodies":
[
  {
  "customExts":
    {
    "name":"flower",
    "size":"16",
    "price":"100"
    },
  "customEvent":"gift_1",
  "type":"custom"
 }
]
上次编辑于:
环信私有化部署