该接口可以在聊天室中批量发送多条消息，支持发送定向消息（指定消息接收者列表）和空间消息（指定接收者的空间坐标）。

功能描述

• 在聊天室重发消息也都可通过本接口实现，通过设置 resend_flag 参数进行区分。详情请参考下文 请求体参数说明。
• 不支持将聊天室定向消息保存为历史消息。

聊天室存在流量控制机制（以下简称 流控机制），即用户在聊天室发送大量消息时，部分消息可能丢失。

为保证用户体验（如避免服务器过载），目前针对消息接收，有以下 流控机制。

• 针对普通消息，聊天室用户每秒至多可接收 20 条，超过部分会因为流控随机丢弃。为避免丢失重要消息（通常为服务端消息），可将下文请求参数中的 high_priority 参数设置为 true，实现高优先级接收服务端消息，进而保证高优先级消息流控上限内的重要消息不丢失。
• 针对高优先级消息，每秒至多接收 10 条，超过部分可能会丢失。

调用频率

单个应用默认最高调用频率请参考 频控说明。

请求信息

请求 URL

POST https://{endpoint}/im/v2/chatrooms/messages

请求 URL 中的 {endpoint} 代表服务地址域名，您可以根据用户服务区域选择中国大陆和海外服务地址，并支持搭建高可用主备域名机制。详情请参考 调用方式 服务地址章节。

请求头参数

请求 Header 的参数说明请参考 请求 Header。

请求体参数

