目录

发送消息

更新时间:2021-12-31 该文档已不再维护,请看新版 3.X 文档。

新版文档见:消息管理


本篇介绍消息相关的 REST API,包括在服务端实现用户到用户,或用户到群组的消息发送与接收,支持消息类型包括文本消息,图片消息,语音消息,视频消息,透传消息和自定义消息。

发送文件类型消息要先把文件上传到环信服务器,参考文档:文件上传下载

REST 接口发消息,不会判断环信 ID 在 App Key 下是否存在。

流程说明

消息类型说明
发送文本/透传消息直接编辑内容发送。
发送图片/语音/视频消息需要先上传这三类文件,从接口返回值中获取到相应的参数,按照 API 要求编辑到消息体中然后的发送。

发送文本消息

给一个或者多个用户,或者一个或者多个群组发送消息,并且通过可选的 from 字段让接收方看到发送方是不同的人。同时,支持扩展字段,通过 ext 属性,APP 可以发送自己专属的消息结构。

注意:在调用程序中,请求体如果超过 50KB 会导致 413 错误,需要拆成几个更小的请求体重试,同时用户消息+扩展字段的长度在 40KB 以内。详见接口限流说明

HTTP Request

方法:POST

接入点:

Request Headers

参数说明
Content-Typeapplication/json
AuthorizationBearer ${token}
host你在环信即时通讯 IM 管理后台注册项目时所在的集群服务器地址。

Request Body

参数类型是否必需说明
target_typeString必需发送的目标类型:users:给用户发消息,chatgroups:给群发消息,chatrooms:给聊天室发消息。
targetList必需发送的目标;注意这里需要用数组,数组内添加的最大用户数默认 600 个,即使只有一个用户,也要用数组 ['u1'];给用户发送时数组元素是用户名,给群组发送时,数组元素是 groupid。
msgJson必需具体消息内容参数集,参考以下不同类型消息。
fromString非必需表示消息发送者;无此字段 Server 会默认设置为 “from”:“admin”,有 from 字段但值为空串 (“”) 时请求失败。
sync_device Bool 非必需 消息发送成功后,是否将消息同步给发送方。
-true:是;
- (默认)false:否。
routetype String 非必需 该参数值为“ROUTE_ONLINE”, 表示发送消息时只有接收方在线时,才进行消息投递。若接收方离线,将不会收到此条消息。

Response Body

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

参数说明
username接受消息的用户名
success表示消息发送成功

发送文本消息(发送给所有用户,消息无需同步给发送方)请求示例

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"
}

如果返回结果是429、503或者其他5xx,有可能代表该接口被限流了,请稍后再试。详见接口限流说明

使用 Easemob REST API 在线测试


发送图片消息

给一个或者多个用户,或者一个或者多个群组发送消息,并且通过可选的 from 字段让接收方看到发送方是不同的人。同时,支持扩展字段,通过 ext 属性,APP 可以发送自己专属的消息结构。

注意:在调用程序中,请求体如果超过 5kb 会导致413错误,需要拆成几个更小的请求体重试。详见接口限流说明

HTTP Request

/{org_name}/{app_name}/messages

Request Headers

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

Request Body

参数说明
target_type发送的目标类型;users:给用户发消息,chatgroups:给群发消息,chatrooms:给聊天室发消息
target发送的目标;注意这里需要用数组,数组内添加的最大用户数默认600个,即使只有一个用户,也要用数组 ['u1'];给用户发送时数组元素是用户名,给群组发送时,数组元素是groupid
msg消息内容
type消息类型;txt:文本消息,img:图片消息,loc:位置消息,audio:语音消息,video:视频消息,file:文件消息
url域名/orgname/appname/chatfiles/成功上传文件返回的UUID。参考请求示例
filename图片名称
secret成功上传文件后返回的secret
size图片尺寸;height:高度,width:宽度
from表示消息发送者;无此字段Server会默认设置为“from”:“admin”,有from字段但值为空串(“”)时请求失败

Response Body

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

参数说明
username接受消息的用户名
success表示消息发送成功

请求示例

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}}}'

可能返回的结果示例

返回值200,表示消息发送成功

{
  "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"
}

返回值400,表示 massage 结构错误

{
  "error": "json_parse",
  "timestamp": 1543922465246,
  "duration": 0,
  "exception": "org.codehaus.jackson.JsonParseException",
  "error_description": "Unexpected character ('}' (code 125)): was expecting double-quote to start field name\n at [Source: java.io.BufferedInputStream@7ba7eef2; line: 11, column: 2]"
}

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

