---
title: "Send a message to many creators at once"
method: POST
path: "/chat/broadcasts"
tags: ["Chat"]
---

# Send a message to many creators at once

`POST /chat/broadcasts`

## Request

- Base URL: `https://viral.app/api/v1`
- URL: `https://viral.app/api/v1/chat/broadcasts`
- Auth: API key in header `x-api-key`

Queues one message for the audience and answers 202 with the broadcast's id and reach; the messages then go out in the background. The `creators`, `campaigns` and `all` audiences send it as a separate direct message to each creator (at most 500), into the existing conversation or a new one; `groups` posts it once in each selected group chat (at most 50). Only creators who can receive messages are reached: they joined your organization or hold a pending invitation, and selecting a creator who does not is refused. `broadcastId` is your idempotency key: repeating a request with the same id and payload answers 202 again and only sends what is still missing, while the same id with a different message or audience is refused (400). Each member can start 10 broadcasts per hour (429). Broadcasts carry text only. Every message fires a `chat.message.sent` webhook event carrying the `broadcastId`, which is how to follow delivery.

## Request body

- object
  - `audience` 'creators' | 'campaigns' | 'all' | 'groups', required
  - `orgCreatorIds` string[]
  - `campaignIds` string[]
  - `groupChatIds` string[]
  - `content` string, required
  - `broadcastId` string, required: Your idempotency key for this broadcast (8-24 characters: letters, digits, _ and -). Repeating a request with the same id and payload answers 202 again and only sends what is missing; the same id with a different message or audience is refused.
  - `senderIdentity` 'member' | 'org': API-key calls only: how creators see the sender. "org" (the default) sends as the brand alone; "member" puts the key owner's first name in front of the brand ("Dennis from Acme"). Ignored for every other caller, whose broadcasts follow their own chat settings.
  - `attachmentIds` string[]: Not supported: broadcasts carry text only. Any attachment id is refused (400); send files in each conversation instead.

## Response `202`

Accepted: the broadcast is queued

- object
  - `broadcastId` string, required
  - `status` 'queued', required
  - `recipientCount` integer, required
  - `groupCount` integer, required

## Other responses

- `400`: 400
- `401`: 401
- `402`: 402
- `404`: 404
- `408`: 408
- `429`: 429
- `500`: 500

---

[API](https://skmtc.dev/viral/apis/viral-app-api.md) · [All operations](https://skmtc.dev/viral/apis/viral-app-api/llms.txt) · [OpenAPI document](https://skmtc.dev/viral/apis/viral-app-api/revisions/31e97fa79ef1?raw)