消息管理
更新时间:2022-05-19
本文介绍消息相关的 REST API,包括在服务端实现用户到用户或用户到群组的消息发送与接收、消息附件上传和下载、获取聊天记录、服务端消息撤回、服务端单向删除会话等。支持消息类型包括文本消息、图片消息、语音消息、视频消息、透传消息和自定义消息。
前提条件
要调用环信即时通讯 RESTful API,请确保满足以下要求:
- 已在环信即时通讯控制台 开通配置环信即时通讯 IM 服务。
- 已从服务端获取 app token,详见 使用环信 app token 鉴权。
常见参数说明
以下为常出现的响应体参数及描述:
参数 | 描述 |
---|---|
action | 请求方式,即接口方法名。 |
organization | 即 org_name ,即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。 |
application | 系统内为应用生成的唯一标识,开发者无需关心。 |
applicationName | 即 app_name ,你在环信即时通讯 IM 管理后台注册项目时填入的应用名称。 |
uri | 请求 URL。 |
path | 请求路径,属于请求 URL 的一部分,开发者无需关注。 |
host | 你在环信即时通讯 IM 管理后台注册项目时所在的集群服务器地址。 |
entities | 详细信息。 |
data | 实际取到的数据详情。 |
uuid | 系统内为用户或者应用生成的系统内唯一标识,开发者无需关心。 |
created | 用户创建时间,Unix 时间戳,单位为 ms。 |
username | 用户 ID,长度不可超过 64 个字节长度。不可设置为空。支持以下字符集:• 26 个小写英文字母 a-z; • 26 个大写英文字母 A-Z;• 10 个数字 0-9; • “_”, “-”, “.”。 注意: • 该参数不区分大小写,因此 Aa 和 aa 为相同用户名; • 请确保同一个 app 下,username 唯一; • username 用户 ID 是会公开的信息,请勿使用 UUID、邮箱地址、手机号等敏感信息。 |
groupname | 群组名。 |
nickname | 用户昵称。 |
timestamp | Unix 时间戳,单位为 ms。 |
duration | 请求响应时间, 单位为 ms。 |
认证方式
环信即时通讯 IM REST API 要求 Bearer HTTP 认证。每次发送 HTTP 请求时,都必须在请求头部填入如下 Authorization 字段:
Authorization:Bearer ${YourAppToken}
为提高项目的安全性,环信使用 Token(动态密钥)对即将登录即时通讯系统的用户进行鉴权。即时通讯 REST API 建议使用 app token 的鉴权方式,详见 使用 Token 鉴权。
具体接口
发送消息
接口描述
在服务端实现用户到用户,或用户到群组的消息发送与接收,消息类型包括文本消息、图片消息、语音消息、视频消息、透传消息以及自定义消息。
消息类型 | 说明 |
---|---|
发送文本/透传消息 | 直接编辑内容发送。 |
发送图片/语音/视频/附件消息 | 需要先上传这三类文件,从接口返回值中获取到相应的参数,按照 API 要求编辑到消息体中再发送,实际发送的其实都是 URL 等信息的纯文本。 |
调用服务端接口发送消息时,通过可选的 from
字段可以让接收方看到发送方是不同的人。
同时,支持扩展字段,通过 ext
属性,app 可以发送自己专属的消息结构,也包括设置推送等,详见 APNS 自定义显示 和 Android 推送字段说明。
注意
在调用程序中,请求体如果超过 5 KB 会导致 413 错误,需要拆成几个更小的请求体重试,同时用户消息加扩展字段的长度在 4 KB 字节以内。
基本信息
方法:POST
接入点:
- 不返回消息 ID:
https://{host}/{org_name}/{app_name}/messages
- 返回消息 ID:
https://{host}/{org_name}/{app_name}/messages?useMsgId=true
路径参数
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
host | String | 必需 | 你在环信即时通讯 IM 管理后台注册项目时所在的集群服务器地址。 |
org_name | String | 必需 | 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。 |
app_name | String | 必需 | 你在环信即时通讯 IM 管理后台注册项目时填入的应用名称。 |
请求头
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
Content-Type | String | 必需 | 内容类型:application/json |
Authorization | String | 必需 | Bearer ${token} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。 |
响应体
参数 | 说明 |
---|---|
username | 接收消息的用户名。 |
success | 消息发送成功。 |
通用请求体
这是所有消息的外层结构。这是一个 JSON 字段,不同的消息只是 msg
字段内容不一致。
参数 | 类型 | 是否必需 | 参数描述 |
---|---|---|---|
target_type | String | 必需 | 发送的目标类型: • users :给用户发消息; • chatgroups :给群发消息; • chatrooms :给聊天室发消息。 |
target | List | 必需 | 发送的目标;注意这里需要用数组,数组内添加的最大用户数默认 600 个,即使只有一个用户,也要用数组 [‘u1’];给用户发送时数组元素是用户名,给群组发送时,数组元素是 groupid。 |
msg | Json | 必需 | 具体消息内容参数集,参考以下不同类型消息。 |
from | String | 非必需 | 表示消息发送者;无此字段 Server 会默认设置为 “from”:“admin”,有 from 字段但值为空串 (“”) 时请求失败。 |
sync_device | Bool | 非必需 | 消息发送成功后,是否将消息同步给发送方。 - true :是;- (默认) false :否。 |
routetype | String | 非必需 | 该参数值为 “ROUTE_ONLINE”, 表示发送消息时只有接收方在线时,才进行消息投递。若接收方离线,将不会收到此条消息。 |
文字以及透传消息 msg 值
参数 | 参数类型 | 是否必需 | 说明 |
---|---|---|---|
type | String | 必需 | type 是消息类型,包括以下几种: •txt :文本消息; •img :图片消息; •loc :位置消息; •audio :语音消息; •video :视频消息; •file :文件消息; •cmd :透传消息。 |
msg | JSON | 必需 | 消息内容。 |
图片消息 msg 值
参数 | 参数类型 | 是否必需 | 说明 |
---|---|---|---|
filename | String | 必需 | 图片名称。 |
secret | String | 上传时需要就必需 | 成功上传文件后返回的 secret。 |
size | JSON | 必需 | 图片尺寸;height:高度,width:宽度。 |
url | String | 必需 | 域名 /orgname/appname/chatfiles/ 成功上传文件返回的 UUID。参考请求示例。 |
type | String | 必需 | type 是消息类型,包括以下几种: •txt :文本消息; •img :图片消息; •loc :位置消息; •audio :语音消息; •video :视频消息; •file :文件消息; •cmd :透传消息。 |
语音消息 msg 值
参数 | 参数类型 | 是否必需 | 说明 |
---|---|---|---|
filename | String | 必需 | 图片名称。 |
secret | String | 上传时需要就必需 | 成功上传文件后返回的 secret 。 |
Length | Int | 必需 | 语音时间(单位:秒)。 |
url | String | 必需 | 域名 /org_name/app_name/chatfiles/ 成功上传文件返回的 UUID。参考请求示例。 |
type | String | 必需 | type 是消息类型,包括以下几种: •txt :文本消息; •img :图片消息; •loc :位置消息; •audio :语音消息; •video :视频消息; •file :文件消息; •cmd :透传消息。 |
视频消息 msg 值
参数 | 参数类型 | 是否必需 | 说明 |
---|---|---|---|
thumb | String | 必需 | 成功上传视频缩略图返回的 UUID。 |
length | Int | 必需 | 视频播放长度。 |
secret | String | 上传时需要就必需 | 成功上传视频文件后返回的 secret 。 |
file_length | Long | 必需 | 视频文件大小(单位:字节)。 |
thumb_secret | String | 上传时需要就必需 | 成功上传视频缩略图后返回的 secret 。 |
url | String | 必需 | 成功上传视频文件返回的 UUID。 |
type | String | 必需 | type 是消息类型,包括以下几种: •txt :文本消息; •img :图片消息; •loc :位置消息; •audio :语音消息; •video :视频消息; •file :文件消息; •cmd :透传消息。 |
位置消息 msg 值
参数 | 参数类型 | 是否必需 | 描述 |
---|---|---|---|
lat | String | 必需 | 纬度。 |
lng | String | 必需 | 经度。 |
addr | String | 必需 | 位置的文字描述。 |
自定义 msg 值
参数 | 参数类型 | 是否必需 | 说明 |
---|---|---|---|
customEvent | String | 非必需 | 用户自定义的事件类型,必须是 string,值必须满足正则表达式:[a-zA-Z0-9-_/.]{1,32} ,最短 1 个字符 最长 32 个字符。 |
customExts | Json | 非必需 | 用户自定义的事件属性,类型必须是 Map<String,String> ,最多可以包含 16 个元素。customExts 是可选的,不需要可以不传。 |
from | String | 必需 | 表示消息发送者;无此字段 Server 会默认设置为 “from”:“admin”,有 from 字段但值为空串 (“”) 时请求失败。 |
ext | Json | 非必需 | 扩展属性,支持 app 自定义内容。可以没有这个字段;但是如果有,值不能是 “ext:null” 这种形式,否则会发生错误。 |
type | String | 必需 | type 是消息类型,包括以下几种: •txt :文本消息; •img :图片消息; •loc :位置消息; •audio :语音消息; •video :视频消息; •file :文件消息; •cmd :透传消息。 |
发送文本消息(发送给所有用户,消息无需同步给发送方)请求示例
curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer YWMtP5n9zvOQEei7KclxPqJTkgAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnXcBpfQBPGgDC09w5IdrfqG_H8_F53VLVTG0_82GXyEF8ZdMCt9-UpQ' -d '{"target_type": "users","target": ["user2","user3"],"msg": {"type": "txt","msg": "testmessage"},"from": "user1"}' 'http://a1.easemob.com/easemob-demo/testapp/messages'
发送文本消息(仅发送给在线用户,消息同步给发送方,返回消息 ID)请求示例
curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer YWMtP5n9zvOQEei7KclxPqJTkgAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnXcBpfQBPGgDC09w5IdrfqG_H8_F53VLVTG0_82GXyEF8ZdMCt9-UpQ' -d '{"target_type": "users","target": ["user2", "user3"],"msg": {"type": "txt","msg": "testmessage"},"from": "user1", "routetype":"ROUTE_ONLINE", "sync_device":true}' 'http://a1.easemob.com/easemob-demo/testapp/messages?useMsgId=true'
发送文本消息(发送给所有用户,消息无需同步给发送方)响应示例
{
"action": "post",
"application": "8be024f0-e978-11e8-b697-5d598d5f8402",
"path": "/messages",
"uri": "https://a1.easemob.com/easemob-demo/testapp/messages",
"data": {
"user2": "success",
"user3": "success"
},
"timestamp": 1543922150902,
"duration": 1,
"organization": "easemob-demo",
"applicationName": "testapp"
}
发送文本消息(仅发送给在线用户,消息同步给发送方,返回消息 ID)响应示例
{
"path":"/messages",
"uri":"http://a1.easemob.com/easemob-demo/testapp/messages",
"timestamp":1644305988265,
"organization":"easemob-demo",
"application":"8be024f0-e978-11e8-b697-5d598d5f8402",
"action":"post",
"data":{
"user2":"973845988210901688",
"user3":"973845988210905784"
},
"duration":0,
"applicationName":"testapp"
}
发送图片消息请求示例
curl -X POST -i 'https://a1.easemob.com/easemob-demo/testapp/messages' -H 'Authorization: Bearer YWMtsFVigGSuEeSTc7k5183Z5QAAAUqzeFx_9IjRch-ZxNbIlBIvx_4GWvzheSU' -d '{"target_type":"users","target":["user2"],"from":"user1","msg":{"type":"img","filename":"testimg.jpg","secret":"VfEpSmSvEeS7yU8dwa9rAQc-DIL2HhmpujTNfSTsrDt6eNb_","url":"https://a1.easemob.com/easemob-demo/testapp/chatfiles/55f12940-64af-11e4-8a5b-ff2336f03252","size":{"width":480,"height":720}}}'
发送图片消息响应示例
{
"action" : "post",
"application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
"uri" : "https://a1.easemob.com/easemob-demo/testapp/messages",
"entities" : [ ],
"data" : {
"user2" : "success"
},
"timestamp" : 1415166497129,
"duration" : 12,
"organization" : "easemob-demo",
"applicationName" : "testapp"
}
发送语音消息请求示例
curl -X POST -H "Authorization: Bearer YWMtxc6K0L1aEeKf9LWFzT9xEAAAAT7MNR_9OcNq-GwPsKwj_TruuxZfFSC2eIQ" "https://a1.easemob.com/easemob-demo/testapp/messages" -d '{"target_type" : "users","target" : ["user2", "user3"],"msg" : {"type": "audio","url": "https://a1.easemob.com/easemob-demo/testapp/chatfiles/1dfc7f50-55c6-11e4-8a07-7d75b8fb3d42","filename": "testaudio.amr","length": 10,"secret": "Hfx_WlXGEeSdDW-SuX2EaZcXDC7ZEig3OgKZye9IzKOwoCjM"},"from" : "user1" }'
发送语音消息响应示例
{
"action": "post",
"application": "8be024f0-e978-11e8-b697-5d598d5f8402",
"path": "/messages",
"uri": "https://a1.easemob.com/easemob-demo/testapp/messages",
"data": {
"user2": "success",
"user3": "success"
},
"timestamp": 1543922150902,
"duration": 1,
"organization": "easemob-demo",
"applicationName": "testapp"
}
发送视频消息请求示例
curl -X POST -i 'https://a1.easemob.com/easemob-demo/testapp/messages' -H 'Authorization: Bearer YWMtxc6K0L1aEeKf9LWFzT9xEAAAAT7MNR_9OcNq-GwPsKwj_TruuxZfFSC2eIQ' -d '{"target_type":"users","target":["user2","user3"],"from":"user1","msg":{"type":"video","filename" : "testvideo.mp4","thumb" : "https://a1.easemob.com/easemob-demo/testapp/chatfiles/67279b20-7f69-11e4-8eee-21d3334b3a97","length" : 0,"secret":"VfEpSmSvEeS7yU8dwa9rAQc-DIL2HhmpujTNfSTsrDt6eNb_","file_length" : 58103,"thumb_secret" : "ZyebKn9pEeSSfY03ROk7ND24zUf74s7HpPN1oMV-1JxN2O2I","url" : "https://a1.easemob.com/easemob-demo/testapp/chatfiles/671dfe30-7f69-11e4-ba67-8fef0d502f46"}}'
发送视频消息响应示例
{
"action" : "post",
"application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
"uri" : "https://a1.easemob.com/easemob-demo/testapp/messages",
"entities" : [ ],
"data" : {
"user2" : "success",
"user3" : "success"
},
"timestamp" : 1415166234863,
"duration" : 5,
"organization" : "easemob-demo",
"applicationName" : "testapp"
}
发送文件消息请求示例
curl -X POST -i 'https://a1.easemob.com/XXXX/XXXX/messages' -H 'Authorization: Bearer YWcXXXX2eIQ' -d '{"target_type":"users","target":["u1"],"from":"u2","msg":{"type":"file","filename":"test.txt","secret":"1-g0XXXXua","url":"https://a1.easemob.com/XXXX/XXXX/chatfiles/d7eXXXX7444"}}'
发送文件消息响应示例
{
"path":"/messages",
"uri":"https://a1.easemob.com/XXXX/XXXX/messages",
"timestamp":1651202759190,
"organization":"XXXX",
"application":"6b5XXXX0",
"action":"post",
"data":{
"u1":"success"
},
"duration":1,
"applicationName":"XXXX"
}
发送位置消息请求示例
curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer YWMtP5n9zvOQEei7KclxPqJTkgAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnXcBpfQBPGgDC09w5IdrfqG_H8_F53VLVTG0_82GXyEF8ZdMCt9-UpQ' -d '{"target_type": "users","target": ["user2"],"msg": {"type": "loc","lat": "39.966","lng":"116.322",."addr":"中国北京市海淀区中关村"},"from": "user1"}' 'http://a1.easemob.com/easemob-demo/testapp/messages'
发送位置消息响应示例
{
"action": "post",
"application": "8be024f0-e978-11e8-b697-5d598d5f8402",
"path": "/messages",
"uri": "https://a1.easemob.com/easemob-demo/testapp/messages",
"data": {
"user2": "success"
},
"timestamp": 1543922150902,
"duration": 1,
"organization": "easemob-demo",
"applicationName": "testapp"
}
发送透传消息请求示例
curl -X POST -H "Authorization:Bearer YWMtxc6K0L1aEeKf9LWFzT9xEAAAAT7MNR_9OcNq-GwPsKwj_TruuxZfFSC2eIQ" -i "https://a1.easemob.com/easemob-demo/testapp/messages" -d '{"target_type":"users","target":["user2","user3"],"msg":{"type":"cmd","action":"action1"},"from":"user1"}'
发送透传消息响应示例
{
"action" : "post",
"application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
"uri" : "https://a1.easemob.com/easemob-demo/testapp/messages",
"entities" : [ ],
"data" : {
"user2" : "success",
"user3" : "success"
},
"timestamp" : 1415167842297,
"duration" : 4,
"organization" : "easemob-demo",
"applicationName" : "testapp"
}
发送自定义消息请求示例
curl -L -X POST 'https://a1.easemob.com/easemob-demo/testapp/messages' -H 'Accept: application/json' -H 'Content-Type: application/json' -H 'Authorization: Bearer ${token}' -d '{ "target_type":"users", "target":["user2"], "msg":{"type":"custom", "customEvent":"gift_1", "customExts":{"name":"flower","size":"16","price":"100"}}, "from":"user1","ext":{"attr1":"test"}}'
发送自定义消息响应示例
{
"path": "/messages",
"uri": "https://a1.easemob.com/easemob-demo/testapp/messages",
"timestamp": 1597292981767,
"organization": "easemob-demo",
"application": "e82bcc5f-3366-4d96-a7c1-92de917ea2b0",
"action": "post",
"data": {
"user2": "success"
},
"duration": 0,
"applicationName": "testapp"
}
发送扩展消息请求示例
curl -X POST -H "Authorization:Bearer YWMtxc6K0L1aEeKf9LWFzT9xEAAAAT7MNR_9OcNq-GwPsKwj_TruuxZfFSC2eIQ" -i "https://a1.easemob.com/easemob-demo/testapp/messages" -d '{"target_type":"users","target":["user2","user3"],"msg":{"type":"txt","msg":"testmessage"},"from":"user1","ext":{"attr1":"test"}}'
发送扩展消息响应示例
{
"action" : "post",
"application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
"uri" : "https://a1.easemob.com/easemob-demo/testapp/messages",
"entities" : [ ],
"data" : {
"user2" : "success",
"user3" : "success"
},
"timestamp" : 1415167842297,
"duration" : 4,
"organization" : "easemob-demo",
"applicationName" : "testapp"
}
状态码
状态码 | 描述 |
---|---|
200 | 请求成功。 |
401 | 鉴权失败(无 token,token 错误或者过期),请重新获取 token 再试。 |
429,503 或者其他 5xx | 单位时间内请求过多,请稍后重试。 |
500 | 服务器内部错误,一般是 mysql 错误。如果问题持续存在,请联系我们的技术支持团队。 |
文件上传
接口描述
环信即时通讯 IM 使用 REST 的方式来实现语音和图片等文件的上传下载。同时,为了保证聊天文件的安全,我们的 API 保证了以下几点:
- 上传文件的大小不能超过 10 M,超过会上传失败。
- 在上传文件的时候可以选择是否限制访问权限,如果选择限制的话,会在上传请求完成后返回一个 secret,只有知道这个 secret,并且是 app 的注册用户,才能够下载文件。如果选择不限制的话,则只要是 app 的注册用户就能够下载。
- 如选择加 secret 限制的话,消息回调(包含发送前回调和发送后回调)、历史消息这些功能中涉及下载文件时,都需要在下载 url 中拼接 secret,才能正常下载文件;
- 拼接规则如下:
{{url}}?share-secret={{secret}}
基本信息
方法:POST
接入点:https://{host}/{org_name}/{app_name}/chatfiles
路径参数
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
host | String | 必需 | 你在环信即时通讯 IM 管理后台注册项目时所在的集群服务器地址。 |
org_name | String | 必需 | 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。 |
app_name | String | 必需 | 你在环信即时通讯 IM 管理后台注册项目时填入的应用名称。 |
请求头
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
Content-Type | String | 非必需 | multipart/form-data 上传文件会自动填充这个头。 |
Authorization | String | 必需 | Bearer ${token} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。 |
restrict-access | Bool | 非必需 | 控制文件是否可以被任何人获取,这个值为 true,返回结果中会添加一个 share-secret 值。再次访问文件需要用到这个值。 |
表单数据
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
file | String | 必需 | 文件本地路径。 |
响应体
在状态码中查看 entities 字段包含的信息
参数 | 描述 |
---|---|
uuid | 文件唯一 ID,指定是哪个文件,发送消息时需要用到。 |
type | type 是消息类型,包括以下几种: •txt :文本消息; •img :图片消息; •loc :位置消息; •audio :语音消息; •video :视频消息; •file :文件消息; •cmd :透传消息。 |
share-secret | 加密后的字符串,以后访问文件会需要。 |
请求示例
curl -X POST https://a1.easemob.com/easemob-demo/testapp/chatfiles -H 'Authorization: Bearer YWMtS1pRuFa-EemixAMhJgmGUAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFp57yd7QBPGgDNLstNggrzgHV3JAbqbznTptqLhpG0fTOCaBFJZgduZA' -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' -H 'restrict-access: true' -F file=@/Users/test/9.2/easemob/image/IMG_2953.JPG
注意:上述请求示例中 /Users/test/9.2/easemob/image/IMG_2953.JPG
,为环信即时通讯 IM 的本地文件路径,使用时请替换为自己的文件路径,否则会请求失败。
响应示例
{
"action": "post",
"application": "8be024f0-e978-11e8-b697-5d598d5f8402",
"path": "/chatfiles",
"uri": "https://a1.easemob.com/easemob-demo/testapp/chatfiles",
"entities": [
{
"uuid": "5fd74830-56be-11e9-822a-81ea50bb049d",
"type": "chatfile",
"share-secret": "X9dIOla-EemnFYUgtUZLGyqG9Y-S01eL_ysw27NqTV1_g7Yc"
}
],
"timestamp": 1554371126338,
"duration": 0,
"organization": "easemob-demo",
"applicationName": "testapp"
}
响应码
状态码 | 描述 |
---|---|
200 | 请求成功。 |
401 | 鉴权失败(无 token,token 错误或者过期),请重新获取 token 再试。 |
429,503 或者其他 5xx | 单位时间内请求过多。请稍后重试。 |
500 | 服务器内部错误,一般是 mysql 错误。 如果问题持续存在,请联系我们的技术支持团队。 |
下载语音/图片文件/缩略图
接口描述
这里需要注意的就是,如果上传文件时候选择了文件不共享,需要在请求头中带上上面返回的 share-secret
和当前登录用户的 token 才能够下载。
基本信息
方法:GET
接入点:https://{host}/{org_name}/{app_name}/chatfiles/{uuid}
路径参数
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
host | String | 必需 | 你在环信即时通讯 IM 管理后台注册项目时所在的集群服务器地址。 |
org_name | String | 必需 | 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。 |
app_name | String | 必需 | 你在环信即时通讯 IM 管理后台注册项目时填入的应用名称。 |
uuid | String | 必需 | 上传成功后返回的唯一标识。 |
请求头
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
accept | string | 必需 | application/octet-stream 以二进制流的形式接收文件。 |
Authorization | string | 必需 | Bearer ${token} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。 |
share-secret | string | 非必需 | 上传成功后需要加密时候返回,访问加密后的文件必须有。 |
请求示例(以下载图片为例)
curl -X GET -H 'Accept: application/octet-stream' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' -H 'share-secret: f0Vr-uyyEeiHpHmsu53Togur4ngZYgyLkdfsZ4xo2Z0cSBnB' 'http://a1.easemob.com/easemob-demo/testapp/chatfiles/7f456bf0-ecb2-11e8-b630-777db304f26c'-o /Users/test/easemob/image/image.JPG
注意:上述请求示例中 /Users/test/easemob/image/image.JPG
为环信即时通讯 IM 的本地文件路径,使用时请替换为自己的文件路径,否则会请求失败。
响应示例
{
//语音/图片文件内容
}
响应码
状态码 | 描述 |
---|---|
200 | 请求成功。 |
401 | 鉴权失败(无 token,token 错误或者过期),请重新获取 token 再试。 |
404 | 资源不存在。 |
429,503 或者其他 5xx | 单位时间内请求过多。请稍后重试。 |
500 | 服务器内部错误,一般是 mysql 错误。如果问题持续存在,请联系我们的技术支持团队。 |
下载缩略图
环信即时通讯 IM 支持在服务器端自动的创建图片的缩略图。可以先下载缩略图,当用户有需求的时候,再下载大图。 这里和下载大图唯一不同的就是 header 中多了一个 “thumbnail: true”,当服务器看到过来的请求的 header 中包括这个的时候,就会返回缩略图,否则返回原始大图。
需要在请求时对应填写 {file_uuid}
,需要获取文件返回的 UUID 。
请求头参数
参数 | 参数类型 | 是否必需 | 说明 |
---|---|---|---|
Content-Type | String | 必需 | application/json |
Authorization | String | 必需 | Bearer ${token} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。 |
thumbnail | String | 非必需 | 当上传文件为文件并且设置了缩略图时候,可以选择性下载缩略图。 |
请求示例
curl -X GET -H 'Accept: application/octet-stream' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' -H 'share-secret: f0Vr-uyyEeiHpHmsu53Togur4ngZYgyLkdfsZ4xo2Z0cSBnB' -H 'thumbnail: true' 'http://a1.ago ra.com/easemob-demo/testapp/chatfiles/7f456bf0-ecb2-11e8-b630-777db304f26c'
响应示例
返回值 200,表示下载缩略图成功
{
//缩略图信息
}
返回值 401,未授权 [无 token、token 错误、token 过期]
{
"error": "auth_bad_access_token",
"timestamp": 1542350943210,
"duration": 0,
"exception": "org.apache.usergrid.rest.exceptions.SecurityException",
"error_description": "Unable to authenticate due to corrupt access token"
}
响应码
状态码 | 描述 |
---|---|
200 | 请求成功。 |
401 | 鉴权失败(无 token,token 错误或者过期),请重新获取 token 再试。 |
404 | 资源不存在。 |
429,503 或者其他 5xx | 单位时间内请求过多。请稍后重试。 |
500 | 服务器内部错误,一般是 mysql 错误。如果问题持续存在,请联系我们的技术支持团队。 |
获取历史消息文件
环信即时通讯 IM 支持通过 REST API 接口导出聊天记录。聊天记录的导出若异常,原因可能是接口限流,请稍后重试。
接口描述
导出聊天记录接口不是实时接口,获取成功存在一定的延时,不能够作为实时拉取消息的接口使用。以下 API 均需要企业管理员权限才能访问。此接口一次只能获取一个小时的历史消息。
基本信息
方法:GET
接入点:https://{host}/{org_name}/{app_name}/chatmessages/${time}
路径参数
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
host | String | 必需 | 你在环信即时通讯 IM 管理后台注册项目时所在的集群服务器地址。 |
org_name | String | 必需 | 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。 |
app_name | String | 必需 | 你在环信即时通讯 IM 管理后台注册项目时填入的应用名称。 |
time | String | 必需 | 时间,每次只能获取一小时的消息,格式为 yyyyMMddHH 如 2018112717 。 |
请求头
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
Content-Type | string | 必需 | 内容类型 application/json |
Authorization | string | 必需 | Bearer ${token} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。详见使用 app token 鉴权。 |
响应体
参数 | 说明 |
---|---|
url | 聊天记录文件下载地址。 |
请求示例
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer YWMtVVK6cPFqEeif2wnxtHDB7AAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnT6x89wBPGgCnBeC15W5VAU5kW2f80QS3_SQSnbEjyOtg8XCcmkvUXw' 'http://a1.easemob.com/easemob-demo/testapp/chatmessages/2018112717'
响应示例
{
"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。
状态码
状态码 | 描述 |
---|---|
200 | 请求成功。 |
401 | 鉴权失败(无 token,token 错误或者过期),请重新获取 token 再试。 |
429,503 或者其他 5xx | 单位时间内请求过多,请稍后重试。 |
500 | 服务器内部错误,一般是 mysql 错误。 如果问题持续存在,请联系我们的技术支持团队。 |
因为历史记录文件生成需要一定时间,建议用户在取得历史记录时要间隔一个小时,例如 2016/12/10 09:00 之后,可以开始下载 2016/12/10 07:00 ~ 08:00 的消息历史记录。
不同套餐版本对应不同的消息存储时间。免费版 3 天、专业版 7 天、旗舰版 90 天、尊享版 180 天。附件消息(包括文图片、语音、视频、文件消息)保存 7 天。
聊天记录数据结构
聊天记录的数据格式主要字段的描述说明:
参数 | 参数类型 | 说明 |
---|---|---|
msg_id | String | 消息 ID。 |
timestamp | long | 消息发送时间。 |
from | String | 发送人 username。 |
to | String | 接收人的 username 或者接收 group 的 ID。 |
chat_type | String | 用来判断单聊、群聊还是聊天室。 • chat : 单聊; • groupchat : 群聊; • chatroom : 聊天室。 |
payload | Json | 消息 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 | Json | 消息内容。 |
type | String | “txt”,文本消息类型。 |
文本类型消息格式示例
"bodies": [{"msg":"welcome to easemob!", "type":"txt"}]
图片消息
对应上述消息的 bodies 参数,对图片类型消息参数说明:
参数 | 参数类型 | 说明 |
---|---|---|
file_length | Long | 图片附件大小(单位:字节)。 |
filename | String | “image.jpg”, 图片名称,带图片格式。 |
secret | String | 在上传图片后会返回字符串,只有含有 secret 才能够下载此图片。 |
size | Json | 图片长、宽尺寸。 |
type | String | “img”,图片消息类型。 |
url | String | 上传图片消息地址,在上传成功后会返回 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 | String | “地址”要发送的地址文字内容描述。 |
lat | Long | 纬度。 |
lng | Long | 经度。 |
type | String | “loc”,位置消息类型。 |
地理位置类型消息格式示例:
"bodies": [
{
"addr":"西城区西便门桥 ",
"lat":39.9053,
"lng":116.36302,
"type":"loc"
}]
语音消息
对应上述消息的 bodies 参数,对语音类型消息参数说明:
参数 | 参数类型 | 说明 |
---|---|---|
file_length | Long | 语音附件大小(单位:字节)。 |
filename | String | “audio,amr”,语音文件,带文件格式。 |
secret | String | 在上传语音后会返回字符串,只有含有 secret 才能够下载此语音文件。 |
length | Int | 语音时间(单位:秒)。 |
type | String | “audio”,语音消息类型。 |
url | String | 上传语音文件地址,上传成功后返回 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 | Long | 视频附件大小(单位:字节)。 |
filename | String | “video,mp4”,视频文件,带文件格式。 |
secret | String | 在上传视频后会返回字符串,只有含有 secret 才能够下载此视频文件。 |
length | Int | 视频播放长度(单位:秒)。 |
size | Json | 视频缩略图长、宽尺寸。 |
thumb | String | 上传视频缩略图远程地址,在上传视频缩略图后会返回 UUID。 |
thumb_secret | String | 在上传视频缩略图后会返回字符串,只有含有 secret 才能够下载此视频缩略图。 |
type | String | “video”,视频消息类型。 |
url | String | 上传视频地址,在上传成功后会返回 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 | Long | 文件大小(单位:字节)。 |
filename | String | “file.zip”,文件名称,带文件格式。 |
secret | String | 在上传文件后会返回字符串,只有含有 secret 才能够下载此文件。 |
type | String | “file”,图片消息类型。 |
url | String | 上传文件的地址,在上传成功后会返回 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"
}
]
透传消息
对应上述消息的 bodies 参数,对透传类型消息参数说明:
参数 | 参数类型 | 说明 |
---|---|---|
action | String | 自定义的 action。 |
type | String | “cmd”,透传消息。 |
透传类型消息格式示例:
"bodies":
[
{
"action":"run",
"type":"cmd"
}
]
自定义消息
对应上述消息的 bodies 参数,对自定义类型消息参数说明
参数 | 参数类型 | 说明 |
---|---|---|
customExts | Json | 用户自定义的事件属性。 |
customEvent | String | 用户自定义的事件类型。 |
type | String | “custom”,自定义消息类型。 |
自定义类型消息格式示例:
"bodies":
[
{
"customExts":
{
"name":"flower",
"size":"16",
"price":"100"
},
"customEvent":"gift_1",
"type":"custom"
}
]
服务端消息撤回
应用管理员可调用接口撤回发送的消息,默认时限为 2 分钟,如需调整请联系环信商务经理。
REST 消息撤回赋予了应用管理员对消息的撤回能力,可以对不良消息进行人工处理。
基本信息
方法:POST
接入点:https://{host}/{org_name}/{app_name}/messages/recall
请求头参数
参数 | 参数类型 | 是否必需 | 说明 |
---|---|---|---|
Content-Type | String | 必需 | 内容类型 application/json |
Authorization | String | 必需 | Bearer ${token} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。 |
请求体参数
参数 | 参数类型 | 是否必需 | 说明 |
---|---|---|---|
msg_id | String | 必需 | 撤回消息的消息 ID。 |
to | String | 必需 | 撤回消息的接收方。如果不提供则消息体找不到就撤回不了。单聊为接收方用户名称,群组为群 ID,聊天室为聊天室 ID。 |
chat_type | String | 必需 | 撤回消息的三种消息类型: - chat :单聊 ;- group_chat :群聊 ;- chatroom :聊天室 。 |
from | String | 非必需 | 消息撤回方,不传默认使用的是 admin,默认消息撤回方为原消息发送者。你可以通过用户 ID 指定消息撤回方。 |
force | bool | 必需 | 是否为强制撤回: - true :是,即超过服务器保存消息时间消息也可以被撤回,具体见服务器消息保存时长;- false :否,若设置的消息撤回时限超过服务端的消息保存时间,请求消息撤回时消息可能由于过期已在服务端删除,消息撤回请求会失败,即无法从收到该消息的客户端撤回该消息。 |
响应体参数
在返回值中查看 msgs 字段包含的信息:
参数 | 说明 |
---|---|
msg_id | 需要撤回的消息 ID。 |
recalled | 返回结果,成功是 yes 。 |
from | 消息撤回方,这里是 admin 表示通过 REST 接口撤回。 |
to | 撤回消息送达方,用户 ID 或者群组 ID。 |
chattype | 撤回消息的消息类型:单聊 chat ,群聊 group_chat ,聊天室 chatroom 三种类型。 |
请求示例
curl -i -X POST -H
"Authorization: Bearer YWMtnIF_ZI-GEea1KgfxnnDmKAAAAVjnsTKe0OE4vMOBWCtOcrB-56YcrhOHMho"
"https://a1.easemob.com/{org_name}/{app_name}/messages/recall" -d
'{
"msgs": [
{
"msg_id": "532680552327682060",
"to": "user1",
"chat_type": "chat",
"from": "op_user1",
"force": true,
},
{
"msg_id": "532680552123456789",
"to": "groupId",
"chat_type": "groupchat", // 单聊为 `chat`,群组消息为 `groupchat`,聊天室消息为 `chatroom`。
"from": "op_user1",
"force": false
}
],
}'
响应示例
成功结果:
{
“path”: “/messages/recall”,
“uri”: “https:%%//%%a1.easemob.com/easemob-demo/chatdemoui/messages”,
“timestamp”: 1582782737304,
“organization”: “easemob-demo”,
“application”: “82d0bbe0-d2a3-11e8-a0af-cb2ab3ce6167”,
“action”: “post”,
“data”: {
“msgs”: [ {
“msg_id”: “682585701976385679”,
“recalled”: “yes”,
“from”: “op_user1”,
“to”: “hxtest1”,
“chattype”: “chat”
} ]
},
“duration”: 3,
“applicationName”: “chatdemoui” }
失败结果:
recalled:撤回结果,有以下几种情况:
- ”can’t find msg to”:未找到撤回消息的接收⽅;
- ”exceed recall time limit”:消息撤回时间超时 ;
- ”not_found msg”:消息过期或已被撤回;
- ”internal error”:后端服务出现异常。
{
"msgs":
[
{ "msg_id":"673296835082717140",
"recalled":"not_found msg"
},
{
"msg_id":"673296797703079892",
"recalled":"not_found msg"
}
]
}
撤回消息服务没有在即时通讯云管理后台开通,返回示例如下:
{
"error":"forbidden_op",
"exception":"EasemobForbiddenOpException",
"timestamp":1644402553845,
"duration":0,
"error_description":"message recall service is unopened"
}
响应码
状态码 | 描述 |
---|---|
200 | 请求成功。 |
401 | 鉴权失败(无 token,token 错误或者过期),请重新获取 token 再试。 |
403 | 撤回失败。 |
429,503 或者其他 5xx | 单位时间内请求过多。请稍后重试。 |
500 | 服务器内部错误。如果问题持续存在,请联系我们的技术支持团队。 |
服务端单向删除会话
基本信息
方法:DELETE
接入点:https://{host}/{orgName}/{appName}/users/{userName}/user_channel
路径参数
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
host | String | 必需 | 你在环信即时通讯云控制台注册项目时所在的集群服务器地址。 |
org_name | String | 必需 | 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。 |
app_name | String | 必需 | 你在环信即时通讯云控制台注册项目时填入的应用名称。 |
userName | String | 必需 | 要删除会话的用户的唯一标识符,即 user ID。 |
请求头参数
参数 | 参数类型 | 是否必需 | 说明 |
---|---|---|---|
Content-Type | String | 必需 | 内容类型 application/json |
Authorization | String | 必需 | Bearer ${token} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。 |
请求体参数
参数 | 参数类型 | 是否必需 | 说明 |
---|---|---|---|
channel | String | 必需 | 要删除的会话 ID。 |
type | String | 必需 | type: 会话类型。 - chat :单聊会话;- groupchat :群聊会话。 |
delete_roam | bool | 必需 | 是否删除服务端消息,不允许为空。 - true :是;- false :否。 |
响应参数
参数 | 说明 |
---|---|
result | 删除结果,ok 表示成功,失败则直接返回错误码和原因。 |
请求示例
curl -X DELETE -H "Authorization: Bearer YWMtxc6K0L1aEeKf9LWFzT9xEAAAAT7MNR_9OcNq-GwPsKwj_TruuxZfFSC2eIQ" "https://a1.easemob.com/easemob-demo/test-app/users/u1/user_channel" -d '{"channel":"u2", "type":"chat","delete_roam": true}'
响应示例
{
"path": "/users/user_channel",
"uri": "https://a1.easemob.com/easemob-demo/test-app/users/u1/user_channel",
"timestamp": 1638440544078,
"organization": "easemob-demo",
"application": "c3624975-3d51-4b0a-9da2-ee91ed4c5a76",
"entities": [],
"action": "delete",
"data": {
"result": "ok"
},
"duration": 3,
"applicationName": "test-app"
}
响应码
状态码 | 描述 |
---|---|
200 | 请求成功。 |
401 | 鉴权失败(无 token,token 错误或者过期),请重新获取 token 再试。 |
404 | 资源不存在。 |
429,503 或者其他 5xx | 单位时间内请求过多。请稍后重试。 |
500 | 服务器内部错误,一般是 mysql 错误。如果问题持续存在,请联系我们的技术支持团队。 |