发送消息

聊天相关 API。

流程说明

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

发送文本消息

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

<WRAP round tip> 接口限流说明：同一个 IP 每秒最多可调用30次，超过的部分会返回429或503错误。所以在调用程序中，如果碰到了这样的错误，需要稍微暂停一下并且重试。如果该限流控制不满足需求，请联系商务经理开放更高的权限。请求体如果超过 5kb 会导致413错误，需要拆成几个更小的请求体重试。 </WRAP>

  • Path: /{org_name}/{app_name}/messages
  • Request Method: POST
  • URL Params: 无
  • Request Headers: {“Content-Type”:”application/json”,”Authorization”:”Bearer ${token}”}
  • Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  • 可能的错误码：400（此用户或groupid不存在）、401（未授权[无token、token错误、token过期]）、5xx。详见：服务器端 REST API 常见错误码

Request Body: 

{
    "target_type" : "users", // users 给用户发消息。chatgroups: 给群发消息，chatrooms: 给聊天室发消息
    "target" : ["u1", "u2", "u3"], // 注意这里需要用数组，数组长度建议不大于20，即使只有一个用户，
                                   // 也要用数组 ['u1']，给用户发送时数组元素是用户名，给群组发送时  
                                   // 数组元素是groupid
    "msg" : {
        "type" : "txt",
        "msg" : "hello from rest" //消息内容，参考[[start:100serverintegration:30chatlog|聊天记录]]里的bodies内容
        },
    "from" : "jma2" //表示消息发送者。无此字段Server会默认设置为"from":"admin"，有from字段但值为空串("")时请求失败
}

curl 示例： 

curl -X POST -i -H "Authorization: Bearer YWMtxc6K0L1aEeKf9LWFzT9xEAAAAT7MNR_9OcNq-GwPsKwj_TruuxZfFSC2eIQ" "https://a1.easemob.com/easemob-demo/chatdemoui/messages" -d '{"target_type" : "users","target" : ["stliu1", "jma3", "stliu", "jma4"],"msg" : {"type" : "txt","msg" : "hello from rest"},"from" : "jma2"}'

Response 示例： 

{
    "action": "post",
    "application": "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
    "params": {},
    "uri": "https://a1.easemob.com/easemob-demo/chatdemoui",
    "entities": [],
    "data": {
        "stliu1": "success",
        "jma3": "success",
        "stliu": "success",
        "jma4": "success"
    },
    "timestamp": 1404932446668,
    "duration": 110,
    "organization": "easemob-demo",
    "applicationName": "chatdemoui"
}

发送图片消息

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

<WRAP round tip> 接口限流说明：同一个 IP 每秒最多可调用30次，超过的部分会返回429或503错误。所以在调用程序中，如果碰到了这样的错误，需要稍微暂停一下并且重试。如果该限流控制不满足需求，请联系商务经理开放更高的权限。请求体如果超过 5kb 会导致413错误，需要拆成几个更小的请求体重试。 </WRAP>

  • Path: /{org_name}/{app_name}/messages
  • Request Method: POST
  • URL Params: 无
  • Request Headers: {“Content-Type”:”application/json”,”Authorization”:”Bearer ${token}”}
  • Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  • 可能的错误码：400（此用户或groupid不存在）、401（未授权[无token、token错误、token过期]）、5xx。详见：服务器端 REST API 常见错误码

Request Body: 

{
    "target_type" : "users",   //users 给用户发消息。chatgroups: 给群发消息，chatrooms: 给聊天室发消息
    "target" : ["u1", "u2", "u3"],// 注意这里需要用数组，数组长度建议不大于20，即使只有一个用户，
                                  // 也要用数组 ['u1']，给用户发送时数组元素是用户名，给群组发送时  
                                  // 数组元素是groupid
    "msg" : {  //消息内容
        "type" : "img",   // 消息类型
	    "url": "https://a1.easemob.com/easemob-demo/chatdemoui/chatfiles/55f12940-64af-11e4-8a5b-ff2336f03252",  //成功上传文件返回的UUID
	    "filename": "24849.jpg", // 指定一个文件名
	    "secret": "VfEpSmSvEeS7yU8dwa9rAQc-DIL2HhmpujTNfSTsrDt6eNb_", // 成功上传文件后返回的secret
	    "size" : {
          "width" : 480,
          "height" : 720
      }
     },
    "from" : "jma2" //表示消息发送者，无此字段Server会默认设置为"from":"admin"，有from字段但值为空串("")时请求失败
}

