聊天记录


环信支持 APP 把聊天记录通过 REST 接口导出。

聊天记录数据结构

{
    "type": "chatmessage",
    "from": "zw123", //发送人username
    "msg_id": "5I02W-16-8278a", //消息ID
    "chat_type": "chat", //用来判断单聊还是群聊。chat: 单聊;groupchat: 群聊
    "payload": {
        "bodies": [ //消息bodies
          {
            "msg": "hhhhhh", //消息内容
            "type": "txt", //消息类型。txt: 文本消息;img: 图片;loc: 位置;audio: 语音
            "length": 3, //语音时长,单位为秒,这个属性只有语音消息有
            "url": "", //图片语音等文件的网络URL,图片和语音消息有这个属性
            "filename": "22.png", //文件名字,图片和语音消息有这个属性
            "secret": "pCY80PdfEeO4Jh9URCOfMQWU9QYsJytynu4n-yhtvAhmt1g9", //获取文件的secret,图片和语音消息有这个属性
            "lat": 39.983805, //发送的位置的纬度,只有位置消息有这个属性
            "lng": 116.307417, //位置经度,只有位置消息有这个属性
            "addr": "北京市海淀区北四环西路66号" //位置消息详细地址,只有位置消息有这个属性
          }
        ],
            "ext": { //自定义扩展属性
            "key1": "value1",   //你设置的key和value的值
    		   ...
         },
    },
    "timestamp": 1403099033211, //消息发送时间
    "to": "1402541206787" //接收人的username或者接收group的ID
}

文本类型消息

{  
    "from":"test2",
    "to":"test1",
    "bodies":[{
        "type":"txt", //文本消息类型
        "msg":"hello from test2"//消息内容
     }]
}

图片类型消息

{  
    "from":"test1",
    "to":"test2",
    "bodies":[{
    	"type":"img",//图片消息类型
    	"url":"https://a1.easemob.com/easemob-demo/chatdemoui/chatfiles/65e54a4a-fd0b-11e3-b821-ebde7b50cc4b",//上传图片消息地址,在上传图片成功后会返回UUID
    	"filename":"test1.jpg",//图片名称
    	"thumb":"https://a1.easemob.com/easemob-demo/chatdemoui/chatfiles/496334fa-f53f-11e3-9eb7-4fbb06ff7876",//上传缩略图地址
    	"secret":"DRGM8OZrEeO1vafuJSo2IjHBeKlIhDp0GCnFu54xOF3M6KLr",//secret在上传图片后会返回,只有含有secret才能够下载此图片
    	"thumb_secret":"DRGM8OZrEeO1vafuJSo2IjHBeKlIhDp0GCnFu54xOF3M6KLr"//thumb_secret在上传缩略图后会返回
    }]
}

语音类型消息

{  
    "from":"test2",
    "to":"test1",
    "bodies":[{
    	"type":"audio",//语音消息类型
    	"url":"https://a1.easemob.com/easemob-demo/chatdemoui/chatfiles/0637e55a-f606-11e3-ba23-51f25fd1215b",//上传语音远程地址,在上传语音后会返回UUID
    	"filename":"test1.amr",//语音名称
    	"length":10, //语音时间(单位:秒)
    	"secret":"DRGM8OZrEeO1vafuJSo2IjHBeKlIhDp0GCnFu54xOF3M6KLr"//secret在上传文件后会返回
    }]
}

地址位置类型消息

{
    "from":"test1",
    "to":"test2",
    "bodies":[{
        "type":"loc",//位置消息类型
        "addr":"西城区西便门桥 ",//要发送的地址
        "lat":39.9053,//纬度
        "lng":116.36302//经度
     }]
}

视频类型消息

{
    "from":"test1",
    "to":"test2",
    "bodies":[{
        "type": "video",//视频消息类型
        "filename": "1418105136313.mp4",//视频文件名称
        "thumb": "https://a1.easemob.com/easemob-demo/chatdemoui/chatfiles/67279b20-7f69-11e4-8eee-21d3334b3a97",//上传视频缩略图远程地址,在上传视频缩略图后会返回UUID
        "length": 10,//视频播放长度
        "secret": "VfEpSmSvEeS7yU8dwa9rAQc-DIL2HhmpujTNfSTsrDt6eNb_",//secret在上传文件后会返回
        "file_length": 58103,
        "thumb_secret": "ZyebKn9pEeSSfY03ROk7ND24zUf74s7HpPN1oMV-1JxN2O2I",//secret在上传缩略图后会返回
        "url": "https://a1.easemob.com/easemob-demo/chatdemoui/chatfiles/671dfe30-7f69-11e4-ba67-8fef0d502f46"//上传视频远程地址,在上传视频后会返回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"

上一页:用户体系集成

下一页:文件上传下载