聊天记录


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

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

参数说明
msg_id消息ID
timestamp消息发送时间
from发送人username
to接收人的username或者接收group的ID
chat_type用来判断单聊还是群聊。chat: 单聊;groupchat: 群聊
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

导出聊天记录接口不是实时接口,获取成功存在一定的延时,不能够作为实时拉取消息的接口使用。目前提供两种方式来导出聊天记录,即下载历史消息文件拉取历史消息两个接口,其中拉取历史消息接口为旧有接口并于2017年3月1日起停止使用,建议使用下载历史消息文件接口。以下所有 API 均需要企业管理员权限才能访问。

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

名称请求描述
获取历史消息文件/{org_name}/{app_name}/chatmessages/${time}根据请求的时间范围返回数据的文件,下载查看
拉取历史消息已停用/{org_name}/{app_name}/chatmessages根据请求的时间范围实时获取历史聊天记录

环信提供的 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"
}

返回值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天文件消息,如需延长存储时间请联系商务经理。


根据请求的时间范围一次性获取聊天记录,每次最多返回1000条记录。该接口已停用

名称请求描述
根据 timestamp 查询聊天记录/{org_name}/{app_name}/chatmessages?ql=select+*+where+{timestamp}根据指定的时间范围获取历史消息
分页获取数据/{org_name}/{app_name}/chatmessages?ql=select+*+where+{timestamp}分页获取根据指定的时间范围获取历史消息

根据 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

HTTP Request

/{org_name}/{app_name}/chatmessages?ql=select+*+where+{timestamp}

请求参数中{timestamp}代表的是时间范围,详情见描述

Request Headers

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

Response Body

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

请求示例

curl -X GET -i -H "Authorization: Bearer YWMtxc6K0L1aEeKf9LWFzT9xEAAAAT7MNR_9OcNq-GwPsKwj_TruuxZfFSC2eIQ" "https://a1.easemob.com/easemob-demo/chatdemoui/chatmessages?ql=select+*+where+timestamp>1403164734226"

可能返回的结果示例

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

{
	"count" : 10,
	"cursor" : "asdsdfaee", 
	"entities" : [
		{
		}
	]
}

返回值400,表示参数 ql 结构错误

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

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

使用 Easemob REST API 在线测试


分页获取数据

使用 limit 参数获取数据完毕后,如果后边还有数据,会返回一个不为空的 cursor 回来,使用这个 cursor 就能进行分页获取了。 分页示例:根据之前获取数据返回的 cursor 继续获取后面的20条数据。在 URL 后面加上参数 cursor,ql 语句保持不变。 (一分钟最多调用10次,每次 limit 最大值为1000。)

HTTP Request

/{org_name}/{app_name}/chatmessages?ql=select+*+where+{timestamp}

请求参数中{timestamp}代表的是时间范围,详情见描述

Request Headers

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

Response Body

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

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

请求示例

curl -X GET -i -H "Authorization: Bearer YWMtxc6K0L1aEeKf9LWFzT9xEAAAAT7MNR_9OcNq-GwPsKwj_TruuxZfFSC2eIQ" "https://a1.easemob.com/easemob-demo/testapp/chatmessages?ql=select+*+where+timestamp>1403164734226&limit=20&cursor=MTYxOTcyOTYyNDpnR2tBQVFNQWdHa0FCZ0ZHczBKN0F3Q0FkUUFRYUdpdkt2ZU1FZU9vNU4zVllyT2pqUUNBZFFBUWFHaXZJUGVNRWVPMjdMRWo5b0w4dEFB"

可能返回的结果示例

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

{
	"count" : 10,
	"cursor" : "asdsdfaee", 
	"entities" : [
		{
		}
	]
}

返回值400,表示参数 ql 结构错误

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

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

使用 Easemob REST API 在线测试


上一页:聊天室管理

下一页:文件上传下载