全域性禁言

禁止使用者在某個場景發訊息，例如不讓他發單聊，或不讓他在任何群裡發言。禁言期間他照常登入、收訊息、看歷史，只是不能在這個場景傳送。可以永久禁言，也可以限時、到期自動解除。

例如，禁止 zhaoliu 發單聊訊息 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": "发布广告" }'

按場景（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": "发布广告"
}