{
  "error": "auth_bad_access_token",
  "timestamp": 1543922590032,
  "duration": 0,
  "exception": "org.apache.usergrid.rest.exceptions.SecurityException",
  "error_description": "Unable to authenticate due to corrupt access token"
}

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

使用 Easemob REST API 在线测试


发送语音消息

发送语音文件,需要先上传语音文件,然后再发送此消息。(URL 中的 UUID 和 secret 可以从上传后的 response 获取)

注意:在调用程序中,请求体如果超过 5kb 会导致413错误,需要拆成几个更小的请求体重试。详见接口限流说明

HTTP Request

/{org_name}/{app_name}/messages

Request Headers

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

Request Body

参数说明
target_type发送的目标类型;users:给用户发消息,chatgroups:给群发消息,chatrooms:给聊天室发消息
target发送的目标;注意这里需要用数组,数组内添加的最大用户数默认600个,即使只有一个用户,也要用数组 ['u1'];给用户发送时数组元素是用户名,给群组发送时,数组元素是groupid
msg消息内容
type消息类型;txt:文本消息,img:图片消息,loc:位置消息,audio:语音消息,video:视频消息,file:文件消息
url成功上传文件返回的UUID
filename语音名称
secret成功上传文件后返回的secret
length语音时间(单位:秒)
from表示消息发送者;无此字段Server会默认设置为“from”:“admin”,有from字段但值为空串(“”)时请求失败

Response Body

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

参数说明
username接受消息的用户名
success表示消息发送成功

请求示例

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" }'

可能返回的结果示例

返回值200,表示消息发送成功

{
  "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"
}

返回值400,表示 massage 结构错误

{
  "error": "json_parse",
  "timestamp": 1543922465246,
  "duration": 0,
  "exception": "org.codehaus.jackson.JsonParseException",
  "error_description": "Unexpected character ('}' (code 125)): was expecting double-quote to start field name\n at [Source: java.io.BufferedInputStream@7ba7eef2; line: 11, column: 2]"
}

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

{
  "error": "auth_bad_access_token",
  "timestamp": 1543922590032,
  "duration": 0,
  "exception": "org.apache.usergrid.rest.exceptions.SecurityException",
  "error_description": "Unable to authenticate due to corrupt access token"
}

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

使用 Easemob REST API 在线测试


发送视频消息

发送视频消息,需要先上传视频文件和视频缩略图文件,然后再发送此消息。(URL 中的 UUID 和 secret 可以从上传后的 response 获取)

注意:在调用程序中,请求体如果超过 5kb 会导致413错误,需要拆成几个更小的请求体重试。详见接口限流说明

HTTP Request

/{org_name}/{app_name}/messages

Request Headers

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

Request Body

参数说明
target_type发送的目标类型;users:给用户发消息,chatgroups:给群发消息,chatrooms:给聊天室发消息
target发送的目标;注意这里需要用数组,数组内添加的最大用户数默认600个,即使只有一个用户,也要用数组 ['u1'];给用户发送时数组元素是用户名,给群组发送时,数组元素是groupid
type消息类型;txt:文本消息,img:图片消息,loc:位置消息,audio:语音消息,video:视频消息,file:文件消息
filename视频文件名称
thumb成功上传视频缩略图返回的UUID
length视频播放长度
secret成功上传视频文件后返回的secret
file_length视频文件大小(单位:字节)
thumb_secret成功上传视频缩略图后返回的secret
url成功上传视频文件返回的UUID

Response Body

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

参数说明
username接受消息的用户名
success表示消息发送成功

请求示例

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"}}'

可能返回的结果示例

返回值200,表示消息发送成功

{
  "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"
}

返回值400,表示 massage 结构错误

{
  "error": "json_parse",
  "timestamp": 1543922465246,
  "duration": 0,
  "exception": "org.codehaus.jackson.JsonParseException",
  "error_description": "Unexpected character ('}' (code 125)): was expecting double-quote to start field name\n at [Source: java.io.BufferedInputStream@7ba7eef2; line: 11, column: 2]"
}

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

{
  "error": "auth_bad_access_token",
  "timestamp": 1543922590032,
  "duration": 0,
  "exception": "org.apache.usergrid.rest.exceptions.SecurityException",
  "error_description": "Unable to authenticate due to corrupt access token"
}

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

