使用者的群

以使用者為中心的群介面。

要做什麼	介面
查一個使用者加入了哪些群（帶他的角色、群暱稱、禁言狀態）	查詢使用者加入的群
查或改“被邀請時要不要本人確認”	查詢使用者的入群設定、修改使用者的入群設定

例如，查 zhangsan 加入的群：

curl "$IM_API/$ORG/$APP/users/zhangsan/groups" \
  -H "Authorization: Bearer $APP_TOKEN"

查詢使用者加入的群

分頁返回一個使用者加入的群，每項為完整的群組物件，另帶這個使用者在群裡的角色、群暱稱和禁言狀態。被封禁的群也在列表中；群解散後約 1 小時內成員還未被移出，這時已解散的群也在列表中，status 為 dismissed。

群按群 ID 從小到大排列，即大致按建立時間從早到晚。

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

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
username	String	使用者名稱

查詢引數

引數	型別	必填	說明
limit	Number	否	每頁條數，預設 20，取值 1 到 100
cursor	String	否	下一頁的遊標，見分頁

請求示例

curl -X GET "$IM_API/$ORG/$APP/users/sunqi/groups" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK，items 中每項為一個群組物件，另加一個欄位：

欄位	型別	說明
self	Object	這個使用者在群裡的資訊，欄位見下表

self 的欄位：

欄位	型別	說明
role	String	角色：owner 群主，admin 管理員，member 普通成員
group_nickname	String	群暱稱，沒有時為空字串
muted	Boolean	當前是否在這個群裡被禁言（不含全員禁言）
muted_until	String	禁言的到期時間；永久禁言或沒有被禁言時為 null
joined_at	String	加入群的時間

next_cursor 為下一頁的遊標，沒有下一頁時為 null。

{
  "items": [
    {
      "group_id": "99582688326844416",
      "type": "public",
      "name": "摄影爱好者",
      "avatar_url": "",
      "description": "分享作品，交流器材",
      "announcement": "",
      "announcement_updated_at": null,
      "announcement_updated_by": null,
      "attributes": null,
      "owner": "lisi",
      "member_invite": "approval",
      "join_mode": "approval",
      "mute_all": false,
      "max_members": 500,
      "member_count": 5,
      "status": "active",
      "disabled_by": null,
      "info_version": 12,
      "member_version": 5,
      "created_at": "2026-10-02T19:06:03.054Z",
      "status_reason": null,
      "max_members_setting": null,
      "created_via": "openapi",
      "dismissed_at": null,
      "self": {
        "role": "member",
        "group_nickname": "",
        "muted": false,
        "muted_until": null,
        "joined_at": "2026-10-02T19:10:46.913Z"
      }
    }
  ],
  "next_cursor": null
}

錯誤

HTTP 狀態碼	code	說明
400	invalid_argument	limit 超出範圍
404	not_found	使用者不存在

查詢使用者的入群設定

返回使用者的入群邀請方式，即被群成員在客戶端邀請時，是直接入群還是需要本人確認：

取值	說明
allow_any	被邀請時直接入群
need_confirm	被邀請時收到一條邀請，本人接受後才入群，見入群申請與邀請

使用者沒有設定過時，使用應用執行策略中的 default_group_invite_mode（預設 allow_any）。這項設定隻影響成員在客戶端發出的邀請（包括使用者在客戶端建群時拉入的初始成員）；服務端建群和新增成員時直接入群，不看這項設定。使用者也可以在客戶端自己修改。

GET/{org_name}/{app_name}/users/{username}/group-settings

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
username	String	使用者名稱

請求示例

curl -X GET "$IM_API/$ORG/$APP/users/zhouba/group-settings" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK：

欄位	型別	說明
invite_mode	String	使用者自己的設定：allow_any 或 need_confirm；沒有設定過時為 null
effective_invite_mode	String	實際生效的入群邀請方式：使用者設定過時為他的設定，否則為應用的預設值

{
  "invite_mode": null,
  "effective_invite_mode": "allow_any"
}

錯誤

HTTP 狀態碼	code	說明
404	not_found	使用者不存在

修改使用者的入群設定

設定使用者被邀請時是否需要本人確認，或恢復為使用應用的預設值。修改隻影響之後的邀請，已經發出的邀請不受影響。

PUT/{org_name}/{app_name}/users/{username}/group-settings

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
username	String	使用者名稱

請求體

欄位	型別	必填	說明
invite_mode	String	是	allow_any 或 need_confirm；為 null 時清除使用者的設定，改為使用應用的預設值。這個欄位必須出現

請求示例

curl -X PUT "$IM_API/$ORG/$APP/users/zhouba/group-settings" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "invite_mode": "need_confirm"
  }'

響應

成功返回 200 OK，欄位同查詢使用者的入群設定。與原來的設定相同時同樣返回成功。

{
  "invite_mode": "need_confirm",
  "effective_invite_mode": "need_confirm"
}

錯誤

HTTP 狀態碼	code	說明
400	invalid_argument	缺少 invite_mode，或取值不是 allow_any、need_confirm、null
404	not_found	使用者不存在