差别

这里会显示出您选择的修订版和当前版本之间的差别。

到此差别页面的链接

两侧同时换到之前的修订记录 前一修订版
后一修订版
前一修订版
后一修订版 两侧同时换到之后的修订记录
im:server:basics:messages [2019/09/10 04:00]
lizg [发送透传消息]
im:server:basics:messages [2020/08/13 04:54]
shenchong
行 5: 行 5:
 聊天相关 API,​可以发送文本消息,发送图片消息,发送语音消息,发送视频消息,发送透传消息和发送扩展消息。 聊天相关 API,​可以发送文本消息,发送图片消息,发送语音消息,发送视频消息,发送透传消息和发送扩展消息。
  
 +发送文件类型消息要先把文件上传到环信服务器,参考文档:[[im:​server:​basics:​fileoperation|文件上传下载]]
 +
 +REST接口发消息,不会判断环信id在appkey下是否存在。
 ===== 流程说明 ===== ===== 流程说明 =====
 ^消息类型^说明^ ^消息类型^说明^
行 13: 行 16:
 给一个或者多个用户,或者一个或者多个群组发送消息,并且通过可选的 from 字段让接收方看到发送方是不同的人。同时,支持扩展字段,通过 ext 属性,APP 可以发送自己专属的消息结构。 给一个或者多个用户,或者一个或者多个群组发送消息,并且通过可选的 from 字段让接收方看到发送方是不同的人。同时,支持扩展字段,通过 ext 属性,APP 可以发送自己专属的消息结构。
 <WRAP clear/> <WRAP clear/>
-**注意**:在调用程序中,请求体如果超过 5kb 会导致413错误,需要拆成几个更小的请求体重试,同时用户消息+扩展字段的长度在40k字节以内。详见[[im:​server:​help:​restastrict|接口限流说明]]。+**注意**:在调用程序中,请求体如果超过 5kb 会导致413错误,需要拆成几个更小的请求体重试,同时用户消息+扩展字段的长度在4k字节以内。详见[[im:​server:​help:​restastrict|接口限流说明]]。
  
 === HTTP Request === === HTTP Request ===
行 29: 行 32:
 ^参数^说明^ ^参数^说明^
 |target_type|发送的目标类型;users:给用户发消息,chatgroups:给群发消息,chatrooms:给聊天室发消息| |target_type|发送的目标类型;users:给用户发消息,chatgroups:给群发消息,chatrooms:给聊天室发消息|
-|target|发送的目标;注意这里需要用数组,数组长度建议大于20,即使只有一个用户,也要用数组 ['​u1'​];给用户发送时数组元素是用户名,给群组发送时,数组元素是groupid|+|target|发送的目标;注意这里需要用数组,并且向数组内添加的用户能超过1000个,即使只有一个用户,也要用数组 ['​u1'​];给用户发送时数组元素是用户名,给群组发送时,数组元素是groupid|
 |msg|消息内容| |msg|消息内容|
 |type|消息类型;txt:​文本消息,img:图片消息,loc:位置消息,audio:语音消息,video:视频消息,file:文件消息| |type|消息类型;txt:​文本消息,img:图片消息,loc:位置消息,audio:语音消息,video:视频消息,file:文件消息|
行 115: 行 118:
 ^参数^说明^ ^参数^说明^
 |target_type|发送的目标类型;users:给用户发消息,chatgroups:给群发消息,chatrooms:给聊天室发消息| |target_type|发送的目标类型;users:给用户发消息,chatgroups:给群发消息,chatrooms:给聊天室发消息|
