API 参考
圈组

发送聊天室消息

更新时间: 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 字符除文本消息(msgType=0)和提示消息(msgType=10)外,其他消息类型的内容都为 JSON 格式,具体请参见消息格式示例
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:不存储
abandonRatioInteger消息丢弃的概率,取值范围 [0-9999];
0:不丢弃消息(默认),9999:99.99%的概率丢弃消息
此参数可用于流控特定业务类型的消息如果填写此参数,下面的 highPriority 参数将无效
highPriority Boolean true:高优先级消息,云信会优先保障投递此类消息;false:低优先级消息(默认)
高优先级消息可以设置进入后重发,具体参见 needHighPriorityMsgResend 参数建议恰当使用该参数,以便在必要时,优先保障应用内的高优先级消息的投递。若全部设置为高优先级,则等于没有设置,单个聊天室最多支持每秒 10 条高优先级消息,超过的默认转为普通消息
needHighPriorityMsgResend Boolean true:会重发消息(默认),false:不会重发消息若设置为true,当用户离开聊天室之后重新加入聊天室,在有效期内还会收到发送的此条消息,目前有效期默认 30s。在未配置 highPriority时,needHighPriorityMsgResend 不生效
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 个字符

自定义抄送环境.png

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发送消息的时间戳,毫秒级
fromAvatorString发送消息用户的头像
msgid_clientLong客户端的消息 ID
fromClientTypeString发送消息用户的客户端类型
roomId Long聊天室 ID
fromAccount String 发送消息的用户账号,accid
fromNick String 发送消息的用户昵称
attach String消息内容
type Integer 消息类型
ext String扩展字段
highPriorityFlag Integer高优先级消息标记,不带此标记表示非高优先级
msgAbandonFlagInteger消息被丢弃标记,传 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	
}
此文档是否对你有帮助?
有帮助
去反馈
  • 聊天室流控机制
  • 功能描述
  • API 使用限制
  • URL
  • 请求参数
  • 返回参数
  • 示例
  • 请求示例(curl)
  • 请求成功返回示例
  • 请求失败返回示例
  • 状态码
  • 消息格式示例
  • 图片消息(type = 1)
  • 语音消息(type = 2)
  • 视频消息(type = 3)
  • 地理位置消息(type = 4)
  • 文件消息(type = 6)
  • 自定义消息(type = 100)