聊天记录

环信支持把聊天记录通过 REST 接口导出。聊天记录的导出异常时，有可能是因为接口被限流了，请稍微暂停一下并重试。详见接口限流说明

聊天记录数据结构

聊天记录的数据格式主要字段的描述说明，可参考返回的数据结构示例

参数说明
msg_id消息ID
timestamp消息发送时间
from发送人username
to接收人的username或者接收group的ID
chat_type用来判断单聊、群聊还是聊天室。chat: 单聊；groupchat: 群聊；chatroom: 聊天室
payload消息bodies，不同的消息类型；消息ext，自定义扩展属性等

聊天记录返回数据格式示例 

{
    "msg_id": "5I02W-16-8278a", 
    "timestamp": 1403099033211, 
    "direction":"outgoing",
    "to": "1402541206787",
    "from": "zw123", 
    "chat_type": "chat", 
    "payload": {
        "bodies": [
          {
             //下面会将不同的消息类型进行说明
          }
        ],
        "ext": {
            "key1": "value1", 
    		   ...
         },
         "from":"zw123",
         "to":"1402541206787"
    }
}

文本类型消息

对应上述消息的bodies参数，对文本类型消息参数说明

参数说明
msg消息内容
type“txt”，文本消息类型

文本类型消息格式示例 

"bodies": [ 
   {
       "msg":"welcome to easemob!",
       "type":"txt"
   }
]

图片类型消息

对应上述消息的bodies参数，对图片类型消息参数说明

参数说明
file_length图片附件大小（单位：字节）
filename“image.jpg”, 图片名称，带图片格式
secret在上传图片后会返回字符串，只有含有secret才能够下载此图片
size图片长、宽尺寸
type“img”,图片消息类型
url上传图片消息地址，在上传成功后会返回UUID

图片类型消息格式示例 

"bodies": [ 
   {
       "file_length":128827,
       "filename":"test1.jpg", 
       "secret":"DRGM8OZrEeO1vafuJSo2IjHBeKlIhDp0GCnFu54xOF3M6KLr", 
       "size":{"height":1325,"width":746},
       "type":"img",
    	"url":"https://a1.easemob.com/easemob-demo/chatdemoui/chatfiles/65e54a4a-fd0b-11e3-b821-ebde7b50cc4b", 
   }
]

地址位置类型消息

对应上述消息的bodies参数，对地理位置类型消息参数说明

参数说明
addr“地址”要发送的地址文字内容描述
lat纬度
lng经度
type“loc”，位置消息类型

地理位置类型消息格式示例 

"bodies": [
   {
       "addr":"西城区西便门桥 ",
       "lat":39.9053,
       "lng":116.36302, 
       "type":"loc"  
   }
]

语音类型消息

对应上述消息的bodies参数，对语音类型消息参数说明

参数说明
file_length语音附件大小（单位：字节）
filename“audio,amr”, 语音文件，带文件格式
secret在上传语音后会返回字符串，只有含有secret才能够下载此语音文件
length语音时间（单位：秒）
type“audio”,语音消息类型
url上传语音文件地址，在上传成功后会返回UUID

语音类型消息格式示例 

"bodies": [ 
   {
       "file_length":6630,
       "filename":"test1.amr",
       "length":10, 
       "secret":"DRGM8OZrEeO1vafuJSo2IjHBeKlIhDp0GCnFu54xOF3M6KLr",
       "type":"audio",
    	"url":"https://a1.easemob.com/easemob-demo/chatdemoui/chatfiles/0637e55a-f606-11e3-ba23-51f25fd1215b"
   }
]

视频类型消息

对应上述消息的bodies参数，对视频类型消息参数说明

参数说明
file_length视频附件大小（单位：字节）
filename“video,mp4”, 视频文件，带文件格式
secret在上传视频后会返回字符串，只有含有secret才能够下载此视频文件
length视频播放长度（单位：秒）
size视频缩略图长、宽尺寸
thumb上传视频缩略图远程地址，在上传视频缩略图后会返回UUID
thumb_secret在上传视频缩略图后会返回字符串，只有含有secret才能够下载此视频缩略图
type“video”,视频消息类型
url上传视频地址，在上传成功后会返回UUID

视频类型消息格式示例 

"bodies": [
   {
       "file_length": 58103,
       "filename": "1418105136313.mp4",
       "length": 10,
       "secret": "VfEpSmSvEeS7yU8dwa9rAQc-DIL2HhmpujTNfSTsrDt6eNb_",
       "size":{"height":480,"width":360},
       "thumb": "https://a1.easemob.com/easemob-demo/chatdemoui/chatfiles/67279b20-7f69-11e4-8eee-21d3334b3a97",
       "thumb_secret": "ZyebKn9pEeSSfY03ROk7ND24zUf74s7HpPN1oMV-1JxN2O2I",
       "type": "video",
        "url": "https://a1.easemob.com/easemob-demo/chatdemoui/chatfiles/671dfe30-7f69-11e4-ba67-8fef0d502f46"
   }
]

