====== 发送消息 ====== 更新时间：2021-12-31 该文档已不再维护，请看新版 3.X 文档。 新版文档见：[[ccim:rest:message|消息管理]]。 ---- 本篇介绍消息相关的 REST API，包括在服务端实现用户到用户，或用户到群组的消息发送与接收，支持消息类型包括文本消息，图片消息，语音消息，视频消息，透传消息和自定义消息。 发送文件类型消息要先把文件上传到环信服务器，参考文档：[[im:server:basics:fileoperation|文件上传下载]]。 REST 接口发消息，不会判断环信 ID 在 App Key 下是否存在。 ===== 流程说明 ===== ^消息类型^说明^ |发送文本/透传消息|直接编辑内容发送。| |发送图片/语音/视频消息|需要先上传这三类文件，从接口返回值中获取到相应的参数，按照 API 要求编辑到消息体中然后的发送。| ===== 发送文本消息 ===== 给一个或者多个用户，或者一个或者多个群组发送消息，并且通过可选的 from 字段让接收方看到发送方是不同的人。同时，支持扩展字段，通过 ext 属性，APP 可以发送自己专属的消息结构。 **注意**：在调用程序中，请求体如果超过 50KB 会导致 413 错误，需要拆成几个更小的请求体重试，同时用户消息+扩展字段的长度在 40KB 以内。详见[[im:server:help:restastrict|接口限流说明]]。 === 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，有可能代表该接口被限流了，请稍后再试。详见[[im:server:help:restastrict|接口限流说明]] [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] ---- ===== 发送图片消息 ===== 给一个或者多个用户，或者一个或者多个群组发送消息，并且通过可选的 from 字段让接收方看到发送方是不同的人。同时，支持扩展字段，通过 ext 属性，APP 可以发送自己专属的消息结构。 **注意**：在调用程序中，请求体如果超过 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：文件消息| |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，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]] [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] ---- ===== 发送语音消息 ===== 发送语音文件，需要先上传语音文件，然后再发送此消息。（URL 中的 UUID 和 secret 可以从上传后的 response 获取） 注意：在调用程序中，请求体如果超过 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：文件消息| |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，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]] [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] ---- ===== 发送视频消息 ===== 发送视频消息，需要先上传视频文件和视频缩略图文件，然后再发送此消息。（URL 中的 UUID 和 secret 可以从上传后的 response 获取） 注意：在调用程序中，请求体如果超过 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| |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，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]] [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] ---- ===== 发送位置消息 ===== 位置消息：获取到地址的经纬度，填写正确地址发送。 **注意**：在调用程序中，请求体如果超过 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|表示消息发送成功| === 请求示例 === 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，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]] [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] ---- ===== 发送透传消息 ===== 透传消息：不会在客户端提示（铃声、震动、通知栏等），也不会有 APNS 推送（苹果推送），但可以在客户端监听到，具体功能可以根据自身自定义。 注意：在调用程序中，请求体如果超过 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：文件消息，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，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]] [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] ---- ===== 发送自定义消息 ===== 自定义消息：若普通消息类型不满足用户消息需求，可以使用自定义消息来自定义消息类型，主要是通过message的customEvent字段实现。 注意：在调用程序中，请求体如果超过 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，最多可以包含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，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]] [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] ---- ===== 发送扩展消息 ===== 扩展消息：若普通消息类型不满足用户消息需求，可以使用扩展消息。任何类型的消息都支持扩展，主要是通过message的ext字段实现。 注意：在调用程序中，请求体如果超过 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：文件消息| |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，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]] [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] ==== iOS扩展消息 ==== 环信提供以下几种扩展字段： ^扩展字段^描述^ |em_push_content|[[im:ios:apns:content#自定义显示|自定义推送显示]]| |em_push_category|[[im:ios:apns:content#添加category字段|向 APNs Payload 中添加 category 字段]]| |em_push_sound|[[im:ios:apns:content#自定义推送提示音|自定义推送提示音]]| |em_push_mutable_content|[[im:ios:apns:content#开启 APNs 通知扩展|开启 APNs 通知扩展]]| |em_ignore_notification|[[im:ios:apns:content#发送静默消息|发送静默消息]]| |em_force_notification|[[im:ios:apns:content#设置强制推送型 APNs|设置强制推送型 APNs]]| ---- 上一页：[[im:server:ready:user|用户体系集成]] 下一页：[[im:server:basics:group|群组管理]]