====== 聊天记录 ======
----
环信支持 APP 把聊天记录通过 REST 接口导出。
===== 聊天记录数据结构 =====
{
"msg_id": "5I02W-16-8278a", //消息ID
"timestamp": 1403099033211, //消息发送时间
"direction":"outgoing",
"to": "1402541206787", //接收人的username或者接收group的ID
"from": "zw123", //发送人username
"chat_type": "chat", //用来判断单聊还是群聊。chat: 单聊；groupchat: 群聊
"payload": {
"bodies": [ //消息bodies
{
//不同的消息类型，bodies数据格式见如下几条
}
],
"ext": { //自定义扩展属性
"key1": "value1", //你设置的key和value的值
...
},
"from":"zw123",
"to":"1402541206787"
}
}
==== 文本类型消息 ====
"bodies": [ //消息bodies
{
"msg":"hello from test2",//消息内容
"type":"txt"//文本消息类型
}
]
==== 图片类型消息 ====
"bodies": [ //消息bodies
{
"file_length":128827,//图片附件大小（单位：字节）
"filename":"test1.jpg", //图片名称
"secret":"DRGM8OZrEeO1vafuJSo2IjHBeKlIhDp0GCnFu54xOF3M6KLr", //secret在上传图片后会返回，只有含有secret才能够下载此图片
"size":{"height":1325,"width":746},//图片尺寸
"type":"img",//图片消息类型
"url":"https://a1.easemob.com/easemob-demo/chatdemoui/chatfiles/65e54a4a-fd0b-11e3-b821-ebde7b50cc4b", //上传图片消息地址，在上传图片成功后会返回UUID
}
]
==== 地址位置类型消息 ====
"bodies": [ //消息bodies
{
"addr":"西城区西便门桥 ",//要发送的地址
"lat":39.9053,//纬度
"lng":116.36302,//经度
"type":"loc"//位置消息类型
}
]
==== 语音类型消息 ====
"bodies": [ //消息bodies
{
"file_length":6630,//语音附件大小（单位：字节）
"filename":"test1.amr",//语音名称
"length":10, //语音时间（单位：秒）
"secret":"DRGM8OZrEeO1vafuJSo2IjHBeKlIhDp0GCnFu54xOF3M6KLr",//secret在上传文件后会返回
"type":"audio",//语音消息类型
"url":"https://a1.easemob.com/easemob-demo/chatdemoui/chatfiles/0637e55a-f606-11e3-ba23-51f25fd1215b"//上传语音远程地址，在上传语音后会返回UUID
}
]
==== 视频类型消息 ====
"bodies": [ //消息bodies
{
"file_length": 58103,//视频附件大小（单位：字节）
"filename": "1418105136313.mp4",//视频文件名称
"length": 10,//视频播放长度
"secret": "VfEpSmSvEeS7yU8dwa9rAQc-DIL2HhmpujTNfSTsrDt6eNb_",//secret在上传文件后会返回
"size":{"height":480,"width":360},//视频缩略图尺寸
"thumb": "https://a1.easemob.com/easemob-demo/chatdemoui/chatfiles/67279b20-7f69-11e4-8eee-21d3334b3a97",//上传视频缩略图远程地址，在上传视频缩略图后会返回UUID
"thumb_secret": "ZyebKn9pEeSSfY03ROk7ND24zUf74s7HpPN1oMV-1JxN2O2I",//secret在上传缩略图后会返回
"type": "video",//视频消息类型
"url": "https://a1.easemob.com/easemob-demo/chatdemoui/chatfiles/671dfe30-7f69-11e4-ba67-8fef0d502f46"//上传视频远程地址，在上传视频后会返回UUID
}
]
==== 文件类型消息 ====
"bodies": [ //消息bodies
{
"file_length":3279,//文件附件大小（单位：字节）
"filename":"record.md",//视频文件名称
"secret":"2RNXCgeeEee2caV-fSQ1btZXJH4cgr2admVXn560He2PD3RX",//secret在上传文件后会返回
"type":"file",//文件消息类型
"url":"https://a1.easemob.com/sxqxwdong/mychatdemo/chatfiles/d9135700-079e-11e7-b000-a7039876610f"//上传文件远程地址，在上传文件后会返回UUID
}
]
===== 导出聊天记录 =====
导出聊天记录接口不是实时接口获得的时间存在一定的延时，不能够作为实时拉取消息的接口使用。
目前提供两种方式来导出聊天记录，即下载历史消息文件和拉取历史消息两个接口，**其中拉取历史消息接口为旧有接口并于2017年3月1日起停止使用，建议使用下载历史消息文件接口**。
以下所有 API 均需要企业管理员权限才能访问。
==== 根据时间条件下载历史消息文件 ====
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[start:450errorcode:45restastrict|接口限流说明]]。
* Path: /{org_name}/{app_name}/chatmessages/${time}
* HTTP Method: GET
* URL Params: 无
* Request Headers: {“Content-Type”:”application/json”,”Authorization”:”Bearer ${token}”}
* Response Body: 历史文件的下载地址，可以通过地址下载对应的历史记录文件。
* 可能的错误码：400（要取得历史记录已过期、要取得的历史记录文件还没有生成）、401（未授权[无token、token错误、token过期]、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端 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天的历史文件,如需延长存储时间请联系商务经理。
Response 示例：
{
....
"uri" : "http://a1.easemob.com/easemob-demo/restapp1/chatmessages/2016121214",
"data" : [ {
"url" : "http://ebs-chatmessage-a1.easemob.com/history/1D/easemob-demo/restapp1/2016121214.gz?Expires=1481532888&OSSAccessKeyId=LTAIlKPZStPokdA8&Signature=Zzt%2ByJ7tj%2Bgq3zxLVK4QrbFutto%3D" //返回的文件下载地址
....
}
curl 示例：
curl -H "Authorization: Bearer YWMtKE9FxsAVEeaakDV5WXc9dQAAAAAAAAAAAAAAAAAAAAF8W6hAc0gR5oUiCYHCfur3AgMAAAFY8Ox2UgBPGgA6gtMo9E-nU8uaqRLXcs63EZi6Iu0QBpw6vta5E8Ix-g" -X GET "http://a1.easemob.com/easemob-demo/restapp1/chatmessages/2016121214"
==== 根据时间条件拉取历史消息（已停用） ====
一次最多返回1000条。
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[start:450errorcode:45restastrict|接口限流说明]]。
* Path: /{org_name}/{app_name}/chatmessages
* HTTP Method: GET
* URL Params: 无
* Request Headers: {“Content-Type”:”application/json”,”Authorization”:”Bearer ${token}”}
* Response Body: 聊天记录（JSON），默认返回10条记录
* 可能的错误码：400（参数 ql 结构错误）、401（未授权[无token、token错误、token过期]）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端 REST API 常见错误码]]
* 服务端默认保存3天的历史消息记录,如需延长存储时间请联系商务经理。
Response 示例：
{
....
"count" : 10, //返回的数量
"cursor" : "asdsdfaee", //游标，用于分页查询
"entities" : [
{
聊天记录entity
}
...
]
....
}
=== 示例1：根据 timestamp 查询聊天记录 ===
在URL后面加上参数 ''ql=select * where timestamp>1403164734226'' 或者 ''ql=select * where timestamp<1403164734226''。"="后的参数需要转义。
* 如只取最近的消息可以只用 ''timestamp>1403166586000''，然后记录获取到的最后一条消息的 timestamp，作为下次获取时使用的 timestamp，按此方法往下查询。
* 需要导出聊天记录的，可以结合 cursor 分页来查询出所需要的聊天记录。聊天记录查询接口返回数据已经按照 timestamp 字段做了升序排序。
* 不能使用 and、or 等操作符来组成这种查询 ''ql=select * where timestamp<1403164734226 and timestamp>1403166586000''。
curl 示例：
curl -X GET -i -H "Authorization: Bearer YWMtxc6K0L1aEeKf9LWFzT9xEAAAAT7MNR_9OcNq-GwPsKwj_TruuxZfFSC2eIQ" "https://a1.easemob.com/easemob-demo/chatdemoui/chatmessages?ql=select+*+where+timestamp>1403164734226"
=== 示例2：分页获取数据 ===
使用 limit 参数获取数据完毕后，如果后边还有数据，会返回一个不为空的 cursor 回来，使用这个 cursor 就能进行分页获取了。
分页示例：根据之前获取数据返回的 cursor 继续获取后面的20条数据。在 URL 后面加上参数 cursor，ql语句保持不变。
**（一分钟最多调用10次，每次 limit 最大值为1000。）**
curl 示例：
curl -X GET -i -H "Authorization: Bearer YWMtxc6K0L1aEeKf9LWFzT9xEAAAAT7MNR_9OcNq-GwPsKwj_TruuxZfFSC2eIQ" "https://a1.easemob.com/easemob-demo/chatdemoui/chatmessages?ql=select+*+where+timestamp>1403164734226&limit=20&cursor=MTYxOTcyOTYyNDpnR2tBQVFNQWdHa0FCZ0ZHczBKN0F3Q0FkUUFRYUdpdkt2ZU1FZU9vNU4zVllyT2pqUUNBZFFBUWFHaXZJUGVNRWVPMjdMRWo5b0w4dEFB"
----
上一页：[[start:100serverintegration:20users|用户体系集成]]
下一页：[[start:100serverintegration:40fileoperation|文件上传下载]]