参数名称	类型	是否必选	描述
room_id	Long	是	聊天室 ID。
sender_id	String	是	发送聊天室消息的账号 ID。
receiver_ids	Array of strings	否	消息接收账号 ID 列表，例如["yx2","yx3"]。 该参数不为空即判定为定向消息，形象消息不存历史。 定向消息不支持 message_config 参数。 定向消息不支持空间坐标相关参数。
resend_flag	Integer	否	重发消息标记。 0（默认）：非重发消息；1：重发消息（按照 message_client_id 进行去重）。
extension	String	否	开发者扩展参数，JSON 格式。例如："{"k":"v"}"。 该字段长度上限以使用的 IM 套餐为准；IM 旗舰版及以上套餐才支持配置字段上限。
- messages	Array of objects	是	消息列表。
message_client_id	String	是	消息客户端 ID。
message_type	Integer	是	消息类型。0：文本消息；1：图片消息；2：语音消息；3：视频消息；4：地理位置消息；6：文件消息；10：提示消息；100：自定义消息。对于未开通安全通（即易盾反垃圾）功能的应用，自定义消息不会过内容审核。
sub_type	Integer	否	自定义消息子类型，大于 0。message_type = 100 时该参数才有效。
text	String	否	对于文本消息和提示消息，该字段必填，值为消息内容，长度上限 5000 位字符。 对于非文本/提示消息，该字段非必填，值为描述信息，可用于 全文关键字搜索历史消息，长度上限 500 位字符。
attachment	Object	否	非文本消息/提示消息的属性或自定义消息内容。 对于非文本消息/提示消息，该字段必填，每种消息的属性参数见：消息格式示例。 该字段长度上限以使用的 IM 套餐为准；IM 旗舰版及以上套餐才支持配置字段上限。
location_x	Double	否	空间坐标 x，用于发送空间消息。定向消息（receiver_ids 不为空）不支持该参数。
location_y	Double	否	空间坐标 y，用于发送空间消息。定向消息（receiver_ids 不为空）不支持该参数。
location_z	Double	否	空间坐标 z，用于发送空间消息。定向消息（receiver_ids 不为空）不支持该参数。
- message_config	Object	否	消息配置项。定向消息（receiver_ids 不为空）不支持该参数。
ignore_chat_banned	Boolean	否	是否忽略聊天室的临时禁言。false（默认）：不忽略，即消息发送者不能是临时禁言的聊天室成员。
history_enabled	Boolean	否	该消息是否存云端历史。默认为 true（存储）。
high_priority	Boolean	否	是否发送高优先级消息，网易云信会优先保障投递此类消息，默认为 false（低优先级）。 若需要重发高优先级消息，可以设置 need_high_priority_msg_resend 参数。建议恰当使用该参数，以便在必要时，优先保障应用内的高优先级消息的投递。若全部设置为高优先级，则等于没有设置，单个聊天室最多支持每秒 10 条高优先级消息，超过的默认转为普通消息。
need_high_priority_msg_resend	Boolean	否	高优先级消息重发标记。默认为 false（不重发）。若设置为 true，当用户离开聊天室之后重新加入聊天室，在有效期内（30s）还会收到发送的此条消息。该参数只有在 high_priority = true 时才生效。
abandon_ratio	Integer	否	消息丢弃的概率，取值范围 [0-9999]。0（默认）：不丢弃消息；9999：99.99% 的概率丢弃消息。此参数可用于流控特定业务类型的消息。若设置该参数，则 high_priority 参数设置无效。
notify_target_tags	String	否	目标 标签表达式，用于设定聊天室消息提醒的投递对象，长度上限 128 位字符。
chat_msg_priority	Integer	否	走 CDN 通道的消息的优先级，可选值：0（默认），1，2，3
forbidden_if_high_priority_msg_freq	Integer	否	高优先级消息被频控后是降级为普通消息还是返回 403 错误码。 0（默认）：降级为普通消息；1：返回 403 错误码。
- route_config	Object	否	抄送相关配置项。
route_enabled	Boolean	否	该消息是否需要抄送至指定的应用服务器（需要为应用开通消息抄送功能），默认为 true（抄送）。
route_environment	String	否	当前消息需要抄送到的环境的名称，对应您在网易云信控制台中配置的自定义抄送的环境名称。
- antispam_config	Object	否	安全通相关配置项。
antispam_enabled	Boolean	否	该消息（除自定义消息）是否需要过安全通审核。 若已在 网易云信控制台 开通安全通，该参数默认为 true（过审核），若需要设置单条消息不经过审核，则设置为 fasle。 若未开通安全通，该参数无效。
antispam_business_id	String	否	安全通业务 ID，可以指定当前消息过安全通某个检测策略。 默认情况下网易云信控制后台会生成默认业务，开通安全通后，客户端不需要配置业务 ID 就能默认走该策略，若需要自定义检测策略，请 提交工单 联系网易云信技术支持工程师进行配置，配置好后传入对应的安全通业务 ID，表示当前消息过安全通的指定检测策略。
antispam_extension	String	否	透传给易盾的反垃圾增强版的检测参数，格式为 JSON，长度限制 1024 位字符（具体请参考易盾的反垃圾增强版用户 可扩展参数）。反作弊相关的 email、phone、token、extension，抄送到 antispam_cheating 参数中。其他用户增值信息，抄送到 antispam_extension 参数。
antispam_cheating	String	否	透传给易盾的反作弊检测参数，格式为 JSON，长度限制 1024 位字符（具体请参考易盾的反垃圾防刷版 专属参数）。反作弊相关的 email、phone、token、extension，抄送到 antispam_cheating 参数中。其他用户增值信息，抄送到 antispam_extension 参数。 antispam_extension 传入的值默认覆盖 extension。
antispam_custom_message_enabled	Boolean	否	是否对自定义消息的指定内容（antispam_custom_message）进行审核。 若已在 网易云信控制台 开通安全通，该参数默认为 false（不过审核），若需要设置该条自定义消息经过审核，则设置为 true。 若未开通安全通，该参数无效。
antispam_custom_message	String	否	自定义的安全通检测内容, JSON 格式，长度限制同 text 参数。格式如下： {"type":1,"data":"custom content"} 字段说明： type: 1 为文本；2 为图片；3 为视频；4 为音频；5 为图文 data: type 为 1、2、3、4 时，data 为字符串，分别传入文本内容、图片地址、视频/音频地址。 type 为 5 时，data 为 JSON 格式，例如： { "text":""，//1 个文本 必填 "images":["url1,"url2"], //最大 6 个图片 必填 "textbid":"", //文本检测业务 ID 选填 "picbid":"" //图片检测业务 ID 选填 } 该参数只对自定义消息（message_type = 100）且 ntispam_custom_message_enabled = true 时才生效。

请求体示例

JSON{
  "sender_id": "gg",
  "room_id": 72,
  "receiver_ids": ["wmtest2", "不存在的 account_id", "movnrlqeweo9qi0ymlrjhn7jtzhsmv9q0"],
  "extension": "laboris enim aliqua sint nostrud",
  "messages": [
    {
      "message_type": 0,
      "text": "proident Excepteur irure",
      "message_client_id": "dfdfsdfdsf-dfsdfsd-werewrw-11",
      "sub_type": 10
    }
  ],
  "route_config": {
    "route_enabled": true
  },
  "message_config": {
    "ignore_mute": false
  }
}

响应信息

响应头参数

响应 Header 的参数说明请参考 响应 Header。

响应体参数

参数名称	类型	说明	是否必返回
code	Integer	状态码，200 表示请求成功。	是
msg	String	提示信息。请求失败时返回错误信息，请求成功时返回 "success"。	是
- data	Object	返回的 JSON 数据对象，请求失败则返回空对象。	是
- success_list	Array of objects	发送成功的消息列表。	是
message_client_id	String	消息客户端 ID。	是
create_time	Long	消息发送时间戳。	是
message_type	Integer	消息类型。0：文本消息；1：图片消息；2：语音消息；3：视频消息；4：地理位置消息；6：文件消息；10：提示消息；100：自定义消息。	是
sender_id	String	消息发送方账号 ID。	是
sender_nick	String	消息发送者昵称。	否
sender_avatar	String	消息发送者头像 URL。	否
room_id	Long	聊天室 ID。	是
text	String	文本/提示消息内容或多媒体消息的描述文本（该描述信息可用于云端历史消息关键词检索）。	否
attachment	Object	多媒体消息的属性或自定义消息内容。	否
msg_abandon	Boolean	消息是否被限流丢弃。	否
high_priority	Boolean	消息是否为高优消息。	否
sub_type	Integer	消息子类型。	否
- failed_list	Object	发送失败的列表。	否
- failed_account_ids	Array of objects	发送失败的账号信息列表。	否
account_id	String	IM 账号 ID。	否
error_code	Integer	操作失败的错误码。	否
error_msg	String	操作失败的错误信息。	否
- failed_messages	Array of objects	发送失败的信息列表。	否
message_client_id	String	IM 账号 ID。	否
error_code	Integer	操作失败的错误码。	否
error_msg	String	操作失败的错误信息。	否

响应体示例

JSON{
    "code": 200,
    "msg": "success",
    "data": {
        "success_list": [
            {
                "text": "{\"msg\":\"2025-07-17T13:47:33.620文本消息测试-e9e7sdjdk1\"}",
                "message_client_id": "ec7c8***772a9a6",
                "create_time": 1752731254252,
                "message_type": 0,
                "sender_id": "test",
                "sender_nick": "test的昵称",
                "sender_avatar": "",
                "room_id": 11654762785,
                "high_priority": false
            }
        ]
    }
}

错误码

本文仅列举部分业务接口错误码，完整列表请参考客户端 API 错误码。

错误码	错误码描述	错误信息示例
200	请求成功	success
414	参数错误	parameter error
102404	用户不存在	account not exist
102422	用户被禁用	account banned
103404	用户资料不存在	user profile not exist
107410	该 App 未开启发消息功能	messaging function disabled
107304	高优消息超过频控限制	rate limit of high-priority messages exceeded
107305	ack 消息必须是高优消息	ack message should be high-priority
107306	消息 ID 重复	duplicate client message ID
107451	该消息未通过反垃圾审核	message hit antispam
113410	聊天室服务未开通	chatroom service disabled
113404	聊天室不存在	chatroom not exist
113406	聊天室已关闭	chatroom closed
113423	聊天室全体禁言	all chatroom members chat banned
113302	聊天室标签成员被禁言	chatroom tagged members chat banned
500	服务器内部错误	internal server error