聊天室 API

聊天室模块覆盖创建与销毁、信息与在线成员、保活与销毁策略、房间 KV、成员禁言/封禁/白名单、全员禁言、消息优先级与 RTC 房间绑定。

模块概览​

项目值
接口数量35
幂等接口12
路径前缀/im/v2
请求方法POST(JSON 请求体)
鉴权方式App-Key / Nonce / Timestamp / Signature(见 鉴权与签名)
响应信封{ code, msg?, data?, requestId? }

接口列表​

接口方法路径说明幂等
创建聊天室POST/im/v2/chatroom/create创建聊天室(幂等:同 chatroomId 已存在则返回现有)。是
销毁聊天室POST/im/v2/chatroom/destroy销毁聊天室:踢出所有在线成员、广播 destroyed。否
聊天室信息POST/im/v2/chatroom/get聊天室信息(含在线数)。否
聊天室在线成员列表POST/im/v2/chatroom/members/list聊天室在线成员列表。否
刷新聊天室空闲销毁时间POST/im/v2/chatroom/keepalive刷新聊天室空闲销毁时间(默认 30 分钟无活动销毁)。否
设置聊天室 KVPOST/im/v2/chatroom/kv/set设置聊天室 KV(房间级键值,随房间销毁;ttlMs 可选)。是
读取聊天室 KVPOST/im/v2/chatroom/kv/get读取聊天室 KV(keys 省略返回全部)。否
删除聊天室 KVPOST/im/v2/chatroom/kv/remove删除聊天室 KV。否
聊天室成员禁言/解禁POST/im/v2/chatroom/mute聊天室成员禁言/解禁(mutedUntil=0 解禁;房主/管理员可操作)。否
聊天室封禁/解封成员POST/im/v2/chatroom/ban聊天室封禁/解封成员(封禁后被踢出且不可再加入)。否
聊天室白名单POST/im/v2/chatroom/whitelist/add聊天室白名单:加入(白名单内用户不受封禁/禁言限制)。否
聊天室白名单POST/im/v2/chatroom/whitelist/remove聊天室白名单:移除。否
聊天室白名单POST/im/v2/chatroom/whitelist/list聊天室白名单:查询。否
设置/取消聊天室全体禁言POST/im/v2/chatroom/mute-all设置/取消聊天室全体禁言(房主/管理员可操作;白名单成员不受限)。是
查询聊天室全体禁言状态POST/im/v2/chatroom/mute-all/get查询聊天室全体禁言状态。否
设置聊天室销毁策略POST/im/v2/chatroom/destroy/policy/set设置聊天室销毁策略(idle=空闲销毁,idleMs 默认 1800000;fixed=定时销毁,destroyAt 由创建时间+idleMs 计算)。否
设置聊天室低优先级消息类型POST/im/v2/chatroom/message/priority/set设置聊天室低优先级消息类型(全量覆盖)。是
查询聊天室低优先级消息类型POST/im/v2/chatroom/message/priority/list查询聊天室低优先级消息类型。否
绑定聊天室与音视频房间POST/im/v2/chatroom/rtc/bind绑定聊天室与音视频房间(RTC 房间号仅存储,音视频能力需外部服务)。是
查询聊天室绑定的音视频房间POST/im/v2/chatroom/rtc/get查询聊天室绑定的音视频房间。否
查询聊天室封禁用户列表POST/im/v2/chatroom/user/block/list查询聊天室封禁用户列表(分页)。覆盖融云 /chatroom/user/block/list.json;time 为解禁时间(UTC),空串表示封禁未设置时长。否
查询应用下已设置保活状态的聊天室列表POST/im/v2/chatroom/keepalive/query查询应用下已设置保活状态的聊天室列表。覆盖融云 /chatroom/keepalive/query.json。否
移除聊天室保活状态并恢复空闲销毁计时POST/im/v2/chatroom/keepalive/remove移除聊天室保活状态并恢复空闲销毁计时。覆盖融云 /chatroom/keepalive/remove.json。是
查询指定用户是否在聊天室中POST/im/v2/chatroom/user/exist查询指定用户是否在聊天室中。覆盖融云 /chatroom/user/exist.json。否
批量查询用户是否在聊天室中POST/im/v2/chatroom/users/exist批量查询用户是否在聊天室中(单次 <=1000;isInChrm 1=在 0=不在)。覆盖融云 /chatroom/users/exist.json。否
查询聊天室禁言用户列表POST/im/v2/chatroom/user/gag/list查询聊天室禁言用户列表(仅返回未到期记录,time 为解禁时间)。覆盖融云 /chatroom/user/gag/list.json。否
全局禁言用户POST/im/v2/chatroom/user/ban/add全局禁言用户:应用下所有聊天室生效,仅约束客户端发送;单次 <=20 用户,minute 1..=43200。覆盖融云 /chatroom/user/ban/add.json。是
解除用户全局禁言POST/im/v2/chatroom/user/ban/remove解除用户全局禁言(单次 <=20 用户;幂等)。覆盖融云 /chatroom/user/ban/remove.json。是
查询应用下已被全局禁言的用户列表POST/im/v2/chatroom/user/ban/query查询应用下已被全局禁言的用户列表(含解禁时间;到期记录惰性清理)。覆盖融云 /chatroom/user/ban/query.json。否
添加消息类型到聊天室消息白名单POST/im/v2/chatroom/whitelist/add.json添加消息类型到聊天室消息白名单(应用级共享,<=20 种,标识 <=32 字符;重复添加幂等)。覆盖融云 /chatroom/whitelist/add.json;路径带 .json 以避开 rev4 用户白名单占用的 /chatroom/whitelist/add。是
查询应用全局的聊天室消息类型白名单POST/im/v2/chatroom/whitelist/query.json查询应用全局的聊天室消息类型白名单。覆盖融云 /chatroom/whitelist/query.json。否
从聊天室消息白名单移除消息类型POST/im/v2/chatroom/whitelist/delete.json从聊天室消息白名单移除消息类型(幂等)。覆盖融云 /chatroom/whitelist/delete.json。是
向应用下所有聊天室广播消息POST/im/v2/message/chatroom/broadcast向应用下所有聊天室广播消息(仅广播当时在线成员,不落聊天室历史;默认不同步发件人)。覆盖融云 /message/chatroom/broadcast.json。否
批量设置聊天室自定义属性POST/im/v2/chatroom/entry/batch/set批量设置聊天室自定义属性(按 entryOwnerId 隔离,单次 <=100 对;同 key 覆盖)。覆盖融云 /chatroom/entry/batch/set.json。是
批量移除聊天室自定义属性POST/im/v2/chatroom/entry/batch/remove批量移除聊天室自定义属性(<=100 个 key,按 entryOwnerId 隔离,幂等)。覆盖融云 /chatroom/entry/batch/remove.json。是

相关回调事件​

接口约定​

  • 完整请求地址 = 部署域名 + /im/v2 + 接口路径;所有接口使用 POST。
  • 请求头必须携带 App-Key / Nonce / Timestamp / Signature;签名规则见鉴权与签名。
  • 响应统一为 { code, msg?, data?, requestId? };code = 0 表示成功。
  • 列表类接口使用 limit 分页,单页上限见限频与限制。

相关说明​