curl 示例： 

curl -X POST -i 'https://a1.easemob.com/easemob-demo/chatdemoui/messages'   -H 'Authorization: Bearer YWMtsFVigGSuEeSTc7k5183Z5QAAAUqzeFx_9IjRch-ZxNbIlBIvx_4GWvzheSU'  -d '{"target_type":"users","target":["l1k4vpllxp"],"from":"jma2","msg":{"type":"img","filename":"24849.jpg","secret":"VfEpSmSvEeS7yU8dwa9rAQc-DIL2HhmpujTNfSTsrDt6eNb_","url":"https://a1.easemob.com/easemob-demo/chatdemoui/chatfiles/55f12940-64af-11e4-8a5b-ff2336f03252"},size:{"width":480,"height":720}}

Response 示例： 

{
  "action" : "post",
  "application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
  "uri" : "https://a1.easemob.com/easemob-demo/chatdemoui",
  "entities" : [ ],
  "data" : {
   	 "l1k4vpllxp" : "success"
  },
  "timestamp" : 1415166497129,
  "duration" : 12,
  "organization" : "easemob-demo",
  "applicationName" : "chatdemoui"
}

发送语音消息

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

<WRAP round tip> 接口限流说明：同一个 IP 每秒最多可调用30次，超过的部分会返回429或503错误。所以在调用程序中，如果碰到了这样的错误，需要稍微暂停一下并且重试。如果该限流控制不满足需求，请联系商务经理开放更高的权限。请求体如果超过 5kb 会导致413错误，需要拆成几个更小的请求体重试。 </WRAP>

  • Path: /{org_name}/{app_name}/messages
  • Request Method: POST
  • URL Params: 无
  • Request Headers: {“Content-Type”:”application/json”,”Authorization”:”Bearer ${token}”}
  • Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  • 可能的错误码：400（此用户或groupid不存在）、401（未授权[无token、token错误、token过期]）、5xx。详见：服务器端 REST API 常见错误码

Request Body: 

{
	"target_type" : "users",  //users 给用户发消息。chatgroups: 给群发消息，chatrooms: 给聊天室发消息
	"target" : ["testd", "testb", "testc"],// 注意这里需要用数组，数组长度建议不大于20，即使只有一个  
                                           // 用户或者群组，也要用数组形式 ['u1']，给用户发送  
                                           // 此数组元素是用户名，给群组发送时数组元素是groupid
	"msg" : {   //消息内容
		"type": "audio",  // 消息类型
		"url": "https://a1.easemob.com/easemob-demo/chatdemoui/chatfiles/1dfc7f50-55c6-11e4-8a07-7d75b8fb3d42",  //成功上传文件返回的UUID
		"filename": "messages.amr", // 指定一个文件名
		"length": 10,
		"secret": "Hfx_WlXGEeSdDW-SuX2EaZcXDC7ZEig3OgKZye9IzKOwoCjM" // 成功上传文件后返回的secret
	},
	"from" : "testa"   //表示消息发送者，无此字段Server会默认设置为"from":"admin"，有from字段但值为空串("")时请求失败
}

curl 示例： 

curl -X POST -H "Authorization: Bearer YWMtxc6K0L1aEeKf9LWFzT9xEAAAAT7MNR_9OcNq-GwPsKwj_TruuxZfFSC2eIQ" "https://a1.easemob.com/easemob-demo/chatdemoui/messages" -d '{"target_type" : "users","target" : ["testd", "testb", "testc"],"msg" : {"type": "audio","url": "https://a1.easemob.com/easemob-demo/chatdemoui/chatfiles/1dfc7f50-55c6-11e4-8a07-7d75b8fb3d42","filename": "messages.amr","length": 10,"secret": "Hfx_WlXGEeSdDW-SuX2EaZcXDC7ZEig3OgKZye9IzKOwoCjM"},"from" : "testa" }'

Response 示例： 

{
  "action" : "post",
  "application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
  "uri" : "https://a1.easemob.com/easemob-demo/chatdemoui",
  "entities" : [ ],
  "data" : {
    "testd" : "success",
    "testb" : "success",
    "testc" : "success"
  },
  "timestamp" : 1415166234863,
  "duration" : 5,
  "organization" : "easemob-demo",
  "applicationName" : "chatdemoui"
}