使用 Easemob REST API 在线测试


发送位置消息

位置消息:获取到地址的经纬度,填写正确地址发送。

注意:在调用程序中,请求体如果超过 5kb 会导致413错误,需要拆成几个更小的请求体重试,同时用户消息+扩展字段的长度在4k字节以内。详见接口限流说明

HTTP Request

/{org_name}/{app_name}/messages

Request Headers

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

Request Body

参数说明
target_type发送的目标类型;users:给用户发消息,chatgroups:给群发消息,chatrooms:给聊天室发消息
target发送的目标;注意这里需要用数组,数组内添加的最大用户数默认600个,即使只有一个用户,也要用数组 ['u1'];给用户发送时数组元素是用户名,给群组发送时,数组元素是groupid
msg消息内容
type消息类型;txt:文本消息,img:图片消息,loc:位置消息,audio:语音消息,video:视频消息,file:文件消息
from表示消息发送者;无此字段Server会默认设置为“from”:“admin”,有from字段但值为空串(“”)时请求失败

Response Body

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

参数说明
username接受消息的用户名
success表示消息发送成功

请求示例

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'

可能返回的结果示例

返回值200,表示消息发送成功

{
  "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"
}

返回值400,表示 massage 结构错误

{
  "error": "json_parse",
  "timestamp": 1543922465246,
  "duration": 0,
  "exception": "org.codehaus.jackson.JsonParseException",
  "error_description": "Unexpected character ('}' (code 125)): was expecting double-quote to start field name\n at [Source: java.io.BufferedInputStream@7ba7eef2; line: 11, column: 2]"
}

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

{
  "error": "auth_bad_access_token",
  "timestamp": 1543922590032,
  "duration": 0,
  "exception": "org.apache.usergrid.rest.exceptions.SecurityException",
  "error_description": "Unable to authenticate due to corrupt access token"
}

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

使用 Easemob REST API 在线测试


发送透传消息

透传消息:不会在客户端提示(铃声、震动、通知栏等),也不会有 APNS 推送(苹果推送),但可以在客户端监听到,具体功能可以根据自身自定义。

注意:在调用程序中,请求体如果超过 5kb 会导致413错误,需要拆成几个更小的请求体重试。详见接口限流说明

HTTP Request

/{org_name}/{app_name}/messages

Request Headers

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

Request Body

参数说明
target_type发送的目标类型;users:给用户发消息,chatgroups:给群发消息,chatrooms:给聊天室发消息
target发送的目标;注意这里需要用数组,数组内添加的最大用户数默认600个,即使只有一个用户,也要用数组 ['u1'];给用户发送时数组元素是用户名,给群组发送时,数组元素是groupid
msg消息内容
type消息类型;txt:文本消息,img:图片消息,loc:位置消息,audio:语音消息,video:视频消息,file:文件消息,cmd:透传消息
from表示消息发送者;无此字段Server会默认设置为“from”:“admin”,有from字段但值为空串(“”)时请求失败

Response Body

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

参数说明
username接受消息的用户名
success表示消息发送成功

请求示例

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"}'

可能返回的结果示例

返回值200,表示消息发送成功

{
  "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"
}

返回值400,表示 massage 结构错误

{
  "error": "json_parse",
  "timestamp": 1543922465246,
  "duration": 0,
  "exception": "org.codehaus.jackson.JsonParseException",
  "error_description": "Unexpected character ('}' (code 125)): was expecting double-quote to start field name\n at [Source: java.io.BufferedInputStream@7ba7eef2; line: 11, column: 2]"
}

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

{
  "error": "auth_bad_access_token",
  "timestamp": 1543922590032,
  "duration": 0,
  "exception": "org.apache.usergrid.rest.exceptions.SecurityException",
  "error_description": "Unable to authenticate due to corrupt access token"
}

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

使用 Easemob REST API 在线测试


发送自定义消息

自定义消息:若普通消息类型不满足用户消息需求,可以使用自定义消息来自定义消息类型,主要是通过message的customEvent字段实现。

注意:在调用程序中,请求体如果超过 5kb 会导致413错误,需要拆成几个更小的请求体重试。详见接口限流说明

HTTP Request

/{org_name}/{app_name}/messages

Request Headers

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

Request Body