-|target|发送的目标;注意这里需要用数组,数组长度建议大于20,即使只有一个用户,也要用数组 ['​u1'​];给用户发送时数组元素是用户名,给群组发送时,数组元素是groupid|+|target|发送的目标;注意这里需要用数组,并且向数组内添加的用户能超过1000个,即使只有一个用户,也要用数组 ['​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|
行 134: 行 137:
  
 <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>​
  
行 145: 行 148:
   "​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"​ : {
行 206: 行 209:
 ^参数^说明^ ^参数^说明^
 |target_type|发送的目标类型;users:给用户发消息,chatgroups:给群发消息,chatrooms:给聊天室发消息| |target_type|发送的目标类型;users:给用户发消息,chatgroups:给群发消息,chatrooms:给聊天室发消息|
-|target|发送的目标;注意这里需要用数组,数组长度建议大于20,即使只有一个用户,也要用数组 ['​u1'​];给用户发送时数组元素是用户名,给群组发送时,数组元素是groupid|+|target|发送的目标;注意这里需要用数组,并且向数组内添加的用户能超过1000个,即使只有一个用户,也要用数组 ['​u1'​];给用户发送时数组元素是用户名,给群组发送时,数组元素是groupid|
 |msg|消息内容| |msg|消息内容|
 |type|消息类型;txt:​文本消息,img:图片消息,loc:位置消息,audio:语音消息,video:视频消息,file:文件消息| |type|消息类型;txt:​文本消息,img:图片消息,loc:位置消息,audio:语音消息,video:视频消息,file:文件消息|
行 296: 行 299:
 ^参数^说明^ ^参数^说明^
 |target_type|发送的目标类型;users:给用户发消息,chatgroups:给群发消息,chatrooms:给聊天室发消息| |target_type|发送的目标类型;users:给用户发消息,chatgroups:给群发消息,chatrooms:给聊天室发消息|
-|target|发送的目标;注意这里需要用数组,数组长度建议大于20,即使只有一个用户,也要用数组 ['​u1'​];给用户发送时数组元素是用户名,给群组发送时,数组元素是groupid|+|target|发送的目标;注意这里需要用数组,并且向数组内添加的用户能超过1000个,即使只有一个用户,也要用数组 ['​u1'​];给用户发送时数组元素是用户名,给群组发送时,数组元素是groupid|
 |type|消息类型;txt:​文本消息,img:图片消息,loc:位置消息,audio:语音消息,video:视频消息,file:文件消息| |type|消息类型;txt:​文本消息,img:图片消息,loc:位置消息,audio:语音消息,video:视频消息,file:文件消息|
 |filename|视频文件名称| |filename|视频文件名称|
行 327: 行 330:
   "​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"​ : {
行 366: 行 369:
 [[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|发送的目标;注意这里需要用数组,并且向数组内添加的用户不能超过1000个,即使只有一个用户,也要用数组 ['​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 在线测试]]
 +----
 ===== 发送透传消息 ===== ===== 发送透传消息 =====
  
行 388: 行 473:
 ^参数^说明^ ^参数^说明^
 |target_type|发送的目标类型;users:给用户发消息,chatgroups:给群发消息,chatrooms:给聊天室发消息| |target_type|发送的目标类型;users:给用户发消息,chatgroups:给群发消息,chatrooms:给聊天室发消息|
-|target|发送的目标;注意这里需要用数组,数组长度建议大于20,即使只有一个用户,也要用数组 ['​u1'​];给用户发送时数组元素是用户名,给群组发送时,数组元素是groupid|+|target|发送的目标;注意这里需要用数组,并且向数组内添加的用户能超过1000个,即使只有一个用户,也要用数组 ['​u1'​];给用户发送时数组元素是用户名,给群组发送时,数组元素是groupid|
 |msg|消息内容| |msg|消息内容|
 |type|消息类型;txt:​文本消息,img:图片消息,loc:位置消息,audio:语音消息,video:视频消息,file:文件消息,cmd:透传消息| |type|消息类型;txt:​文本消息,img:图片消息,loc:位置消息,audio:语音消息,video:视频消息,file:文件消息,cmd:透传消息|
行 403: 行 488:
  
 <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>​
  
行 414: 行 499:
   "​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"​ : {
行 446: 行 531:
   "​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|发送的目标;注意这里需要用数组,并且向数组内添加的用户不能超过1000个,即使只有一个用户,也要用数组 ['​u1'​];给用户发送时数组元素是用户名,给群组发送时,数组元素是groupid|
 +|msg|消息内容|
 +|type|消息类型;txt:​文本消息,img:图片消息,loc:位置消息,audio:语音消息,video:视频消息,file:文件消息,custom:自定义消息|
 +|customEvent|用户自定义的事件类型,必须是string,值必须满足正则表达式 [a-zA-Z0-9-_/​\.]{1,​32},最短1个字符 最长32个字符|
 +|customExts|用户自定义的事件属性,类型必须是object,最多可以包含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>​
行 475: 行 650:
 ^参数^说明^ ^参数^说明^
 |target_type|发送的目标类型;users:给用户发消息,chatgroups:给群发消息,chatrooms:给聊天室发消息| |target_type|发送的目标类型;users:给用户发消息,chatgroups:给群发消息,chatrooms:给聊天室发消息|
-|target|发送的目标;注意这里需要用数组,数组长度建议大于20,即使只有一个用户,也要用数组 ['​u1'​];给用户发送时数组元素是用户名,给群组发送时,数组元素是groupid|+|target|发送的目标;注意这里需要用数组,并且向数组内添加的用户能超过1000个,即使只有一个用户,也要用数组 ['​u1'​];给用户发送时数组元素是用户名,给群组发送时,数组元素是groupid|
 |msg|消息内容| |msg|消息内容|
 |type|消息类型,不局限与文本消息。任何消息类型都可以加扩展消息;txt:​文本消息,img:图片消息,loc:位置消息,audio:语音消息,video:视频消息,file:文件消息| |type|消息类型,不局限与文本消息。任何消息类型都可以加扩展消息;txt:​文本消息,img:图片消息,loc:位置消息,audio:语音消息,video:视频消息,file:文件消息|
行 504: 行 679:
   "​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"​ : {
行 552: 行 727:
 |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>