Chat

Send a message to many creators at once

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.

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

Request body

audience'creators' | 'campaigns' | 'all' | 'groups' required
orgCreatorIdsstring[]
campaignIdsstring[]
groupChatIdsstring[]
contentstring required
broadcastIdstring 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.

attachmentIdsstring[]

Not supported: broadcasts carry text only. Any attachment id is refused (400); send files in each conversation instead.

Response

Accepted: the broadcast is queued

broadcastIdstring required
status'queued' required
recipientCountinteger required
groupCountinteger required

Changes

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