消息管理

更新时间:2022-05-19

本文介绍消息相关的 REST API,包括在服务端实现用户到用户或用户到群组的消息发送与接收、消息附件上传和下载、获取聊天记录、服务端消息撤回、服务端单向删除会话等。支持消息类型包括文本消息、图片消息、语音消息、视频消息、透传消息和自定义消息。

要调用环信即时通讯 RESTful API,请确保满足以下要求:

以下为常出现的响应体参数及描述:

参数 描述
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;
• “_”, “-”, “.”。
注意:
• 该参数不区分大小写,因此 Aaaa 为相同用户名;
• 请确保同一个 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:否。
routetypeString 非必需 该参数值为 “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 必需 时间,每次只能获取一小时的消息,格式为 yyyyMMddHH2018112717

请求头

参数 类型 是否必需 描述
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_typeString用来判断单聊、群聊还是聊天室。
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 消息内容。
typeString“txt”,文本消息类型。

文本类型消息格式示例

"bodies": [{"msg":"welcome to easemob!", "type":"txt"}]

图片消息

对应上述消息的 bodies 参数,对图片类型消息参数说明:

参数 参数类型 说明
file_lengthLong 图片附件大小(单位:字节)。
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 参数,对地理位置类型消息参数说明:

参数 参数类型 说明
addrString“地址”要发送的地址文字内容描述。
lat Long 纬度。
lng Long 经度。
typeString“loc”,位置消息类型。

地理位置类型消息格式示例:

"bodies": [   
  {       
    "addr":"西城区西便门桥 ",       
    "lat":39.9053,       
    "lng":116.36302,        
    "type":"loc"     
    }]

语音消息

对应上述消息的 bodies 参数,对语音类型消息参数说明:

参数 参数类型 说明
file_lengthLong 语音附件大小(单位:字节)。
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_secretString在上传视频缩略图后会返回字符串,只有含有 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_lengthLong 文件大小(单位:字节)。
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 参数,对透传类型消息参数说明:

参数 参数类型 说明
actionString自定义的 action。
type String“cmd”,透传消息。

透传类型消息格式示例:

"bodies": 
[    
  {       
  "action":"run",       
  "type":"cmd"   
  }
]

自定义消息

对应上述消息的 bodies 参数,对自定义类型消息参数说明

参数 参数类型 说明
customExts Json 用户自定义的事件属性。
customEventString用户自定义的事件类型。
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 错误。如果问题持续存在,请联系我们的技术支持团队。