Chats

Async broadcast announcement to selected chat rooms

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.
post/v2/chats/broadcast

Request

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

Request body

textstring required

Message body to broadcast. Plain text; chat-component renders it as a system or regular message depending on isSystemMessage.

allRoomsboolean

If true, broadcast to every chat in this app. Capped by CHATS_BROADCAST_MAX_ROOMS (default 5000). Mutually exclusive with chatNames / chatIds.

chatNamesstring[]

Array of internal chat names (<appId>_<chatId>) to target. Use this for the most reliable matching. Max 100 per call.

chatIdsstring[]

Array of chatId values (the part after <appId>_). Convenience shorthand; converted to chatNames server-side. Max 100 per call.

metadataobject

Free-form JSON attached to each emitted message. Useful for partner integrations that need a correlation ID.

dryRunboolean

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.

isSystemMessageboolean

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.

Example request

{
  "sender": {
    "name": "Acme Health",
    "photoUrl": "https://cdn.example.com/logo.png"
  }
}

Response 

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

Changes

No recorded changes to this operation across all 1 revision of this API.