聊天记录


环信支持 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错误,说明接口被限流了,请稍微暂停一下并重试。详见接口限流说明

  • 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。详见:服务器端 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错误,说明接口被限流了,请稍微暂停一下并重试。详见接口限流说明

  • 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。详见:服务器端 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"

上一页:用户体系集成

下一页:文件上传下载