Chat room members
A chat room's members are whoever is in it right now: users become members when they enter from a client and stop being members when they leave or 15 seconds after disconnecting; membership isn't stored. For entering and leaving, roles and mute-all, see Chat room management.
To deal with a disruptive user in a live stream, pick by the effect you want:
| You want | Use | Can stay in the room | Can post | Can come back |
|---|---|---|---|---|
| Stop them talking | Mute users | Yes | No | — |
| Make them leave once | Remove members | No | — | Yes, right away |
| Keep them out for a while | Ban users (removes them automatically) | No | — | Only after it ends |
| Let guests post during mute-all | Add to the allowlist | Yes | Yes | — |
For example, ban troll for an hour:
curl -X POST "$IM_API/$ORG/$APP/chatrooms/100310941534519296/bans" \
-H "Authorization: Bearer $APP_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "usernames": ["troll"], "duration_seconds": 3600, "reason": "刷屏" }'To see online members or check whether a user is in the room, see List chat room members and Check whether a user is in the room.
Mutes, bans and the allowlist
These three lists are kept on the server regardless of who's in the room: you can act on users who aren't in it right now, and the lists still apply when users leave and come back.
| List | Effect | Duration | Limit per room |
|---|---|---|---|
| Mutes | Can't send messages or set attributes from clients; can still enter, receive messages and delete attributes they set. Sending returns 403 chatroom_muted with details.reason member and the end time in details.muted_until | 1 second to 10 years, or permanent; ends automatically | 10,000 active mutes |
| Bans | All the user's connections in the room are removed immediately, and they can't enter while banned: entering returns 403 permission_denied with details.reason chatroom_banned and the end time in details.expires_at. Banning an admin also removes their admin role | 1 second to 10 years, or permanent; ends automatically | 10,000 active bans |
| Allowlist | Can still send messages and set attributes during mute-all, good for guests in a stream. Individually muted users still can't post | Until removed from the allowlist | 500 users |
- The three lists are independent: a user can be on the allowlist and muted at once (then they can't post); bans don't remove users from the allowlist. Owners and admins aren't subject to mute-all anyway, but can be added to the allowlist, which takes effect once they're no longer owner or admin.
- The owner is protected: nobody can mute, remove or ban the owner, not even your server (
permission_denied,owner_protected). To deal with the owner, transfer or clear ownership first. Your server can mute, remove and ban admins. - Independent of global mutes: chat room mutes and a user's global mute (
roomscope) each stop them posting in chat rooms. Your server sending messages as them isn't limited. - Notifications: mutes, unmutes and allowlist changes are pushed to online members in real time, and the muted user's client disables its input box; mutes ending automatically aren't announced, so clients restore input locally from the end time they received. Removed and banned users get a removal notice (reason
kickedorbanned, with the end time for bans). - Timing: removals and bans usually take effect within a second.
Batch list APIs
Removing, muting, unmuting, banning, unbanning, and adding to and removing from the allowlist are all batch APIs: up to 100 users at a time, handled one by one so one failure doesn't affect the others, with each result listed in the response, see Batch results. They count toward the app's OpenAPI quota once per username, see Rate limits and app status.
Banned rooms can manage these lists too. While the app is read-only, only adding to the allowlist returns 403 app_unavailable; the other list operations and removals still work.
List chat room members
Get the users in the room right now, page by page, earliest entry first, each with their nickname, avatar and room role.
Users who stay in the room while you page appear exactly once; users who leave and re-enter while you page get a new entry time and may appear again on a later page, so deduplicate by username. 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.
/{org_name}/{app_name}/chatrooms/{room_id}/membersPath parameters
For org_name and app_name, see the server overview.
| Parameter | Type | Description |
|---|---|---|
room_id | String | The chat room ID |
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | Number | No | Page size, default 20, 1 to 1000 |
cursor | String | No | The cursor for the next page, see Paging |
Request example
curl -X GET "$IM_API/$ORG/$APP/chatrooms/100310941534519296/members?limit=3" \
-H "Authorization: Bearer $APP_TOKEN"Response
On success you get 200 OK, with each item in items a member object and the next page's cursor in next_cursor (null when there's no next page).
{
"items": [
{
"username": "zhangsan",
"nickname": "张三",
"avatar_url": "https://cdn.example.com/avatar/zhangsan.png",
"role": "owner",
"joined_at": "2026-10-04T19:20:32.763Z"
},
{
"username": "lisi",
"nickname": "李四",
"avatar_url": "https://cdn.example.com/avatar/lisi.png",
"role": "admin",
"joined_at": "2026-10-04T19:20:33.019Z"
},
{
"username": "wangwu",
"nickname": "王五",
"avatar_url": "https://cdn.example.com/avatar/wangwu.png",
"role": "member",
"joined_at": "2026-10-04T19:20:33.319Z"
}
],
"next_cursor": "1791141633319:100310462331092992"
}Errors
| HTTP status | code | Description |
|---|---|---|
| 400 | invalid_argument | limit is out of range, or cursor is invalid |
| 404 | not_found | The room doesn't exist or was dissolved |
| 500 | internal | details.reason dependency_unavailable: members are temporarily unreadable; wait for the Retry-After header and retry |
Check whether a user is in the room
Check whether a user is in the room right now, with their entry time and room role. The user is in the room if any of their devices is, including connections dropped less than 15 seconds ago.
/{org_name}/{app_name}/chatrooms/{room_id}/members/{username}Path parameters
For org_name and app_name, see the server overview.
| Parameter | Type | Description |
|---|---|---|
room_id | String | The chat room ID |
username | String | The username |
Request example
curl -X GET "$IM_API/$ORG/$APP/chatrooms/100310941534519296/members/lisi" \
-H "Authorization: Bearer $APP_TOKEN"Response
On success you get 200 OK:
| Field | Type | Description |
|---|---|---|
in_room | Boolean | Whether they're in the room right now |
joined_at | String | When they entered this time; null when not in the room |
role | String | Their room role: owner, admin or member, returned even when not in the room |
{
"in_room": true,
"joined_at": "2026-10-04T19:20:33.019Z",
"role": "admin"
}When the user isn't in the room:
{
"in_room": false,
"joined_at": null,
"role": "member"
}Errors
| HTTP status | code | Description |
|---|---|---|
| 404 | not_found | The room doesn't exist or was dissolved, or the user doesn't exist |
| 500 | internal | details.reason dependency_unavailable: members are temporarily unreadable; wait for the Retry-After header and retry |
Remove chat room members
Remove a batch of users from the room, up to 100 at a time. All their connections get a removal notice (reason kicked), and clients don't re-enter automatically; in rooms with at most chatroom_member_notify_limit online (runtime policy, 100 by default), other online members are notified that they left. Attributes they set with delete-on-leave (such as seats) are deleted.
Removing only makes them leave, and they can enter again immediately; to keep them out for a while, ban them instead, which removes them automatically. Admins can be removed; the owner can't. Users not in the room count as success with not_in_room.
/{org_name}/{app_name}/chatrooms/{room_id}/members/batch-deletePath parameters
For org_name and app_name, see the server overview.
| Parameter | Type | Description |
|---|---|---|
room_id | String | The chat room ID |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
usernames | Array<String> | Yes | Users to remove, 1 to 100 (case-insensitive; duplicates handled once) |
Request example
curl -X POST "$IM_API/$ORG/$APP/chatrooms/100310941534519296/members/batch-delete" \
-H "Authorization: Bearer $APP_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"usernames": ["sunqi", "wujiu", "zhangsan", "nobody"]
}'Response
On success you get 200 OK:
| Field | Type | Description |
|---|---|---|
changed | Boolean | Whether anyone was removed |
results | Array<Object> | Each user's result in request order, see Batch results. Successful result is removed or not_in_room |
{
"changed": true,
"results": [
{ "username": "sunqi", "result": "removed" },
{ "username": "wujiu", "result": "not_in_room" },
{
"username": "zhangsan",
"code": "permission_denied",
"message": "不能处置所有者",
"details": { "reason": "owner_protected" }
},
{ "username": "nobody", "code": "not_found", "message": "用户不存在" }
]
}Errors
| HTTP status | code | Description |
|---|---|---|
| 400 | invalid_argument | usernames is empty or has more than 100 entries |
| 404 | not_found | The room doesn't exist or was dissolved |
| 500 | internal | details.reason dependency_unavailable: temporarily unable to remove, and nobody was removed; wait for the Retry-After header and retry |
List mutes
List the room's active mutes page by page in a fixed order (unrelated to when they were set). Expired mutes aren't listed.
/{org_name}/{app_name}/chatrooms/{room_id}/mutesPath parameters
For org_name and app_name, see the server overview.
| Parameter | Type | Description |
|---|---|---|
room_id | String | The chat room 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
curl -X GET "$IM_API/$ORG/$APP/chatrooms/100310941534519296/mutes" \
-H "Authorization: Bearer $APP_TOKEN"Response
On success you get 200 OK, with each item in items a mute entry and the next page's cursor in next_cursor (null when there's no next page).
{
"items": [
{
"username": "zhaoliu",
"nickname": "赵六",
"avatar_url": "https://cdn.example.com/avatar/zhaoliu.png",
"muted_until": null,
"reason": "",
"created_by": null,
"created_by_role": "server",
"created_at": "2026-10-04T19:23:02.395Z"
},
{
"username": "wujiu",
"nickname": "吴九",
"avatar_url": "https://cdn.example.com/avatar/wujiu.png",
"muted_until": "2026-10-04T19:33:02.351Z",
"reason": "刷屏",
"created_by": null,
"created_by_role": "server",
"created_at": "2026-10-04T19:23:02.351Z"
}
],
"next_cursor": null
}Errors
| HTTP status | code | Description |
|---|---|---|
| 400 | invalid_argument | limit is out of range, or cursor is invalid |
| 404 | not_found | The room doesn't exist or was dissolved |
Mute users
Stop a batch of users posting in this room, up to 100 at a time, for a set time or permanently, ending automatically. For the effect see Mutes, bans and the allowlist. Online members are notified in real time with each person's end time.
Muting someone already muted recalculates the end time from the new duration (longer or shorter). Muting permanently when already permanent, or a new end time within 1 minute of the old one (such as a retry), counts as a repeat with result unchanged.
/{org_name}/{app_name}/chatrooms/{room_id}/mutesPath parameters
For org_name and app_name, see the server overview.
| Parameter | Type | Description |
|---|---|---|
room_id | String | The chat room ID |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
usernames | Array<String> | Yes | Users to mute, 1 to 100 (case-insensitive; duplicates handled once) |
duration_seconds | Number | No | Mute length in seconds, 1 to 315360000 (10 years). Omitted or null means permanent |
reason | String | No | Why they're muted, up to 256 characters without control characters. Shown in the mute list, including to the owner and admins viewing it in clients |
Request example
curl -X POST "$IM_API/$ORG/$APP/chatrooms/100310941534519296/mutes" \
-H "Authorization: Bearer $APP_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"usernames": ["wujiu", "sunqi", "zhangsan", "nobody"],
"duration_seconds": 600,
"reason": "刷屏"
}'Response
On success you get 200 OK with the same fields as Remove chat room members, where changed means whether anyone was muted or had their mute length changed. Successful result is muted or unchanged (a repeat with no change).
{
"changed": true,
"results": [
{ "username": "wujiu", "result": "muted" },
{ "username": "sunqi", "result": "muted" },
{
"username": "zhangsan",
"code": "permission_denied",
"message": "不能处置所有者",
"details": { "reason": "owner_protected" }
},
{ "username": "nobody", "code": "not_found", "message": "用户不存在" }
]
}Errors
| HTTP status | code | Description |
|---|---|---|
| 400 | invalid_argument | usernames is empty or has more than 100 entries; duration_seconds is out of range; reason is longer than 256 characters or has control characters |
| 404 | not_found | The room doesn't exist or was dissolved |
Unmute users
Lift a batch of users' mutes in this room early, up to 100 at a time. Online members are notified in real time. Users who aren't muted (or whose mute already ended) count as success with unchanged. Mute-all is turned off separately.
/{org_name}/{app_name}/chatrooms/{room_id}/mutes/batch-deletePath parameters
For org_name and app_name, see the server overview.
| Parameter | Type | Description |
|---|---|---|
room_id | String | The chat room ID |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
usernames | Array<String> | Yes | Users to unmute, 1 to 100 |
Request example
curl -X POST "$IM_API/$ORG/$APP/chatrooms/100310941534519296/mutes/batch-delete" \
-H "Authorization: Bearer $APP_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"usernames": ["sunqi", "zhouba", "nobody"]
}'Response
On success you get 200 OK with the same fields as Remove chat room members, where changed means whether anyone was unmuted. Successful result is unmuted or unchanged (wasn't muted).
{
"changed": true,
"results": [
{ "username": "sunqi", "result": "unmuted" },
{ "username": "zhouba", "result": "unchanged" },
{ "username": "nobody", "code": "not_found", "message": "用户不存在" }
]
}Errors
| HTTP status | code | Description |
|---|---|---|
| 400 | invalid_argument | usernames is empty or has more than 100 entries |
| 404 | not_found | The room doesn't exist or was dissolved |
List bans
List the room's active bans page by page in a fixed order (unrelated to when they were set). Expired bans aren't listed.
/{org_name}/{app_name}/chatrooms/{room_id}/bansPath parameters
For org_name and app_name, see the server overview.
| Parameter | Type | Description |
|---|---|---|
room_id | String | The chat room 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
curl -X GET "$IM_API/$ORG/$APP/chatrooms/100310941534519296/bans" \
-H "Authorization: Bearer $APP_TOKEN"Response
On success you get 200 OK, with each item in items a ban entry and the next page's cursor in next_cursor (null when there's no next page).
{
"items": [
{
"username": "zhouba",
"nickname": "周八",
"avatar_url": "https://cdn.example.com/avatar/zhouba.png",
"expires_at": "2026-10-04T20:23:28.148Z",
"reason": "发布广告",
"created_by": null,
"created_by_role": "server",
"created_at": "2026-10-04T19:23:28.148Z"
},
{
"username": "wujiu",
"nickname": "吴九",
"avatar_url": "https://cdn.example.com/avatar/wujiu.png",
"expires_at": "2026-10-04T20:23:28.148Z",
"reason": "发布广告",
"created_by": null,
"created_by_role": "server",
"created_at": "2026-10-04T19:23:28.148Z"
}
],
"next_cursor": null
}Errors
| HTTP status | code | Description |
|---|---|---|
| 400 | invalid_argument | limit is out of range, or cursor is invalid |
| 404 | not_found | The room doesn't exist or was dissolved |
Ban users
Add a batch of users to the room's ban list, up to 100 at a time, for a set time or permanently, ending automatically. After banning:
- All the user's connections in the room are removed immediately with a removal notice (reason
banned, with the end time), and they can't enter while banned; in rooms with at mostchatroom_member_notify_limitonline (runtime policy, 100 by default), other online members are notified that they left. - A banned admin also loses their admin role;
info_versionincreases by one and online members are notified of the admin change. - Attributes they set with delete-on-leave are deleted.
Banning someone already banned doesn't change the existing entry (duration and reason), with result unchanged; to change the duration, unban first and ban again.
/{org_name}/{app_name}/chatrooms/{room_id}/bansPath parameters
For org_name and app_name, see the server overview.
| Parameter | Type | Description |
|---|---|---|
room_id | String | The chat room ID |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
usernames | Array<String> | Yes | Users to ban, 1 to 100 (case-insensitive; duplicates handled once) |
duration_seconds | Number | No | Ban length in seconds, 1 to 315360000 (10 years). Omitted or null means permanent |
reason | String | No | Why they're banned, up to 256 characters without control characters. Shown in the ban list; the error banned users get when entering doesn't include it |
Request example
curl -X POST "$IM_API/$ORG/$APP/chatrooms/100310941534519296/bans" \
-H "Authorization: Bearer $APP_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"usernames": ["zhouba", "wujiu", "zhangsan"],
"duration_seconds": 3600,
"reason": "发布广告"
}'Response
On success you get 200 OK with the same fields as Remove chat room members, where changed means whether anyone was banned. Successful result is banned or unchanged (already banned).
{
"changed": true,
"results": [
{ "username": "zhouba", "result": "banned" },
{ "username": "wujiu", "result": "banned" },
{
"username": "zhangsan",
"code": "permission_denied",
"message": "不能处置所有者",
"details": { "reason": "owner_protected" }
}
]
}The error a banned user's client gets when entering during the ban:
{
"code": "permission_denied",
"message": "你已被该聊天室封禁",
"details": { "reason": "chatroom_banned", "expires_at": "2026-10-04T20:23:28.148Z" },
"request_id": "DTEVSNARBKXWTGBVZF3IA37RV3"
}Errors
| HTTP status | code | Description |
|---|---|---|
| 400 | invalid_argument | usernames is empty or has more than 100 entries; duration_seconds is out of range; reason is longer than 256 characters or has control characters |
| 404 | not_found | The room doesn't exist or was dissolved |
Unban users
Lift a batch of users' bans in this room early, up to 100 at a time, so they can enter again. Users aren't notified. Users who aren't banned (or whose ban already ended) count as success with unchanged.
/{org_name}/{app_name}/chatrooms/{room_id}/bans/batch-deletePath parameters
For org_name and app_name, see the server overview.
| Parameter | Type | Description |
|---|---|---|
room_id | String | The chat room ID |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
usernames | Array<String> | Yes | Users to unban, 1 to 100 |
Request example
curl -X POST "$IM_API/$ORG/$APP/chatrooms/100310941534519296/bans/batch-delete" \
-H "Authorization: Bearer $APP_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"usernames": ["wujiu", "sunqi"]
}'Response
On success you get 200 OK with the same fields as Remove chat room members, where changed means whether anyone was unbanned. Successful result is unbanned or unchanged (wasn't banned).
{
"changed": true,
"results": [
{ "username": "wujiu", "result": "unbanned" },
{ "username": "sunqi", "result": "unchanged" }
]
}Errors
| HTTP status | code | Description |
|---|---|---|
| 400 | invalid_argument | usernames is empty or has more than 100 entries |
| 404 | not_found | The room doesn't exist or was dissolved |
List the allowlist
List the room's allowlist page by page in a fixed order (unrelated to when people were added).
/{org_name}/{app_name}/chatrooms/{room_id}/allowlistPath parameters
For org_name and app_name, see the server overview.
| Parameter | Type | Description |
|---|---|---|
room_id | String | The chat room 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
curl -X GET "$IM_API/$ORG/$APP/chatrooms/100310941534519296/allowlist" \
-H "Authorization: Bearer $APP_TOKEN"Response
On success you get 200 OK, with each item in items an allowlist entry and the next page's cursor in next_cursor (null when there's no next page).
{
"items": [
{
"username": "lisi",
"nickname": "李四",
"avatar_url": "https://cdn.example.com/avatar/lisi.png",
"created_by": null,
"created_at": "2026-10-04T19:22:36.168Z"
},
{
"username": "wujiu",
"nickname": "吴九",
"avatar_url": "https://cdn.example.com/avatar/wujiu.png",
"created_by": null,
"created_at": "2026-10-04T19:22:36.168Z"
},
{
"username": "zhengshi",
"nickname": "郑十",
"avatar_url": "https://cdn.example.com/avatar/zhengshi.png",
"created_by": null,
"created_at": "2026-10-04T19:22:36.168Z"
}
],
"next_cursor": null
}Errors
| HTTP status | code | Description |
|---|---|---|
| 400 | invalid_argument | limit is out of range, or cursor is invalid |
| 404 | not_found | The room doesn't exist or was dissolved |
Add to the allowlist
Add a batch of users to the room's allowlist, up to 100 at a time and 500 per room. For the effect see Mutes, bans and the allowlist. Online members are notified in real time. Users already on it count as success with unchanged. Not allowed while the app is read-only.
/{org_name}/{app_name}/chatrooms/{room_id}/allowlistPath parameters
For org_name and app_name, see the server overview.
| Parameter | Type | Description |
|---|---|---|
room_id | String | The chat room ID |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
usernames | Array<String> | Yes | Users to add, 1 to 100 (case-insensitive; duplicates handled once) |
Request example
curl -X POST "$IM_API/$ORG/$APP/chatrooms/100310941534519296/allowlist" \
-H "Authorization: Bearer $APP_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"usernames": ["wujiu", "zhengshi", "lisi", "nobody"]
}'Response
On success you get 200 OK with the same fields as Remove chat room members, where changed means whether anyone was added. Successful result is added or unchanged (already on it).
{
"changed": true,
"results": [
{ "username": "wujiu", "result": "added" },
{ "username": "zhengshi", "result": "added" },
{ "username": "lisi", "result": "added" },
{ "username": "nobody", "code": "not_found", "message": "用户不存在" }
]
}Errors
| HTTP status | code | Description |
|---|---|---|
| 400 | invalid_argument | usernames is empty or has more than 100 entries |
| 403 | app_unavailable | The app is read-only and the allowlist can't be added to |
| 404 | not_found | The room doesn't exist or was dissolved |
Remove from the allowlist
Remove a batch of users from the room's allowlist, up to 100 at a time. Online members are notified in real time. Users not on it count as success with unchanged.
/{org_name}/{app_name}/chatrooms/{room_id}/allowlist/batch-deletePath parameters
For org_name and app_name, see the server overview.
| Parameter | Type | Description |
|---|---|---|
room_id | String | The chat room ID |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
usernames | Array<String> | Yes | Users to remove from the allowlist, 1 to 100 |
Request example
curl -X POST "$IM_API/$ORG/$APP/chatrooms/100310941534519296/allowlist/batch-delete" \
-H "Authorization: Bearer $APP_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"usernames": ["zhengshi", "zhouba"]
}'Response
On success you get 200 OK with the same fields as Remove chat room members, where changed means whether anyone was removed from it. Successful result is removed or unchanged (wasn't on it).
{
"changed": true,
"results": [
{ "username": "zhengshi", "result": "removed" },
{ "username": "zhouba", "result": "unchanged" }
]
}Errors
| HTTP status | code | Description |
|---|---|---|
| 400 | invalid_argument | usernames is empty or has more than 100 entries |
| 404 | not_found | The room doesn't exist or was dissolved |
Data structures
Member object
| Field | Type | Description |
|---|---|---|
username | String | The 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 |
role | String | Room role: owner, admin or member |
joined_at | String | When they entered this time |
{
"username": "lisi",
"nickname": "李四",
"avatar_url": "https://cdn.example.com/avatar/lisi.png",
"role": "admin",
"joined_at": "2026-10-04T19:20:33.019Z"
}Mute entry
| Field | Type | Description |
|---|---|---|
username | String | The muted 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 |
muted_until | String | When the mute ends; null for permanent mutes |
reason | String | Why they're muted; empty string if none |
created_by | String | The owner or admin who set it from a client; null when set by your server or the console |
created_by_role | String | Who set it: owner, admin or server (server or console). In clients, admins can only lift mutes set by admin |
created_at | String | When this mute entry was created; unchanged when the duration is changed |
Ban entry
The same fields as a mute entry, with expires_at in place of muted_until:
| Field | Type | Description |
|---|---|---|
username | String | The banned 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 |
expires_at | String | When the ban ends; null for permanent bans |
reason | String | Why they're banned; empty string if none |
created_by | String | The owner or admin who set it from a client; null when set by your server or the console |
created_by_role | String | Who set it: owner, admin or server |
created_at | String | When they were banned |
Allowlist entry
| Field | Type | Description |
|---|---|---|
username | String | The 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 |
created_by | String | The owner or admin who added them from a client; null when added by your server or the console |
created_at | String | When they were added |
Batch results
In results from removing, muting, unmuting, banning, unbanning, and adding to and removing from the allowlist, each item is one user's result. Successful items have only username and result; failed items have no result but code and message, and some also details.
| Field | Type | Description |
|---|---|---|
username | String | The username (lowercase) |
result | String | On success, see each API: removed, not_in_room, muted, unmuted, banned, unbanned, added, unchanged |
code | String | On failure: the error code, see below |
message | String | On failure: the error text |
details | Object | Details of the failure; only some errors have it |
code | details.reason | Description |
|---|---|---|
not_found | The user doesn't exist | |
permission_denied | owner_protected | The user is the owner and can't be muted, removed or banned |
limit_exceeded | mute_limit | The mute list is full (10,000 active mutes) |
limit_exceeded | ban_limit | The ban list is full (10,000 active bans) |
limit_exceeded | allowlist_limit | The allowlist is full (500 users) |