发送视频消息

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

<WRAP round tip> 接口限流说明：同一个 IP 每秒最多可调用30次，超过的部分会返回429或503错误。所以在调用程序中，如果碰到了这样的错误，需要稍微暂停一下并且重试。如果该限流控制不满足需求，请联系商务经理开放更高的权限。请求体如果超过 5kb 会导致413错误，需要拆成几个更小的请求体重试。 </WRAP>

  • Path: /{org_name}/{app_name}/messages
  • Request Method: POST
  • URL Params: 无
  • Request Headers: {“Content-Type”:”application/json”,”Authorization”:”Bearer ${token}”}
  • Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  • 可能的错误码：400（此用户或groupid不存在）、401（未授权[无token、token错误、token过期]）、5xx。详见：服务器端 REST API 常见错误码

Request Body: 

{
    "target_type": "users", //users 给用户发消息。chatgroups: 给群发消息，chatrooms: 给聊天室发消息
    "target": [
        "ceshib"// 注意这里需要用数组，数组长度建议不大于20，即使只有一个用户或者群组，也要用数组形式 ['u1']，给用户发送
    ]，// 此数组元素是用户名，给群组发送时数组元素是groupid
    "from": "ceshia", //表示消息发送者，无此字段Server会默认设置为"from":"admin"，有from字段但值为空串("")时请求失败
    "msg": { //消息内容
        "type": "video",// 消息类型
        "filename": "1418105136313.mp4",// 视频文件名称
        "thumb": "https://a1.easemob.com/easemob-demo/chatdemoui/chatfiles/67279b20-7f69-11e4-8eee-21d3334b3a97",//成功上传视频缩略图返回的UUID
        "length": 10,//视频播放长度
        "secret": "VfEpSmSvEeS7yU8dwa9rAQc-DIL2HhmpujTNfSTsrDt6eNb_",// 成功上传视频文件后返回的secret
        "file_length": 58103,//视频文件大小
        "thumb_secret": "ZyebKn9pEeSSfY03ROk7ND24zUf74s7HpPN1oMV-1JxN2O2I",// 成功上传视频缩略图后返回的secret
        "url": "https://a1.easemob.com/easemob-demo/chatdemoui/chatfiles/671dfe30-7f69-11e4-ba67-8fef0d502f46"//成功上传视频文件返回的UUID
    }
}

curl 示例： 

curl -X POST -i 'https://a1.easemob.com/easemob-demo/chatdemoui/messages' -H 'Authorization: Bearer YWMtxc6K0L1aEeKf9LWFzT9xEAAAAT7MNR_9OcNq-GwPsKwj_TruuxZfFSC2eIQ'  -d '{"target_type":"users","target":["testd","testb","testc"],"from":"testa","msg":{"type":"video","filename" : "1418105136313.mp4","thumb" : "https://a1.easemob.com/easemob-demo/chatdemoui/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/chatdemoui/chatfiles/671dfe30-7f69-11e4-ba67-8fef0d502f46"}}'

Response 示例： 

{
  "action" : "post",
  "application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
  "uri" : "https://a1.easemob.com/easemob-demo/chatdemoui",
  "entities" : [ ],
  "data" : {
    "testd" : "success",
    "testb" : "success",
    "testc" : "success"
  },
  "timestamp" : 1415166234863,
  "duration" : 5,
  "organization" : "easemob-demo",
  "applicationName" : "chatdemoui"
}

发送透传消息

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

<WRAP round tip> 接口限流说明：同一个 IP 每秒最多可调用30次，超过的部分会返回429或503错误。所以在调用程序中，如果碰到了这样的错误，需要稍微暂停一下并且重试。如果该限流控制不满足需求，请联系商务经理开放更高的权限。请求体如果超过 5kb 会导致413错误，需要拆成几个更小的请求体重试。 </WRAP>

  • Path: /{org_name}/{app_name}/messages
  • Request Method: POST
  • URL Params: 无
  • Request Headers: {“Content-Type”:”application/json”,”Authorization”:”Bearer ${token}”}
  • Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  • 可能的错误码：400（此用户或groupid不存在）、401（未授权[无token、token错误、token过期]）、5xx。详见：服务器端 REST API 常见错误码