参数说明
target_type发送的目标类型;users:给用户发消息,chatgroups:给群发消息,chatrooms:给聊天室发消息
target发送的目标;注意这里需要用数组,数组内添加的最大用户数默认600个,即使只有一个用户,也要用数组 ['u1'];给用户发送时数组元素是用户名,给群组发送时,数组元素是groupid
msg消息内容
type消息类型;txt:文本消息,img:图片消息,loc:位置消息,audio:语音消息,video:视频消息,file:文件消息,custom:自定义消息
customEvent用户自定义的事件类型,必须是string,值必须满足正则表达式 [a-zA-Z0-9-_/\.]{1,32},最短1个字符 最长32个字符
customExts用户自定义的事件属性,类型必须是Map<String,String>,最多可以包含16个元素。customExts 是可选的,不需要可以不传
from表示消息发送者;无此字段Server会默认设置为“from”:“admin”,有from字段但值为空串(“”)时请求失败
ext扩展属性,由APP自己定义。可以没有这个字段,但是如果有,值不能是“ext:null”这种形式,否则出错
attr1消息的扩展内容,可以增加字段,扩展消息主要解析部分,必须是基本类型数据

Response Body

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

参数说明
username接受消息的用户名
success表示消息发送成功

请求示例

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"}}'

可能返回的结果示例

返回值200,表示消息发送成功

{
    "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"
}

返回值400,表示 massage 结构错误

{
    "error": "illegal_argument",
    "exception": "java.lang.IllegalArgumentException",
    "timestamp": 1597292940854,
    "duration": 1,
    "error_description": "target_type must be provided"
}

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

{
    "error": "unauthorized",
    "exception": "EasemobSecurityException",
    "timestamp": 1597292804746,
    "duration": 1,
    "error_description": "Unable to authenticate (OAuth)"
}

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

使用 Easemob REST API 在线测试


发送扩展消息

扩展消息:若普通消息类型不满足用户消息需求,可以使用扩展消息。任何类型的消息都支持扩展,主要是通过message的ext字段实现。

注意:在调用程序中,请求体如果超过 5kb 会导致413错误,需要拆成几个更小的请求体重试。详见接口限流说明

HTTP Request

/{org_name}/{app_name}/messages

Request Headers

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

Request Body

参数说明
target_type发送的目标类型;users:给用户发消息,chatgroups:给群发消息,chatrooms:给聊天室发消息
target发送的目标;注意这里需要用数组,数组内添加的最大用户数默认600个,即使只有一个用户,也要用数组 ['u1'];给用户发送时数组元素是用户名,给群组发送时,数组元素是groupid
msg消息内容
type消息类型,不局限与文本消息。任何消息类型都可以加扩展消息;txt:文本消息,img:图片消息,loc:位置消息,audio:语音消息,video:视频消息,file:文件消息
msg消息;随意传入都可以
from表示消息发送者;无此字段Server会默认设置为“from”:“admin”,有from字段但值为空串(“”)时请求失败
ext扩展属性,由APP自己定义。可以没有这个字段,但是如果有,值不能是“ext:null”这种形式,否则出错。Key值类型必须是NSString,Value值类型必须是NSString或者 NSNumber类型的 BOOL,int,unsigned in,long long,double。
attr1消息的扩展内容,可以增加字段,扩展消息主要解析部分,必须是基本类型数据

Response Body

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

参数说明
username接受消息的用户名
success表示消息发送成功

请求示例

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"}}'

可能返回的结果示例

返回值200,表示消息发送成功

{
  "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"
}

返回值400,表示 massage 结构错误

{
  "error": "json_parse",
  "timestamp": 1543922465246,
  "duration": 0,
  "exception": "org.codehaus.jackson.JsonParseException",
  "error_description": "Unexpected character ('}' (code 125)): was expecting double-quote to start field name\n at [Source: java.io.BufferedInputStream@7ba7eef2; line: 11, column: 2]"
}

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

{
  "error": "auth_bad_access_token",
  "timestamp": 1543922590032,
  "duration": 0,
  "exception": "org.apache.usergrid.rest.exceptions.SecurityException",
  "error_description": "Unable to authenticate due to corrupt access token"
}

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

使用 Easemob REST API 在线测试

iOS扩展消息

环信提供以下几种扩展字段:

扩展字段描述
em_push_content自定义推送显示
em_push_category向 APNs Payload 中添加 category 字段
em_push_sound自定义推送提示音
em_push_mutable_content开启 APNs 通知扩展
em_ignore_notification发送静默消息
em_force_notification设置强制推送型 APNs

—-

上一页:用户体系集成

下一页:群组管理