差别
这里会显示出您选择的修订版和当前版本之间的差别。
两侧同时换到之前的修订记录 前一修订版 后一修订版 | 前一修订版 | ||
im:server:basics:messages [2019/04/15 10:02] jk [iOS扩展消息] |
im:server:basics:messages [2022/05/19 04:10] (当前版本) jennifer.zeng [发送消息] |
||
---|---|---|---|
行 1: | 行 1: | ||
====== 发送消息 ====== | ====== 发送消息 ====== | ||
+ | |||
+ | 更新时间:2021-12-31 该文档已不再维护,请看新版 3.X 文档。 | ||
+ | |||
+ | 新版文档见:[[ccim:rest:message|消息管理]]。 | ||
---- | ---- | ||
- | 聊天相关 API,可以发送文本消息,发送图片消息,发送语音消息,发送视频消息,发送透传消息和发送扩展消息。 | + | 本篇介绍消息相关的 REST API,包括在服务端实现用户到用户,或用户到群组的消息发送与接收,支持消息类型包括文本消息,图片消息,语音消息,视频消息,透传消息和自定义消息。 |
+ | |||
+ | 发送文件类型消息要先把文件上传到环信服务器,参考文档:[[im:server:basics:fileoperation|文件上传下载]]。 | ||
+ | |||
+ | REST 接口发消息,不会判断环信 ID 在 App Key 下是否存在。 | ||
===== 流程说明 ===== | ===== 流程说明 ===== | ||
^消息类型^说明^ | ^消息类型^说明^ | ||
- | |发送文本/透传消息|直接编辑内容发送| | + | |发送文本/透传消息|直接编辑内容发送。| |
- | |发送图片/语音/视频消息|需要先上传这三类文件,从接口返回值中获取到相应的参数,按照 API 要求编辑到消息体中然后的发送| | + | |发送图片/语音/视频消息|需要先上传这三类文件,从接口返回值中获取到相应的参数,按照 API 要求编辑到消息体中然后的发送。| |
===== 发送文本消息 ===== | ===== 发送文本消息 ===== | ||
给一个或者多个用户,或者一个或者多个群组发送消息,并且通过可选的 from 字段让接收方看到发送方是不同的人。同时,支持扩展字段,通过 ext 属性,APP 可以发送自己专属的消息结构。 | 给一个或者多个用户,或者一个或者多个群组发送消息,并且通过可选的 from 字段让接收方看到发送方是不同的人。同时,支持扩展字段,通过 ext 属性,APP 可以发送自己专属的消息结构。 | ||
<WRAP clear/> | <WRAP clear/> | ||
- | **注意**:在调用程序中,请求体如果超过 5kb 会导致413错误,需要拆成几个更小的请求体重试,同时用户消息+扩展字段的长度在40k字节以内。详见[[im:server:help:restastrict|接口限流说明]]。 | + | **注意**:在调用程序中,请求体如果超过 50KB 会导致 413 错误,需要拆成几个更小的请求体重试,同时用户消息+扩展字段的长度在 40KB 以内。详见[[im:server:help:restastrict|接口限流说明]]。 |
=== HTTP Request === | === HTTP Request === | ||
- | ^{{:im:server:ready:post.png?nolink&90 |}}^/**/{org_name}/{app_name}/messages**^ | + | 方法:''%%POST%%'' |
+ | |||
+ | 接入点: | ||
+ | * 不返回消息 ID:''%%https://{host}/{org_name}/{app_name}/messages%%'' | ||
+ | * 返回消息 ID:''%%https://{host}/{org_name}/{app_name}/messages?useMsgId=true%%'' | ||
=== Request Headers === | === Request Headers === | ||
行 24: | 行 36: | ||
|Content-Type|application/json| | |Content-Type|application/json| | ||
|Authorization|Bearer ${token}| | |Authorization|Bearer ${token}| | ||
+ | |host|你在环信即时通讯 IM 管理后台注册项目时所在的集群服务器地址。| | ||
=== Request Body === | === Request Body === | ||
- | ^参数^说明^ | + | ^参数^类型^是否必需^说明^ |
- | |target_type|发送的目标类型;users:给用户发消息,chatgroups:给群发消息,chatrooms:给聊天室发消息| | + | |''%%target_type%%''|String|必需|发送的目标类型:''%%users%%'':给用户发消息,''%%chatgroups%%'':给群发消息,''%%chatrooms%%'':给聊天室发消息。| |
- | |target|发送的目标;注意这里需要用数组,数组长度建议不大于20,即使只有一个用户,也要用数组 ['u1'];给用户发送时数组元素是用户名,给群组发送时,数组元素是groupid| | + | |''%%target%%''|List|必需|发送的目标;注意这里需要用数组,数组内添加的最大用户数默认 600 个,即使只有一个用户,也要用数组 ['u1'];给用户发送时数组元素是用户名,给群组发送时,数组元素是 groupid。| |
- | |msg|消息内容| | + | |''%%msg%%''|Json|必需|具体消息内容参数集,参考以下不同类型消息。| |
- | |type|消息类型;txt:文本消息,img:图片消息,loc:位置消息,audio:语音消息,video:视频消息,file:文件消息| | + | |''%%from%%''|String|非必需|表示消息发送者;无此字段 Server 会默认设置为 “from”:“admin”,有 from 字段但值为空串 (“”) 时请求失败。| |
- | |from|表示消息发送者;无此字段Server会默认设置为"from":"admin",有from字段但值为空串("")时请求失败| | + | |''%%sync_device%%'' |Bool |非必需 |消息发送成功后,是否将消息同步给发送方。<html><br></html> -''%%true%%'':是;<html><br></html> - (默认)''%%false%%'':否。 | |
+ | | ''%%routetype%%''| String | 非必需 | 该参数值为“ROUTE_ONLINE”, 表示发送消息时只有接收方在线时,才进行消息投递。若接收方离线,将不会收到此条消息。 | | ||
=== Response Body === | === Response Body === | ||
行 41: | 行 55: | ||
- | === 请求示例 === | + | === 发送文本消息(发送给所有用户,消息无需同步给发送方)请求示例 === |
- | <code php> | + | <code> |
- | curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer YWMtP5n9zvOQEei7KclxPqJTkgAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnXcBpfQBPGgDC09w5IdrfqG_H8_F53VLVTG0_82GXyEF8ZdMCt9-UpQ' -d '{ | + | 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' |
- | "target_type": "users", | + | |
- | "target": [ | + | |
- | "user2","user3" | + | |
- | ], | + | |
- | "msg": { | + | |
- | "type": "txt", | + | |
- | "msg": "testmessage" | + | |
- | }, | + | |
- | "from": "user1" | + | |
- | }' 'http://a1.easemob.com/easemob-demo/testapp/messages' | + | |
</code> | </code> | ||
- | === 可能返回的结果示例 === | + | === 发送文本消息(仅发送给在线用户,消息同步给发送方,返回消息 ID)请求示例 === |
+ | <code> | ||
+ | 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' | ||
+ | </code> | ||
- | **返回值200,表示消息发送成功** | + | === 发送文本消息(发送给所有用户,消息无需同步给发送方)响应示例 === |
- | <code json> | + | <code> |
- | { | + | { |
- | "action": "post", | + | "action": "post", |
- | "application": "8be024f0-e978-11e8-b697-5d598d5f8402", | + | "application": "8be024f0-e978-11e8-b697-5d598d5f8402", |
- | "path": "/messages", | + | "path": "/messages", |
- | "uri": "https://a1.easemob.com/easemob-demo/testapp/messages", | + | "uri": "https://a1.easemob.com/easemob-demo/testapp/messages", |
- | "data": { | + | "data": { |
- | "user2": "success", | + | "user2": "success", |
- | "user3": "success" | + | "user3": "success" |
- | }, | + | }, |
- | "timestamp": 1543922150902, | + | "timestamp": 1543922150902, |
- | "duration": 1, | + | "duration": 1, |
- | "organization": "easemob-demo", | + | "organization": "easemob-demo", |
- | "applicationName": "testapp" | + | "applicationName": "testapp" |
} | } | ||
</code> | </code> | ||
- | **返回值400,表示 massage 结构错误** | + | === 发送文本消息(仅发送给在线用户,消息同步给发送方,返回消息 ID)响应示例 === |
- | <code json> | + | <code> |
{ | { | ||
- | "error": "json_parse", | + | "path":"/messages", |
- | "timestamp": 1543922465246, | + | "uri":"http://a1.easemob.com/easemob-demo/testapp/messages", |
- | "duration": 0, | + | "timestamp":1644305988265, |
- | "exception": "org.codehaus.jackson.JsonParseException", | + | "organization":"easemob-demo", |
- | "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]" | + | "application":"8be024f0-e978-11e8-b697-5d598d5f8402", |
+ | "action":"post", | ||
+ | "data":{ | ||
+ | "user2":"973845988210901688", | ||
+ | "user3":"973845988210905784" | ||
+ | }, | ||
+ | "duration":0, | ||
+ | "applicationName":"testapp" | ||
} | } | ||
</code> | </code> | ||
- | **返回值401,表示未授权[无token、token错误、token过期]** | ||
- | <code json> | ||
- | { | ||
- | "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" | ||
- | } | ||
- | </code> | ||
- | 如果返回结果是<wrap em>429、503</wrap>或者其他<wrap em>5xx</wrap>,有可能代表该接口被限流了,请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]] | + | 如果返回结果是<wrap em>429、503</wrap>或者其他<wrap em>5xx</wrap>,有可能代表该接口被限流了,请稍后再试。详见[[im:server:help:restastrict|接口限流说明]] |
[[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] | [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] | ||
行 113: | 行 117: | ||
=== HTTP Request === | === HTTP Request === | ||
- | ^{{:im:server:ready:post.png?nolink&90 |}}^/**/{org_name}/{app_name}/messages**^ | + | ^{{:im:server:ready:post.png?nolink&90 |}}^**/{org_name}/{app_name}/messages**^ |
=== Request Headers === | === Request Headers === | ||
行 125: | 行 129: | ||
^参数^说明^ | ^参数^说明^ | ||
|target_type|发送的目标类型;users:给用户发消息,chatgroups:给群发消息,chatrooms:给聊天室发消息| | |target_type|发送的目标类型;users:给用户发消息,chatgroups:给群发消息,chatrooms:给聊天室发消息| | ||
- | |target|发送的目标;注意这里需要用数组,数组长度建议不大于20,即使只有一个用户,也要用数组 ['u1'];给用户发送时数组元素是用户名,给群组发送时,数组元素是groupid| | + | |target|发送的目标;注意这里需要用数组,数组内添加的最大用户数默认600个,即使只有一个用户,也要用数组 ['u1'];给用户发送时数组元素是用户名,给群组发送时,数组元素是groupid| |
|msg|消息内容| | |msg|消息内容| | ||
|type|消息类型;txt:文本消息,img:图片消息,loc:位置消息,audio:语音消息,video:视频消息,file:文件消息| | |type|消息类型;txt:文本消息,img:图片消息,loc:位置消息,audio:语音消息,video:视频消息,file:文件消息| | ||
- | |url|成功上传文件返回的UUID| | + | |url|域名/orgname/appname/chatfiles/成功上传文件返回的UUID。参考请求示例| |
|filename|图片名称| | |filename|图片名称| | ||
|secret|成功上传文件后返回的secret| | |secret|成功上传文件后返回的secret| | ||
行 144: | 行 148: | ||
<code php> | <code php> | ||
- | 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}}' | + | 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}}}' |
</code> | </code> | ||
行 155: | 行 159: | ||
"action" : "post", | "action" : "post", | ||
"application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5", | "application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5", | ||
- | "uri" : "https://a1.easemob.com/easemob-demo/testapp", | + | "uri" : "https://a1.easemob.com/easemob-demo/testapp/messages", |
"entities" : [ ], | "entities" : [ ], | ||
"data" : { | "data" : { | ||
行 204: | 行 208: | ||
=== HTTP Request === | === HTTP Request === | ||
- | ^{{:im:server:ready:post.png?nolink&90 |}}^/**/{org_name}/{app_name}/messages**^ | + | ^{{:im:server:ready:post.png?nolink&90 |}}^**/{org_name}/{app_name}/messages**^ |
=== Request Headers === | === Request Headers === | ||
行 216: | 行 220: | ||
^参数^说明^ | ^参数^说明^ | ||
|target_type|发送的目标类型;users:给用户发消息,chatgroups:给群发消息,chatrooms:给聊天室发消息| | |target_type|发送的目标类型;users:给用户发消息,chatgroups:给群发消息,chatrooms:给聊天室发消息| | ||
- | |target|发送的目标;注意这里需要用数组,数组长度建议不大于20,即使只有一个用户,也要用数组 ['u1'];给用户发送时数组元素是用户名,给群组发送时,数组元素是groupid| | + | |target|发送的目标;注意这里需要用数组,数组内添加的最大用户数默认600个,即使只有一个用户,也要用数组 ['u1'];给用户发送时数组元素是用户名,给群组发送时,数组元素是groupid| |
|msg|消息内容| | |msg|消息内容| | ||
|type|消息类型;txt:文本消息,img:图片消息,loc:位置消息,audio:语音消息,video:视频消息,file:文件消息| | |type|消息类型;txt:文本消息,img:图片消息,loc:位置消息,audio:语音消息,video:视频消息,file:文件消息| | ||
行 294: | 行 298: | ||
=== HTTP Request === | === HTTP Request === | ||
- | ^{{:im:server:ready:post.png?nolink&90 |}}^/**/{org_name}/{app_name}/messages**^ | + | ^{{:im:server:ready:post.png?nolink&90 |}}^**/{org_name}/{app_name}/messages**^ |
=== Request Headers === | === Request Headers === | ||
行 306: | 行 310: | ||
^参数^说明^ | ^参数^说明^ | ||
|target_type|发送的目标类型;users:给用户发消息,chatgroups:给群发消息,chatrooms:给聊天室发消息| | |target_type|发送的目标类型;users:给用户发消息,chatgroups:给群发消息,chatrooms:给聊天室发消息| | ||
- | |target|发送的目标;注意这里需要用数组,数组长度建议不大于20,即使只有一个用户,也要用数组 ['u1'];给用户发送时数组元素是用户名,给群组发送时,数组元素是groupid| | + | |target|发送的目标;注意这里需要用数组,数组内添加的最大用户数默认600个,即使只有一个用户,也要用数组 ['u1'];给用户发送时数组元素是用户名,给群组发送时,数组元素是groupid| |
|type|消息类型;txt:文本消息,img:图片消息,loc:位置消息,audio:语音消息,video:视频消息,file:文件消息| | |type|消息类型;txt:文本消息,img:图片消息,loc:位置消息,audio:语音消息,video:视频消息,file:文件消息| | ||
|filename|视频文件名称| | |filename|视频文件名称| | ||
行 337: | 行 341: | ||
"action" : "post", | "action" : "post", | ||
"application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5", | "application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5", | ||
- | "uri" : "https://a1.easemob.com/easemob-demo/testapp", | + | "uri" : "https://a1.easemob.com/easemob-demo/testapp/messages", |
"entities" : [ ], | "entities" : [ ], | ||
"data" : { | "data" : { | ||
行 376: | 行 380: | ||
[[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] | [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] | ||
---- | ---- | ||
+ | ===== 发送位置消息 ===== | ||
+ | 位置消息:获取到地址的经纬度,填写正确地址发送。 | ||
+ | <WRAP clear/> | ||
+ | **注意**:在调用程序中,请求体如果超过 5kb 会导致413错误,需要拆成几个更小的请求体重试,同时用户消息+扩展字段的长度在4k字节以内。详见[[im:server:help:restastrict|接口限流说明]]。 | ||
+ | === HTTP Request === | ||
+ | |||
+ | ^{{:im:server:ready:post.png?nolink&90 |}}^**/{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|表示消息发送成功| | ||
+ | |||
+ | |||
+ | === 请求示例 === | ||
+ | |||
+ | <code php> | ||
+ | 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' | ||
+ | </code> | ||
+ | |||
+ | === 可能返回的结果示例 === | ||
+ | |||
+ | **返回值200,表示消息发送成功** | ||
+ | |||
+ | <code json> | ||
+ | { | ||
+ | "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" | ||
+ | } | ||
+ | </code> | ||
+ | |||
+ | **返回值400,表示 massage 结构错误** | ||
+ | <code json> | ||
+ | { | ||
+ | "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]" | ||
+ | } | ||
+ | </code> | ||
+ | |||
+ | **返回值401,表示未授权[无token、token错误、token过期]** | ||
+ | <code json> | ||
+ | { | ||
+ | "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" | ||
+ | } | ||
+ | </code> | ||
+ | |||
+ | 如果返回结果是<wrap em>429、503</wrap>或者其他<wrap em>5xx</wrap>,有可能代表该接口被限流了,请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]] | ||
+ | |||
+ | [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] | ||
+ | ---- | ||
===== 发送透传消息 ===== | ===== 发送透传消息 ===== | ||
行 386: | 行 472: | ||
=== HTTP Request === | === HTTP Request === | ||
- | ^{{:im:server:ready:post.png?nolink&90 |}}^/**/{org_name}/{app_name}/messages**^ | + | ^{{:im:server:ready:post.png?nolink&90 |}}^**/{org_name}/{app_name}/messages**^ |
=== Request Headers === | === Request Headers === | ||
行 398: | 行 484: | ||
^参数^说明^ | ^参数^说明^ | ||
|target_type|发送的目标类型;users:给用户发消息,chatgroups:给群发消息,chatrooms:给聊天室发消息| | |target_type|发送的目标类型;users:给用户发消息,chatgroups:给群发消息,chatrooms:给聊天室发消息| | ||
- | |target|发送的目标;注意这里需要用数组,数组长度建议不大于20,即使只有一个用户,也要用数组 ['u1'];给用户发送时数组元素是用户名,给群组发送时,数组元素是groupid| | + | |target|发送的目标;注意这里需要用数组,数组内添加的最大用户数默认600个,即使只有一个用户,也要用数组 ['u1'];给用户发送时数组元素是用户名,给群组发送时,数组元素是groupid| |
|msg|消息内容| | |msg|消息内容| | ||
- | |type|消息类型;txt:文本消息,img:图片消息,loc:位置消息,audio:语音消息,video:视频消息,file:文件消息| | + | |type|消息类型;txt:文本消息,img:图片消息,loc:位置消息,audio:语音消息,video:视频消息,file:文件消息,cmd:透传消息| |
|from|表示消息发送者;无此字段Server会默认设置为"from":"admin",有from字段但值为空串("")时请求失败| | |from|表示消息发送者;无此字段Server会默认设置为"from":"admin",有from字段但值为空串("")时请求失败| | ||
行 413: | 行 499: | ||
<code php> | <code php> | ||
- | 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"}}' | + | 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"}' |
</code> | </code> | ||
行 424: | 行 510: | ||
"action" : "post", | "action" : "post", | ||
"application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5", | "application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5", | ||
- | "uri" : "https://a1.easemob.com/easemob-demo/testapp", | + | "uri" : "https://a1.easemob.com/easemob-demo/testapp/messages", |
"entities" : [ ], | "entities" : [ ], | ||
"data" : { | "data" : { | ||
行 456: | 行 542: | ||
"exception": "org.apache.usergrid.rest.exceptions.SecurityException", | "exception": "org.apache.usergrid.rest.exceptions.SecurityException", | ||
"error_description": "Unable to authenticate due to corrupt access token" | "error_description": "Unable to authenticate due to corrupt access token" | ||
+ | } | ||
+ | </code> | ||
+ | |||
+ | 如果返回结果是<wrap em>429、503</wrap>或者其他<wrap em>5xx</wrap>,有可能代表该接口被限流了,请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]] | ||
+ | |||
+ | [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] | ||
+ | ---- | ||
+ | |||
+ | ===== 发送自定义消息 ===== | ||
+ | |||
+ | |||
+ | 自定义消息:若普通消息类型不满足用户消息需求,可以使用自定义消息来自定义消息类型,主要是通过message的customEvent字段实现。 | ||
+ | <WRAP clear/> | ||
+ | 注意:在调用程序中,请求体如果超过 5kb 会导致413错误,需要拆成几个更小的请求体重试。详见[[im:server:help:restastrict|接口限流说明]]。 | ||
+ | |||
+ | === HTTP Request === | ||
+ | |||
+ | ^{{:im:server:ready:post.png?nolink&90 |}}^**/{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|表示消息发送成功| | ||
+ | |||
+ | |||
+ | === 请求示例 === | ||
+ | |||
+ | <code php> | ||
+ | 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"}}' | ||
+ | </code> | ||
+ | |||
+ | === 可能返回的结果示例 === | ||
+ | |||
+ | **返回值200,表示消息发送成功** | ||
+ | |||
+ | <code json> | ||
+ | { | ||
+ | "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" | ||
+ | } | ||
+ | </code> | ||
+ | |||
+ | **返回值400,表示 massage 结构错误** | ||
+ | <code json> | ||
+ | { | ||
+ | "error": "illegal_argument", | ||
+ | "exception": "java.lang.IllegalArgumentException", | ||
+ | "timestamp": 1597292940854, | ||
+ | "duration": 1, | ||
+ | "error_description": "target_type must be provided" | ||
+ | } | ||
+ | </code> | ||
+ | |||
+ | **返回值401,表示未授权[无token、token错误、token过期]** | ||
+ | <code json> | ||
+ | { | ||
+ | "error": "unauthorized", | ||
+ | "exception": "EasemobSecurityException", | ||
+ | "timestamp": 1597292804746, | ||
+ | "duration": 1, | ||
+ | "error_description": "Unable to authenticate (OAuth)" | ||
} | } | ||
</code> | </code> | ||
行 473: | 行 649: | ||
=== HTTP Request === | === HTTP Request === | ||
- | ^{{:im:server:ready:post.png?nolink&90 |}}^/**/{org_name}/{app_name}/messages**^ | + | ^{{:im:server:ready:post.png?nolink&90 |}}^**/{org_name}/{app_name}/messages**^ |
=== Request Headers === | === Request Headers === | ||
行 485: | 行 661: | ||
^参数^说明^ | ^参数^说明^ | ||
|target_type|发送的目标类型;users:给用户发消息,chatgroups:给群发消息,chatrooms:给聊天室发消息| | |target_type|发送的目标类型;users:给用户发消息,chatgroups:给群发消息,chatrooms:给聊天室发消息| | ||
- | |target|发送的目标;注意这里需要用数组,数组长度建议不大于20,即使只有一个用户,也要用数组 ['u1'];给用户发送时数组元素是用户名,给群组发送时,数组元素是groupid| | + | |target|发送的目标;注意这里需要用数组,数组内添加的最大用户数默认600个,即使只有一个用户,也要用数组 ['u1'];给用户发送时数组元素是用户名,给群组发送时,数组元素是groupid| |
|msg|消息内容| | |msg|消息内容| | ||
|type|消息类型,不局限与文本消息。任何消息类型都可以加扩展消息;txt:文本消息,img:图片消息,loc:位置消息,audio:语音消息,video:视频消息,file:文件消息| | |type|消息类型,不局限与文本消息。任何消息类型都可以加扩展消息;txt:文本消息,img:图片消息,loc:位置消息,audio:语音消息,video:视频消息,file:文件消息| | ||
|msg|消息;随意传入都可以| | |msg|消息;随意传入都可以| | ||
|from|表示消息发送者;无此字段Server会默认设置为"from":"admin",有from字段但值为空串("")时请求失败| | |from|表示消息发送者;无此字段Server会默认设置为"from":"admin",有from字段但值为空串("")时请求失败| | ||
- | |ext|扩展属性,由APP自己定义。可以没有这个字段,但是如果有,值不能是"ext:null"这种形式,否则出错| | + | |ext|扩展属性,由APP自己定义。可以没有这个字段,但是如果有,值不能是"ext:null"这种形式,否则出错。Key值类型必须是NSString,Value值类型必须是NSString或者 NSNumber类型的 BOOL,int,unsigned in,long long,double。| |
|attr1|消息的扩展内容,可以增加字段,扩展消息主要解析部分,必须是基本类型数据| | |attr1|消息的扩展内容,可以增加字段,扩展消息主要解析部分,必须是基本类型数据| | ||
行 514: | 行 690: | ||
"action" : "post", | "action" : "post", | ||
"application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5", | "application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5", | ||
- | "uri" : "https://a1.easemob.com/easemob-demo/testapp", | + | "uri" : "https://a1.easemob.com/easemob-demo/testapp/messages", |
"entities" : [ ], | "entities" : [ ], | ||
"data" : { | "data" : { | ||
行 562: | 行 738: | ||
|em_ignore_notification|[[im:ios:apns:content#发送静默消息|发送静默消息]]| | |em_ignore_notification|[[im:ios:apns:content#发送静默消息|发送静默消息]]| | ||
|em_force_notification|[[im:ios:apns:content#设置强制推送型 APNs|设置强制推送型 APNs]]| | |em_force_notification|[[im:ios:apns:content#设置强制推送型 APNs|设置强制推送型 APNs]]| | ||
- | |||
---- | ---- | ||
+ | |||
<WRAP group> | <WRAP group> | ||
<WRAP half column> | <WRAP half column> |