Request Body: 

{
	"target_type":"users",     // users 给用户发消息。chatgroups 给群发消息，chatrooms 给聊天室发消息
	"target":["testb","testc"], // 注意这里需要用数组，数组长度建议不大于20，即使只有  
                                // 一个用户u1或者群组，也要用数组形式 ['u1']，给用户发  
                                // 送时数组元素是用户名，给群组发送时数组元素是groupid
	"msg":{  //消息内容
		"type":"cmd",  // 消息类型
		"action":"action1"
	},
	"from":"testa"  //表示消息发送者。无此字段Server会默认设置为"from":"admin"，有from字段但值为空串("")时请求失败
}

curl 示例： 

curl -X POST -H "Authorization:Bearer YWMtxc6K0L1aEeKf9LWFzT9xEAAAAT7MNR_9OcNq-GwPsKwj_TruuxZfFSC2eIQ" -i "https://a1.easemob.com/easemob-demo/chatdemoui/messages" -d '{"target_type":"users","target":["testb","testc"],"msg":{"type":"cmd","action":"action1"},"from":"testa"}}'

Response 示例： 

{
  "action" : "post",
  "application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
  "uri" : "https://a1.easemob.com/easemob-demo/chatdemoui",
  "entities" : [ ],
  "data" : {
    "testb" : "success",
    "testc" : "success"
  },
  "timestamp" : 1415167842297,
  "duration" : 4,
  "organization" : "easemob-demo",
  "applicationName" : "chatdemoui"
}

发送扩展消息

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

<WRAP round tip> 接口限流说明：同一个 IP 每秒最多可调用30次，超过的部分会返回429或503错误。所以在调用程序中，如果碰到了这样的错误，需要稍微暂停一下并且重试。如果该限流控制不满足需求，请联系商务经理开放更高的权限。请求体如果超过 5kb 会导致413错误，需要拆成几个更小的请求体重试。 </WRAP>

  • Path: /{org_name}/{app_name}/messages
  • Request Method: POST
  • URL Params: 无
  • Request Headers: {“Content-Type”:”application/json”,”Authorization”:”Bearer ${token}”}
  • Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  • 可能的错误码：400（此用户或groupid不存在）、401（未授权[无token、token错误、token过期]）、5xx。详见：服务器端 REST API 常见错误码

Request Body: 

{
	"target_type":"users",     // users 给用户发消息。chatgroups 给群发消息，chatrooms 给聊天室发消息
	"target":["testb","testc"], // 注意这里需要用数组，数组长度建议不大于20，即使只有  
                                // 一个用户u1或者群组，也要用数组形式 ['u1']，给用户发  
                                // 送时数组元素是用户名，给群组发送时数组元素是groupid
	"msg":{  //消息内容
		"type":"txt",  // 消息类型，不局限与文本消息。任何消息类型都可以加扩展消息
		"msg":"消息"    // 随意传入都可以
	},
	"from":"testa",  //表示消息发送者。无此字段Server会默认设置为"from":"admin"，有from字段但值为空串("")时请求失败
	"ext":{   //扩展属性，由APP自己定义。可以没有这个字段，但是如果有，值不能是"ext:null"这种形式，否则出错
		"attr1":"v1"   // 消息的扩展内容，可以增加字段，扩展消息主要解析不分。
	}
}

curl 示例： 

curl -X POST -H "Authorization:Bearer YWMtxc6K0L1aEeKf9LWFzT9xEAAAAT7MNR_9OcNq-GwPsKwj_TruuxZfFSC2eIQ" -i "https://a1.easemob.com/easemob-demo/chatdemoui/messages" -d '{"target_type":"users","target":["testb","testc"],"msg":{"type":"txt","msg":"消息"},"from":"testa","ext":{"attr1":"v1"}}'

Response 示例： 

{
  "action" : "post",
  "application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
  "uri" : "https://a1.easemob.com/easemob-demo/chatdemoui",
  "entities" : [ ],
  "data" : {
    "testb" : "success",
    "testc" : "success"
  },
  "timestamp" : 1415167842297,
  "duration" : 4,
  "organization" : "easemob-demo",
  "applicationName" : "chatdemoui"
}