====== 聊天记录 ======

----

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

===== 聊天记录数据结构 =====

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

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

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

<code json>
{
    "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"
    }
}
</code>

===== 文本类型消息 =====

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

^参数^说明^
|msg|消息内容|
|type|"txt"，文本消息类型|

文本类型消息格式示例
<code json>
"bodies": [ 
   {
       "msg":"welcome to easemob!",
       "type":"txt"
   }
]
</code>

===== 图片类型消息 =====

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

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

图片类型消息格式示例
<code json>
"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", 
   }
]
</code>


===== 地址位置类型消息 =====

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

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

地理位置类型消息格式示例
<code json>
"bodies": [
   {
       "addr":"西城区西便门桥 ",
       "lat":39.9053,
       "lng":116.36302, 
       "type":"loc"  
   }
]
</code>

===== 语音类型消息 =====

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

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

语音类型消息格式示例
<code json>
"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"
   }
]
</code>

===== 视频类型消息 =====

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

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

视频类型消息格式示例

<code json>
"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"
   }
]
</code>

===== 文件类型消息 =====

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

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

文件类型消息格式示例

<code json>
"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"
   }
]
</code>
----

====== REST API ======

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

需要使用 REST API 导出聊天记录，可以通过使用文档中嵌入的[[http://api-docs.easemob.com/|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 可以在环信管理后台的 [[https://console.easemob.com/app/applicationOverview/detail|APP 详情页面]]看到。

=== HTTP Request ===

^{{:im:server:ready:get.png?nolink&90 |}}^**/{org_name}/{app_name}/chatmessages/${time}**^
需要在请求时对应填写{time}，需要获取的时间段。

=== Request Headers ===

^参数^说明^
|Content-Type|application/json|
|Authorization|Bearer ${token}|

=== Response Body ===
在返回值中查看data字段包含的信息
^参数^说明^
|url|聊天记录文件下载地址|

=== 请求示例 ===

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

=== 可能返回的结果示例 ===

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

<code json>
{
  "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。
</code>

**返回值400，表示要取得历史记录已过期、要取得的历史记录文件还没有生成**
<code json>
{
  "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"
}
</code>

**返回值401，表示未授权[无token、token错误、token过期]**
<code json>
{
  "error": "unauthorized",
  "timestamp": 1543314417735,
  "duration": 0,
  "exception": "org.apache.shiro.authz.UnauthorizedException"
}
</code>

如果返回结果是<wrap em>5xx</wrap>，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:450errorcode:45restastrict|接口限流说明]]

[[http://api-docs.easemob.com/|使用 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天文件消息，如需延长存储时间请联系商务经理。

----