---
title: "Async broadcast announcement to selected chat rooms"
method: POST
path: "/v2/chats/broadcast"
tags: ["Chats"]
---

# Async broadcast announcement to selected chat rooms

`POST /v2/chats/broadcast`

## Request

- Base URL: `https://api.chat.ethora.com`
- URL: `https://api.chat.ethora.com/v2/chats/broadcast`
- Auth: HTTP bearer

**Auth**: User JWT

Enqueues a background job to send a system message stanza to each target room (avoids timeouts).
Provide chatNames (internal Ethora chat names) or chatIds (uuid-only, will be prefixed with appId),
or set allRooms=true to broadcast to every chat in the app.

Auth model (privileged — app-wide broadcast):
- Requires a `B2B Server JWT` (`x-custom-token`) for the app, OR a user
  JWT whose ACL on the app grants `application.appSettings.update` (admin).
- A plain `App JWT` (shipped in client config) is NOT accepted — it is
  rejected so end users cannot broadcast app-wide.
- A non-admin user JWT is rejected with 403.
- Prefer the explicit `/v2/apps/{appId}/chats/broadcast` for backend or
  tenant-admin integrations.

## Request body

- object
  - `text` string, required: Message body to broadcast. Plain text; chat-component renders it as a system or regular message depending on `isSystemMessage`.
  - `allRooms` boolean: If true, broadcast to every chat in this app. Capped by `CHATS_BROADCAST_MAX_ROOMS` (default 5000). Mutually exclusive with `chatNames` / `chatIds`.
  - `chatNames` string[]: Array of internal chat names (`<appId>_<chatId>`) to target. Use this for the most reliable matching. Max 100 per call.
  - `chatIds` string[]: Array of `chatId` values (the part after `<appId>_`). Convenience shorthand; converted to `chatNames` server-side. Max 100 per call.
  - `metadata` object: Free-form JSON attached to each emitted message. Useful for partner integrations that need a correlation ID.
  - `dryRun` boolean: If true, validate + resolve the room list and return the same `jobId`/`statusUrl` shape as a real call, but do not send any messages. Use to preview the target set before committing.
  - `sender` object: Optional per-broadcast sender override stamped on the outgoing `<data>` element (`fullName / senderFirstName / senderLastName / photo`). Falls back to `app.broadcastSender` and then `app.displayName` when omitted. Without any of these, chat-component renders broadcasts as "Deleted User". Provide either `name` (split on first whitespace) or explicit `firstName` + `lastName`.
    - `name` string
    - `firstName` string
    - `lastName` string
    - `photoUrl` string, uri
  - `isSystemMessage` boolean: When true, chat-component renders the broadcast via its SystemMessage component (banner). Defaults to false so broadcasts look like regular messages from the configured sender.

## Response `202`

```
{ ok: true, jobId: string, statusUrl: string }
```

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `422`: Unprocessable Entity
- `500`: Internal Server Error

---

[API](https://skmtc.dev/ethora/apis/platform-api.md) · [All operations](https://skmtc.dev/ethora/apis/platform-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ethora/apis/platform-api/revisions/01b6e64378ee?raw)