Developer guide

Chat bans: stopping one user from writing in a room

Your backend lists who may not write in an open room; the engine and the kits enforce it.

Back to Developers

Applies to: engine API v1, utd_audio_room_kit 3.11.0 or later, utd_live_room_kit 3.9.0 or later, both with utd_media_client 2.9.9 or later

PUT /api/v1/rooms/:room_name/chat-bans lets your backend say, for one open room, which identities may not write. A banned member still hears, sees, holds their seat and their microphone. It is additive: a room that never uses it behaves as before.

Who can call it

CallerResult
Your backend with X-App-Id + X-App-SecretAllowed
An end user with a bearer user_token, including the room's host and admins403 chat-bans is a server-to-server call; nothing is written
The publishable App KeyNot accepted
A project in secure mode401: the route needs the Server Secret

This is deliberate: who may not write is a moderation decision of your platform, not of a room host. The room must be open: for a closed room the answer is 404 room_closed, which is normal.

Request

PUT /api/v1/rooms/lobby/chat-bans
{
  "banned": {
    "user_123": null,
    "user_456": "2026-10-05T18:30:00Z"
  }
}
  • banned maps an identity (the one you pass as user_id to the token route) to null (banned until you remove it) or an ISO-8601 time (banned until then).
  • The call replaces the whole list. Send everybody who is banned in this room, every time; send { "banned": {} } to clear it.
  • Limits: 200 entries, 64 characters per identity, 5000 bytes serialized. A request over a limit is refused whole with 422, so trim before sending.
  • Response: 200 { "message": "Chat bans updated", "count": 2 }.

What is enforced, and where

There are two layers. The list you write with PUT /chat-bans is stored for every project, and the kits drop chat from a listed sender at the receiver, host and admin included. That layer needs kits at the versions above; an older kit, or a modified client, does not apply it.

The second layer is enforcement at the media server, and it is switched on per project, not for everybody. On a project where it is on, the engine removes the banned member's permission to publish data, and gives every new token for them the same restriction, so rejoining does not lift the ban. It is available on request, per project; until it is on for yours, the receiver-side filter is the only layer.

On projects where media-server enforcement is on, a media server cannot tell chat from other data. Removing the permission stops ALL data from the banned member's device: chat, the cosmetic updates the kit sends, and anything your app sends with sendRoomMessage or sendTargetedMessage. If your app sends gifts or reactions as room messages, a chat ban silences those as well. That is a change from earlier releases, where the ban was applied only at the receiver. The comment lock (one switch for the whole room) is still applied at the receiver.

In 3.14.1 the kit does not read the permission before it sends, so a banned user sees their own message on their own screen while nobody receives it. Hide the composer from UTDRoomController.chatBanned, a ValueNotifier<bool> that is true while the local user is listed.

Keep the list fresh

Write the list when a ban is applied or lifted, and again when a banned user joins a room (the participant_joined webhook is the place), so someone banned while elsewhere is on this room's list too.

backend (Node)
const banned = {};
for (const b of await db.activeWritingBans(roomName)) {
  banned[b.identity] = b.endsAt ? new Date(b.endsAt).toISOString() : null;
}

const res = await fetch(`https://udt-stream.com/api/v1/rooms/${encodeURIComponent(roomName)}/chat-bans`, {
  method: "PUT",
  headers: {
    "Content-Type": "application/json",
    "X-App-Id": process.env.UTD_APP_ID,
    "X-App-Secret": process.env.UTD_SERVER_SECRET,
  },
  body: JSON.stringify({ banned }),
});
if (!res.ok) throw new Error(`chat-bans refused: ${res.status} ${await res.text()}`);

Ready to build with UTD?

Create your account, fund your master wallet, and turn on the services you need.