发送聊天室消息
更新时间: 2024/07/17 17:57:35
网易云信 IM 服务端支持发送聊天室消息,消息类型包括消息类型包括文本消息、图片消息、语音消息、视频消息、地理位置消息、文件消息、提示消息和自定义消息。
聊天室流控机制
聊天室存在流量控制机制(以下简称“流控机制”),即用户在聊天室发送大量消息时,部分消息可能丢失。
为保证用户体验(如避免服务器过载),目前针对消息接收,有以下流控机制。
- 针对普通消息,聊天室用户每秒至多可接收 20 条,超过部分会因为流控随机丢弃。为避免丢失重要消息(通常为服务端消息),可将下文请求参数中的
highPriority
参数设置为true
,实现高优先级接收服务端消息,进而保证高优先级消息流控上限内的重要消息不丢失。 - 针对高优先级消息,每秒至多接收 10 条,超过部分可能会丢失。
功能描述
用户可在聊天室中发送聊天室消息,支持发送文本消息,图片消息,语音消息,地址位置消息等多种消息类型。
重发消息与发送消息都可通过本 API 实现,通过设置resendFlag
进行区分。详情请参见下文请求参数中该参数的说明。
API 使用限制
单个应用默认最高调用频率:100 次/秒。如超限,将被屏蔽 10 秒。
URL
httpPOST https://api.netease.im/nimserver/chatroom/sendMsg.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8
请求参数
-
POST 请求中 Headers 的设置请参考API 调用方式。
-
POST 请求中 Body 的设置如下:
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
roomid | Long | 是 | 聊天室 ID |
msgId | String | 是 | 消息 ID,使用 uuid 等随机串,msgId 相同的消息会被客户端去重 |
attach | String | 否 | 消息内容,最大长度 4096 字符 |
fromAccid | String | 是 | 发送消息的用户账号,accid |
ignoreMute | Boolean | 否 | 是否忽略成员临时禁言,true:忽略;false:不忽略,默认为 false |
msgType | Integer | 是 | 消息类型: 0: 文本消息,1: 图片,2: 语音,3: 视频,4: 地理位置信息,6: 文件,10: 提示消息(Tips),100: 自定义消息 |
subType | Integer | 否 | 自定义消息子类型,大于 0 |
resendFlag | Integer | 否 | 重发消息标记 0:非重发消息,1:重发消息,如重发消息会按照 msgId 检查去重逻辑 |
ext | String | 否 | 消息扩展字段,内容可自定义,JSON 格式,最大长度 4096 位字符 |
route | Integer | 否 | 消息是否需要抄送 0:不需要;1:需要(默认) |
skipHistory | Integer | 否 | 是否存储云端历史消息 0:存储云端历史消息(默认);1:不存储 |
abandonRatio | Integer | 否 | 消息丢弃的概率,取值范围 [0-9999]; 0:不丢弃消息(默认),9999:99.99%的概率丢弃消息 此参数可用于流控特定业务类型的消息 |
highPriority | Boolean | 否 | true:高优先级消息,云信会优先保障投递此类消息;false:低优先级消息(默认) 高优先级消息可以设置进入后重发,具体参见 needHighPriorityMsgResend 参数 |
needHighPriorityMsgResend | Boolean | 否 | true:会重发消息(默认),false:不会重发消息 |
useYidun | Integer | 否 | 单条消息(包括自定义消息)是否使用安全通(即易盾反垃圾),只能传 0,传其他值相当于不传 0:(在开通安全通的情况下)不使用安全通 若不填此字段,即在默认情况下,若应用开通了安全通,则使用安全通来进行垃圾消息的判断 |
yidunAntiCheating | String | 否 | 透传给易盾的反作弊检测参数,JSON,最大长度 1024 位字符,(具体请参见易盾的反垃圾防刷版专属字段) |
yidunAntiSpamExt | String | 否 | 透传给易盾的反垃圾增强版的检测参数,JSON,最大长度 1024 位字符(具体请参见易盾的反垃圾增强版用户可扩展字段) |
bid | String | 否 | 安全通的自定义反垃圾(即内容审核)业务的 ID。自定义反垃圾业务主要用来针对单条消息进行除了默认反垃圾业务以外的内容审核。如需配置自定义反垃圾,请通过云信官网首页提供的微信、在线聊天和电话等方式联系商务经理进行配置,并获取对应的业务 ID |
antispam | Boolean | 否 | 对于开通了安全通(易盾反垃圾)功能的应用,本消息是否需要指定经由易盾检测的内容(antispamCustom),默认 false 只对自定义消息(消息类型:100)生效 |
notifyTargetTags | String | 否 | 目标标签表达式,用于设定聊天室消息的投递对象,最大长度 128 位字符。具体使用说明和示例请参见标签表达式 |
antispamCustom | String | 否 | 自定义的反垃圾检测内容,在 antispam 参数为 true 时生效,JSON,长度限制同 body 字段,最大长度 5000 位字符,要求 antispamCustom 格式如下: {"type":1,"data":"custom content"} 字段说明: type: 1:文本,2:图片 data: 文本内容或图片地址 |
env | String | 否 | 消息需要抄送到的环境的名称,对应您在云信控制台中配置的自定义抄送的环境名称(如下图),最大 32 个字符 |
chatMsgPriority | Integer | 否 | 走 CDN通道的消息的优先级,可选值:0(默认),1,2,3 |
forbiddenIfHighPriorityMsgFreq | Integer | 否 | 高优先级消息被频控后是降级为普通消息还是返回 403 错误码 0:降级为普通消息(默认),1:返回 403 错误码 |
locX | Double | 否 | 空间坐标x,用于在部分基于空间坐标的场景下给指定范围内的用户发送空间消息,该功能对客户端SDK有版本要求(8.11.0及以上) |
locY | Double | 否 | 空间坐标y,用于在部分基于空间坐标的场景下给指定范围内的用户发送空间消息,该功能对客户端SDK有版本要求(8.11.0及以上) |
locZ | Double | 否 | 空间坐标z,用于在部分基于空间坐标的场景下给指定范围内的用户发送空间消息,该功能对客户端SDK有版本要求(8.11.0及以上) |
返回参数
参数 | 类型 | 说明 |
---|---|---|
code | Integer | 状态码 |
desc | String | 发送的消息体的详细信息 |
desc 中的参数说明
参数 | 类型 | 说明 |
---|---|---|
time | Long | 发送消息的时间戳,毫秒级 |
fromAvator | String | 发送消息用户的头像 |
msgid_client | Long | 客户端的消息 ID |
fromClientType | String | 发送消息用户的客户端类型 |
roomId | Long | 聊天室 ID |
fromAccount | String | 发送消息的用户账号,accid |
fromNick | String | 发送消息的用户昵称 |
attach | String | 消息内容 |
type | Integer | 消息类型 |
ext | String | 扩展字段 |
highPriorityFlag | Integer | 高优先级消息标记,不带此标记表示非高优先级 |
msgAbandonFlag | Integer | 消息被丢弃标记,传 abandonRatio 参数时才会返回此标记,不返回此标记代表未被丢弃 |
示例
请求示例(curl)
curlcurl -X POST -H "CheckSum: 51eb13ea***1c65c7866c366" -H "AppKey: f541664***6ad7799" -H "Nonce: 1" -H "CurTime: 1451207708" -H "Content-Type: application/x-www-form-urlencoded" -d 'roomid=36&fromAccid=zhangsan&msgType=0&attach=This+is+test+msg&msgId=c9e6c306-804f-4ec3-b8f0-573778829419' 'https://api.netease.im/nimserver/chatroom/sendMsg.action'
请求成功返回示例
json"Content-Type": "application/json; charset=utf-8"
{
"code":200,
"desc":{
"time": "1456396333115",
"fromAvator":"http://b12026.nos.netease.com/MTAxMTAxMA==/bmltYV84NDU4OF8xNDU1ODczMjA2NzUwX2QzNjkxMjI2LWY2NmQtNDQ3Ni0E2LTg4NGE4MDNmOGIwMQ==",
"msgid_client": "c9e6c306-804f-4ec3-b8f0-573778829419",
"fromClientType": "REST",
"attach": "This+is+test+msg",
"roomId": "36",
"fromAccount": "zhangsan",
"fromNick": "张三",
"type": "0",
"ext": "",
"highPriorityFlag":1, //高优先级消息标记,不带此标记表示非高优先级
"msgAbandonFlag":"1" //消息被丢弃标记,传abandonRatio参数时才会返回此标记,不返回此标记代表未被丢弃
}
}
请求失败返回示例
"Content-Type": "application/json; charset=utf-8"
{
"code":414
"desc":"msgContents size exceed" //消息内容大小超出限制
}
状态码
该接口在 HTTPS Body 中返回请求的状态码,以下仅列出与接口业务相关的状态码。完整状态码请参见状态码。
状态码 | 说明 | 处理建议 |
---|---|---|
200 | 请求成功 | - |
414 | 参数错误 | 根据提示信息,检查传入参数的格式和限制条件 |
403 | 禁止操作 | 聊天室名称等违规,未过审核或者未开启聊天室权限 |
416 | 频控限制,访问频率过高 | 降低访问频率 |
419 | 聊天室数量超出 | - |
500 | 服务出错 | - |
消息格式示例
图片消息(type = 1)
{
"name":"图片发送于2015-05-07 13:59", //图片name
"md5":"9894907e4ad9de4678091277509361f7", //图片文件md5,按照字节流加密
"url":"http://nimtest.nos.netease.com/cbc500e8-e19c-4b0f-834b-c32d4dc1075e", //生成的url
"ext":"jpg", //图片后缀
"w":6814, //宽,单位为像素
"h":2332, //高,单位为像素
"size":388245 //图片文件大小,单位为字节(Byte)
}
语音消息(type = 2)
{
"dur":4551, //语音持续时长ms
"md5":"87b94a090dec5c58f242b7132a530a01", //语音文件的md5值,按照字节流加密
"url":"http://nimtest.nos.netease.com/a2583322-413d-4653-9a70-9cabdfc7f5f9", //生成的url
"ext":"aac", //语音消息格式
"size":16420 //语音文件大小,单位为字节(Byte)
}
视频消息(type = 3)
{
"dur":8003, //视频持续时长ms
"md5":"da2cef3e5663ee9c3547ef5d127f7e3e", //视频文件的md5值,按照字节流加密
"url":"http://nimtest.nos.netease.com/21f34447-e9ac-4871-91ad-d9f03af20412", //生成的url
"w":360, //宽,单位为像素
"h":480, //高,单位为像素
"ext":"mp4", //视频格式
"size":16420 //视频文件大小,单位为字节(Byte)
}
地理位置消息(type = 4)
{
"title":"中国 浙江省 杭州市 网商路 599号", //地理位置title
"lng":120.1908686708565, // 经度
"lat":30.18704515647036 // 纬度
}
文件消息(type = 6)
{
"name":"BlizzardReg.ttf", //文件名
"md5":"79d62a35fa3d34c367b20c66afc2a500", //文件MD5,按照字节流加密
"url":"http://nimtest.nos.netease.com/08c9859d-183f-4daa-9904-d6cacb51c95b", //文件URL
"ext":"ttf", //文件后缀类型
"size":91680 //大小,单位为字节(Byte)
}
自定义消息(type = 100)
//开发者自定义的body,JSON 格式
{
"myKey":myValue
}
此文档是否对你有帮助?