用户的群

本页的接口以用户为中心：查询一个用户加入了哪些群，以及查询和修改用户的入群设置（被成员邀请时是否需要本人确认）。

查询用户加入的群

分页返回一个用户加入的群，每项为完整的群组对象，另带这个用户在群里的角色、群昵称和禁言状态。被封禁的群也在列表中；群解散后约 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	用户不存在