功能描述

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

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

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

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

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

调用频率

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

请求

URL

POST https://open.yunxinapi.com/im/v2/chatrooms/messages

Header

请求 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 格式，长度上限为 4096 位字符。例如："{"k":"v"}"
+ 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	可选	非文本消息/提示消息的属性或自定义消息内容，长度上限 5000 位字符。 对于非文本消息/提示消息，该字段必填，每种消息的属性参数见：消息格式示例。
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 为图片 data: 文本内容或图片地址。该参数只对自定义消息（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 的参数说明请参见响应 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	消息类型。	是
sender_id	String	消息发送方帐号 ID。	是
room_id	Long	聊天室 ID。	是
text	String	文本/提示消息内容或多媒体消息的描述文本（该描述信息可用于云端历史消息关键词检索）。	是
attachment	Object	多媒体消息的属性或自定义消息内容。	否
msg_abandon	Boolean	消息是否被限流丢弃。	否
high_priority	Boolean	消息是否为高优消息。	否
+ failed_list	Object	发送失败的列表。	否
+ failed_account	Array of objects	发送失败的账号列表。	否
account_id	String	云信账号 ID。	否
error_code	Integer	操作失败的错误码。	否
error_msg	String	操作失败的错误信息。	否
+ failed_messages	Array of objects	发送失败的信息列表。	否
message_client_id	String	云信账号 ID。	否
error_code	Integer	操作失败的错误码。	否
error_msg	String	操作失败的错误信息。	否

响应体示例

json{
    "code": 200,
    "msg": "success",
    "data": {
        "success_list": [
            {
                "text": "proident Excepteur irure",
                "message_client_id": "dfdfsdfdsf-dfsdfsd-werewrw-11",
                "create_time": 1698667510463,
                "message_type": 0,
                "sender_id": "gg",
                "sender_nick": "123",
                "sender_avatar": "",
                "room_id": 72,
                "high_priority": false,
                "sub_type": 10
            }
        ],
        "failed_list": {
            "failed_account_ids": [
                {
                    "account_id": "fgfdgfdgd",
                    "error_code": 102404,
                    "error_msg": "fgfdgfdgd not exist"
                }
            ],
            "failed_messages": [
                {
                    "message_client_id": "dfdfsdfdsf-dfsdfsd-werewrw-12",
                    "error_msg": "message hit antispam",
                    "error_code": 107451
                }
            ]
        }
    }
}

错误码

错误码	错误码描述	错误信息示例
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