A user's groups

Group APIs centered on one user.

You want to	API
See which groups a user is in (with their role, group nickname and mute status)	List a user's groups
See or change whether invitations need the user's confirmation	Get a user's group settings, Change a user's group settings

For example, list the groups zhangsan is in:

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

List a user's groups

Get the groups a user is in, page by page. Each item is a full group object plus the user's role, group nickname and mute status in it. Banned groups are included; for about an hour after a group is dissolved, before members are removed, it's included too with status dismissed.

Groups are sorted by ascending group ID, roughly oldest first.

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

Path parameters

For org_name and app_name, see the server overview.

Parameter	Type	Description
username	String	The username

Query parameters

Parameter	Type	Required	Description
limit	Number	No	Page size, default 20, 1 to 100
cursor	String	No	The cursor for the next page, see Paging

Request example

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

Response

On success you get 200 OK. Each item in items is a group object with one extra field:

Field	Type	Description
self	Object	The user's info in the group, fields below

Fields of self:

Field	Type	Description
role	String	owner, admin or member
group_nickname	String	Group nickname; empty string if none
muted	Boolean	Whether they're currently muted in this group (not counting mute-all)
muted_until	String	When the mute ends; null for permanent mutes or when not muted
joined_at	String	When they joined the group

next_cursor is the next page's cursor, null when there's no next page.

{
  "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
}

Errors

HTTP status	code	Description
400	invalid_argument	limit is out of range
404	not_found	The user doesn't exist

Get a user's group settings

Get the user's group invitation mode: whether they join directly when a member invites them from a client, or need to confirm first:

Value	Description
allow_any	Join directly when invited
need_confirm	Get an invitation and join only after accepting, see Join requests and invitations

Users who never set one use default_group_invite_mode from the app's runtime policy (allow_any by default). It only affects invitations members send from clients (including initial members when a user creates a group in a client); server group creation and adding members add people directly regardless. Users can also change it themselves in clients.

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

Path parameters

For org_name and app_name, see the server overview.

Parameter	Type	Description
username	String	The username

Request example

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

Response

On success you get 200 OK:

Field	Type	Description
invite_mode	String	The user's own setting: allow_any or need_confirm; null if never set
effective_invite_mode	String	The mode in effect: the user's setting if any, otherwise the app default

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

Errors

HTTP status	code	Description
404	not_found	The user doesn't exist

Change a user's group settings

Set whether invitations need the user's confirmation, or go back to the app default. Only later invitations are affected; ones already sent aren't.

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

Path parameters

For org_name and app_name, see the server overview.

Parameter	Type	Description
username	String	The username

Request body

Field	Type	Required	Description
invite_mode	String	Yes	allow_any or need_confirm; null clears the user's setting so the app default applies. The field must be present

Request example

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"
  }'

Response

On success you get 200 OK with the same fields as Get a user's group settings. Setting the same value as before also succeeds.

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

Errors

HTTP status	code	Description
400	invalid_argument	invite_mode is missing, or isn't allow_any, need_confirm or null
404	not_found	The user doesn't exist