Group block list

Keep certain users out of a group, typically so a removed member can't come back.

For example, remove sunqi from the group and keep them from rejoining:

bash

curl -X PUT "$IM_API/$ORG/$APP/groups/99582624883802112/blacklist/sunqi" \
  -H "Authorization: Bearer $APP_TOKEN"

After a user is added to the group block list:

If they're in the group, they're removed from it, and they and the group's online members are notified in real time.
They can't join the group again: they can't apply, be invited by members or join through an invite link, and adding them from the server fails too (permission_denied, details.reason group_blacklisted).
Their pending join requests and invitations for this group become invalid immediately (cancel_cause blacklisted).

Users who aren't in the group can be blocked too, to keep them out in advance. Unblocking doesn't put a user back in the group; add them again or let them apply. The group block list only affects this group and has nothing to do with the block list between users.

Each group's block list holds up to 1000 users. The owner can't be added. Banned groups can still manage their block list.

Group block lists in clients

Owners and admins can also manage the group block list from clients. Each entry records the role of whoever added it in created_by_role: in clients, admins can only remove entries added by admins, while entries added by the owner or the server can only be removed by the owner. Server APIs can remove any entry.

List the group block list

Get the group block list page by page. Users whose accounts were deleted aren't listed, so a page may have fewer than limit items; rely on next_cursor to know whether there's another page.

GET/{org_name}/{app_name}/groups/{group_id}/blacklist

Path parameters

For org_name and app_name, see the server overview.

Parameter	Type	Description
`group_id`	String	The group ID

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

bash

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

Response

On success you get 200 OK, with each item in items a group block list entry and the next page's cursor in next_cursor (null when there's no next page).

json

{
  "items": [
    {
      "username": "zhouba",
      "nickname": "周八",
      "avatar_url": "https://cdn.example.com/avatar/zhouba.png",
      "reason": "刷屏",
      "created_by": "wangwu",
      "created_by_role": "admin",
      "created_at": "2026-10-02T19:21:57.068Z"
    },
    {
      "username": "zhengshi",
      "nickname": "郑十",
      "avatar_url": "https://cdn.example.com/avatar/zhengshi.png",
      "reason": "发布广告",
      "created_by": null,
      "created_by_role": "server",
      "created_at": "2026-10-02T19:10:34.181Z"
    }
  ],
  "next_cursor": null
}

Errors

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

Add a user to the group block list

Add a user to the group block list; if they're a member, they're also removed from the group, with a removal notice in the group conversation.

If the user is already blocked, nothing changes: the original entry (reason and who added it) stays and changed is false, so retries are safe.

PUT/{org_name}/{app_name}/groups/{group_id}/blacklist/{username}

Path parameters

For org_name and app_name, see the server overview.

Parameter	Type	Description
`group_id`	String	The group ID
`username`	String	The user to block

Request body

The body is optional.

Field	Type	Required	Description
`reason`	String	No	Reason, up to 256 characters without line breaks or other control characters. Owners and admins see it when viewing the group block list in clients

Request example

bash

curl -X PUT "$IM_API/$ORG/$APP/groups/99582624883802112/blacklist/zhaoliu" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "多次发布广告"
  }'

Response

On success you get 200 OK:

Field	Type	Description
`entry`	Object	The user's group block list entry; the original entry if they were already blocked
`changed`	Boolean	Whether this request newly blocked the user
`member_version`	Number	The member list version: the new version if the user was a member and got removed, otherwise the current one

json

{
  "entry": {
    "username": "zhaoliu",
    "nickname": "赵六",
    "avatar_url": "https://cdn.example.com/avatar/zhaoliu.png",
    "reason": "多次发布广告",
    "created_by": null,
    "created_by_role": "server",
    "created_at": "2026-10-02T19:22:03.134Z"
  },
  "changed": true,
  "member_version": 26
}

Errors

HTTP status	`code`	Description
400	`invalid_argument`	`reason` is longer than 256 characters or has control characters
403	`permission_denied`	The user is the owner and can't be blocked
404	`not_found`	The group doesn't exist or was dissolved, or the user doesn't exist
409	`limit_exceeded`	`details.reason` `group_blacklist_limit`: the group block list already has 1000 users

Remove a user from the group block list

Remove a user from the group block list so they can join the group again. It doesn't add them back. If they weren't blocked, nothing changes and changed is false.

DELETE/{org_name}/{app_name}/groups/{group_id}/blacklist/{username}

Path parameters

For org_name and app_name, see the server overview.

Parameter	Type	Description
`group_id`	String	The group ID
`username`	String	The user to unblock

Request example

bash

curl -X DELETE "$IM_API/$ORG/$APP/groups/99582624883802112/blacklist/zhaoliu" \
  -H "Authorization: Bearer $APP_TOKEN"

Response

On success you get 200 OK:

Field	Type	Description
`changed`	Boolean	Whether this request unblocked the user
`member_version`	Number	The current member list version (unblocking doesn't change the member list)

json

{
  "changed": true,
  "member_version": 26
}

Errors

HTTP status	`code`	Description
404	`not_found`	The group doesn't exist or was dissolved, or the user doesn't exist

Data structures

Group block list entry

Field	Type	Description
`username`	String	The blocked username
`nickname`	String	The nickname from their profile; empty string if none
`avatar_url`	String	The avatar address from their profile; empty string if none
`reason`	String	The reason; empty string if none
`created_by`	String	The owner or admin who did it from a client; `null` when added by the server or console, or when that person was deleted
`created_by_role`	String	The role of whoever added it: `owner`, `admin` or `server` (server or console). Later ownership transfers and role changes don't change it
`created_at`	String	When they were blocked

json

{
  "username": "zhouba",
  "nickname": "周八",
  "avatar_url": "https://cdn.example.com/avatar/zhouba.png",
  "reason": "刷屏",
  "created_by": "wangwu",
  "created_by_role": "admin",
  "created_at": "2026-10-02T19:21:57.068Z"
}

Group block list ​

List the group block list ​

Path parameters ​

Query parameters ​

Request example ​

Response ​

Errors ​

Add a user to the group block list ​

Path parameters ​

Request body ​

Request example ​

Response ​

Errors ​

Remove a user from the group block list ​

Path parameters ​

Request example ​

Response ​

Errors ​

Data structures ​

Group block list entry ​

Group block list

List the group block list

Path parameters

Query parameters

Request example

Response

Errors

Add a user to the group block list

Path parameters

Request body

Request example

Response

Errors

Remove a user from the group block list

Path parameters

Request example

Response

Errors

Data structures

Group block list entry