文件类型消息

对应上述消息的bodies参数，对文件类型消息参数说明

参数说明
file_length文件大小（单位：字节）
filename“file.zip”, 文件名称，带文件格式
secret在上传文件后会返回字符串，只有含有secret才能够下载此文件
type“file”,图片消息类型
url上传文件的地址，在上传成功后会返回UUID

文件类型消息格式示例 

"bodies": [ 
   {
       "file_length":3279,
       "filename":"record.md",
       "secret":"2RNXCgeeEee2caV-fSQ1btZXJH4cgr2admVXn560He2PD3RX",
       "type":"file",
       "url":"https://a1.easemob.com/sxqxwdong/mychatdemo/chatfiles/d9135700-079e-11e7-b000-a7039876610f"
   }
]

REST API

导出聊天记录接口不是实时接口，获取成功存在一定的延时，不能够作为实时拉取消息的接口使用。以下 API 均需要企业管理员权限才能访问。

需要使用 REST API 导出聊天记录，可以通过使用文档中嵌入的Easemob REST API进行在线测试。

名称请求描述
获取历史消息文件/{org_name}/{app_name}/chatmessages/${time}根据请求的时间范围返回数据的文件，下载查看

获取历史消息文件

环信提供的 REST API 需要权限才能访问，权限通过发送 HTTP 请求时携带 token 来体现，下面描述获取 token 的方式。说明：API 描述的时候使用到的 {APP 的 client_id} 之类的这种参数需要替换成具体的值。

重要提醒：获取 token 时服务器会返回 token 有效期，具体值参考接口返回的 expires_in 字段值。由于网络延迟等原因，系统不保证 token 在此值表示的有效期内绝对有效，如果发现 token 使用异常请重新获取新的 token，比如“http response code”返回 401。另外，请不要频繁向服务器发送获取 token 的请求，同一账号发送此请求超过一定频率会被服务器封号，切记，切记！！

此接口一次只能获取一个小时的历史消息

client_id 和 client_secret 可以在环信管理后台的 APP 详情页面看到。

HTTP Request

/{org_name}/{app_name}/chatmessages/${time}

需要在请求时对应填写{time}，需要获取的时间段。

Request Headers

参数说明
Content-Typeapplication/json
AuthorizationBearer ${token}

Response Body

在返回值中查看data字段包含的信息

参数说明
url聊天记录文件下载地址

请求示例

curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer YWMtVVK6cPFqEeif2wnxtHDB7AAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnT6x89wBPGgCnBeC15W5VAU5kW2f80QS3_SQSnbEjyOtg8XCcmkvUXw' 'http://a1.easemob.com/easemob-demo/testapp/chatmessages/2018112717'

可能返回的结果示例

返回值200，表示成功返回了聊天记录文件下载地址 

{
  "action": "get",
  "application": "8be024f0-e978-11e8-b697-5d598d5f8402",
  "uri": "http://a1.easemob.com/easemob-demo/testapp/chatmessages/2018112717",
  "data": [
    {
      "url": "http://ebs-chatmessage-a1.easemob.com/history/3D/easemob-demo/testapp/2018112717.gz?Expires=1543316122&OSSAccessKeyId=LTAIlKPZStPokdA8&Signature=2oQHPpaOgrGcqggkmeXqovM%2FWd8%3D"
    }
  ],
  "timestamp": 1543314322601,
  "duration": 0,
  "organization": "easemob-demo",
  "applicationName": "testapp"
}

注意：url是有过期时间的，url中的Expires对应的时间戳就是过期时间(秒)，请及时通过url下载聊天记录文件，过期后会下载不到，需要重新调用"获取历史消息文件"接口获取新的url。

返回值400，表示要取得历史记录已过期、要取得的历史记录文件还没有生成 

{
  "error": "illegal_argument",
  "timestamp": 1543312726441,
  "duration": 0,
  "exception": "java.lang.IllegalArgumentException",
  "error_description": "illegal arguments: appkey: easemob-demo#testapp, time: 2018112717, maybe chat message history is expired or unstored"
}

返回值401，表示未授权[无token、token错误、token过期] 

{
  "error": "unauthorized",
  "timestamp": 1543314417735,
  "duration": 0,
  "exception": "org.apache.shiro.authz.UnauthorizedException"
}

如果返回结果是5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

提示

极少数情况下，聊天记录中的消息可能重复地被记录。

查询的时间格式为10位数字形式(YYYYMMDDHH),例如要查询2016年12月10号7点到8点的历史记录，则需要输入2016121007,7:00:00的信息也会包含在这个文件里。

因为历史记录文件生成需要一定时间，建议用户在取得历史记录时要间隔一个小时，例如2016/12/10 09:00之后，可以开始下载2016/12/10 07:00 ～ 08:00的消息历史记录。

接口返回的下载地址30分钟内有效，服务端默认保存3天文本消息，7天文件消息，如需延长存储时间请联系商务经理。