全局禁言

全局禁言禁止用户在某个场景发送消息，例如禁止他发单聊消息，或禁止他在所有群里发言。禁言期间用户可以正常登录、接收消息和查看历史消息，只是不能在该场景发送。禁言可以是永久的，也可以指定时长，到期自动解除。

禁言按场景（scope）分别设置：

scope	场景	禁言后
chat	单聊	不能发送单聊消息
group	群聊	不能在任何群里发送消息
room	聊天室	不能在任何聊天室中发送消息

• 被禁言的用户在客户端发送消息时，收到 403 user_muted，details.scope 为禁言的场景，details.expires_at 为到期时间（永久禁言为 null），客户端可以据此提示禁言到什么时候；
• 业务服务端通过 OpenAPI 以用户的身份发送消息不受全局禁言限制，由你的业务自行决定能否发送；
• 全局禁言与群内的禁言（群主、管理员设置的成员禁言和全员禁言）相互独立，任意一个生效都不能在群里发送；
• 设置或解除禁言时，该用户在线的设备会收到通知；
• 删除用户时，他的全局禁言一并清除。已封禁的用户也可以设置和解除禁言，不影响封禁状态；
• 内容安全的自动处罚，以及你的审核人员确认违规时选择的禁言，也会为用户设置全局禁言，自动处罚的原因形如“内容安全：自动处罚（24 小时内违规 3 次）”，可以照常查询和解除；
• 应用处于只读状态时仍可以设置和解除禁言。

被禁言的用户在客户端发送单聊消息时收到的错误：

{
  "error": {
    "code": "user_muted",
    "message": "你已被禁言",
    "details": { "scope": "chat", "expires_at": "2026-10-03T19:09:20.771Z" },
    "request_id": "M7DXC7YMRRYILTNTIYJZBMC3KQ"
  }
}

查询用户的禁言

查询一个用户当前生效的禁言，每个场景最多一项，按 chat、group、room 的顺序排列。已经到期的禁言不返回。

GET/{org_name}/{app_name}/users/{username}/mutes

路径参数

org_name、app_name 见接入概述。

参数	类型	说明
username	String	用户名

请求示例

curl "$IM_API/$ORG/$APP/users/zhaoliu/mutes" \
  -H "Authorization: Bearer $APP_TOKEN"

响应

成功返回 200 OK。items 为当前生效的禁言，每项为禁言对象；没有禁言时为空数组。结果不分页。

{
  "items": [
    { "scope": "chat", "expires_at": "2026-10-03T19:09:20.771Z", "reason": "发布广告" },
    { "scope": "group", "expires_at": null, "reason": "" }
  ]
}

错误

HTTP 状态码	code	说明
404	not_found	用户不存在或已删除

设置禁言

在指定场景禁言用户。对已经禁言的场景再次设置时，按本次的参数覆盖到期时间和原因：省略 duration_seconds 会改为永久禁言，省略 reason 会清空原因，限时禁言从本次调用时重新计算到期时间。

PUT/{org_name}/{app_name}/users/{username}/mutes/{scope}

路径参数

org_name、app_name 见接入概述。

参数	类型	说明
username	String	用户名
scope	String	禁言的场景：chat、group 或 room

请求体

请求体可以省略，省略时为永久禁言、不填原因。

字段	类型	必填	说明
duration_seconds	Number	否	禁言时长，单位为秒，1 到 315360000（10 年）。省略表示永久禁言
reason	String	否	禁言原因，最长 256 个字符，不能包含控制字符

请求示例

禁止用户发送单聊消息 1 天：

curl -X PUT "$IM_API/$ORG/$APP/users/zhaoliu/mutes/chat" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "duration_seconds": 86400,
    "reason": "发布广告"
  }'

响应

成功返回 200 OK，响应体为禁言对象。

{
  "scope": "chat",
  "expires_at": "2026-10-03T19:09:20.771Z",
  "reason": "发布广告"
}

错误

HTTP 状态码	code	说明
400	invalid_argument	scope 不是 chat、group 或 room；duration_seconds 不在 1 到 315360000 之间；reason 超过 256 个字符或包含控制字符
404	not_found	用户不存在或已删除

解除禁言

解除用户在指定场景的禁言。用户在该场景没有禁言时同样返回成功，可以放心重试。

DELETE/{org_name}/{app_name}/users/{username}/mutes/{scope}

路径参数

org_name、app_name 见接入概述。

参数	类型	说明
username	String	用户名
scope	String	禁言的场景：chat、group 或 room

请求示例

curl -X DELETE "$IM_API/$ORG/$APP/users/zhaoliu/mutes/chat" \
  -H "Authorization: Bearer $APP_TOKEN"

响应

成功返回 204 No Content，没有响应体。

错误

HTTP 状态码	code	说明
400	invalid_argument	scope 不是 chat、group 或 room
404	not_found	用户不存在或已删除

查询被禁言的用户列表

分页列出应用中当前被禁言的用户，已经到期的禁言不列出。每项是一个用户在一个场景的禁言，同一个用户在多个场景被禁言时出现多次。结果按用户和场景排序，分页方式见分页，换了 scope 后请从第一页开始查询。

GET/{org_name}/{app_name}/mutes

查询参数

参数	类型	必填	说明
scope	String	否	只列出该场景的禁言：chat、group 或 room。省略时列出全部场景
limit	Number	否	每页数量，1 到 100，默认 20
cursor	String	否	分页游标，取上一页响应中的 next_cursor；省略时从第一页开始

请求示例

curl "$IM_API/$ORG/$APP/mutes?scope=group" \
  -H "Authorization: Bearer $APP_TOKEN"

响应

成功返回 200 OK：

字段	类型	说明
items	Array<Object>	本页的禁言，每项为禁言对象，带 username
next_cursor	String	下一页的游标，可为 null（没有下一页）

{
  "items": [
    { "username": "zhaoliu", "scope": "group", "expires_at": null, "reason": "" },
    { "username": "sunqi", "scope": "group", "expires_at": "2026-10-02T20:09:20.839Z", "reason": "" }
  ],
  "next_cursor": null
}

错误

HTTP 状态码	code	说明
400	invalid_argument	scope 不是 chat、group 或 room；limit 超出范围；游标无效

数据结构

禁言对象

字段	类型	说明
username	String	用户名，只在查询被禁言的用户列表中返回
scope	String	禁言的场景：chat 单聊，group 群聊，room 聊天室
expires_at	String	到期时间，到期后自动解除。可为 null，表示永久禁言
reason	String	禁言原因，没有时为空字符串

{
  "scope": "chat",
  "expires_at": "2026-10-03T19:09:20.771Z",
  "reason": "发布广告"
}