发送消息

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

新版文档见：消息管理。

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

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

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

流程说明

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

发送文本消息

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

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

HTTP Request

方法：POST

接入点：

不返回消息 ID：https://{host}/{org_name}/{app_name}/messages
返回消息 ID：https://{host}/{org_name}/{app_name}/messages?useMsgId=true

Request Headers

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

Request Body

参数	类型	是否必需	说明
`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”，表示发送消息时只有接收方在线时，才进行消息投递。若接收方离线，将不会收到此条消息。

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 在线测试

发送图片消息

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

HTTP Request

	/{org_name}/{app_name}/messages

Request Headers

参数	说明
Content-Type	application/json
Authorization	Bearer ${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-Type	application/json
Authorization	Bearer ${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-Type	application/json
Authorization	Bearer ${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-Type	application/json
Authorization	Bearer ${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-Type	application/json
Authorization	Bearer ${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-Type	application/json
Authorization	Bearer ${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-Type	application/json
Authorization	Bearer ${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

—-

上一页：用户体系集成

下一页：群组管理

目录

发送消息

流程说明

发送文本消息

HTTP Request

Request Headers

Request Body

Response Body

发送文本消息（发送给所有用户，消息无需同步给发送方）请求示例

发送文本消息（仅发送给在线用户，消息同步给发送方，返回消息 ID）请求示例

发送文本消息（发送给所有用户，消息无需同步给发送方）响应示例

发送文本消息（仅发送给在线用户，消息同步给发送方，返回消息 ID）响应示例

发送图片消息

HTTP Request

Request Headers

Request Body

Response Body

请求示例

可能返回的结果示例

发送语音消息

HTTP Request

Request Headers

Request Body

Response Body

请求示例

可能返回的结果示例

发送视频消息

HTTP Request

Request Headers

Request Body

Response Body

请求示例

可能返回的结果示例

发送位置消息

HTTP Request

Request Headers

Request Body

Response Body

请求示例

可能返回的结果示例

发送透传消息

HTTP Request

Request Headers

Request Body

Response Body

请求示例

可能返回的结果示例

发送自定义消息

HTTP Request

Request Headers

Request Body

Response Body

请求示例

可能返回的结果示例

发送扩展消息

HTTP Request

Request Headers

Request Body

Response Body

请求示例

可能返回的结果示例

iOS扩展消息