Chat via the API

The chat API covers the same conversations as the Chat page: direct threads with each creator, group chats, and broadcasts to many creators at once. Use it to connect a helpdesk or CRM, or to let an AI agent answer creators. Pair it with webhooks so your systems hear about new messages the moment they arrive, instead of polling.

The API reference lists every route under Chat, with all fields. API and automation covers keys and access.

Before you start

• Base URL and auth. Every route lives under https://viral.app/api/v1 and takes the x-api-key header.
• Scope. A key reads and writes its own organization's conversations only.
• Roles. Sending, reacting, marking as read and managing groups need a key of an owner, admin or member. Reading also works with a viewer's key.
• Who the key acts as. The key acts as the teammate who owns it. Reactions show as theirs, and "mark as read" moves their read pointer.
• Ids carry their type: crchat_ conversations, crmsg_ messages, cratt_ attachments, orgcre_ creators.

Who creators see

A message sent with an API key is signed as your brand (your organization's name and logo) by default. Send senderIdentity: "member" to sign it with the key owner's first name in front of the brand instead, as in "Dennis from Acme".

Creators see no sign that a message came through the API. Your team does: in the dashboard, those messages carry a small via API badge. Every message records where it came from in source (ui, api, copilot or system), and messages sent with a key also carry that key's id.

Read conversations

GET /chat/threads lists the conversations with the latest message and the unread count. It has three modes:

GET /chat/threads/{chatId} returns one conversation in the same shape. GET /chat/unread-count counts the conversations with unread messages.

A row with kind: "group" is a group chat. title is its internal name, publicTitle the name creators see, and memberCount its size. The creator fields are empty for groups.

Read messages

GET /chat/threads/{chatId}/messages returns a page of messages, oldest to newest within the page, plus both sides' read state. Pass nextPageToken back for the next, older page. GET /chat/threads/{chatId}/search?query=… finds messages by text, and GET /chat/threads/{chatId}/pins lists the pinned ones.

A deleted message stays in the list with empty content, so ids never disappear from under you.

Keep a copy in sync

To mirror conversations into your own system:

1. Load once. Page through GET /chat/threads with limit, and through each conversation's messages with pageToken.
2. Then sync changes.
   • GET /chat/threads?updatedSince=<the newest updatedAt you have> returns the conversations that changed.
   • For each of them, GET /chat/threads/{chatId}/messages?after=<the newest createdAt you have> returns what is new, oldest first.
3. Dedupe on ids.
   • Messages commit slightly out of order (a broadcast writes many at once), so both calls deliberately look back 2 minutes before the time you pass.
   • A conversation that changes during your sync can come back on a later page.
4. Follow edits and reactions through webhooks. A message's createdAt never changes, so after does not return edits. Webhooks do: chat.message.updated, chat.message.deleted, chat.reaction.added and chat.reaction.removed.

Start a conversation

POST /chat/threads with a creator's orgCreatorId (or creatorUserId) returns the conversation's chatId. It is created if it doesn't exist yet. For an applicant who is not on your roster, open the chat from the application with POST /applications/{id}/chat.

Invite first. A creator on your roster who has never been invited to viral.app has no account to read messages with. Starting a conversation with them, or sending them a message, returns 409 with the code CREATOR_NOT_INVITED and their orgCreatorId. Invite them with POST /creators/{id}/invite, then write. Applicants and archived creators can always be messaged.

Send a message

curl -X POST "https://viral.app/api/v1/chat/threads/crchat_A1b2C3d4E5f6/messages" \
  -H "x-api-key: $VIRAL_APP_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "content": "Thanks! Your payout goes out on Monday.",
    "clientMessageId": "helpdesk-8f14e45f"
  }'

• clientMessageId is required and makes retries safe. Generate a fresh random value (8 to 64 characters) per message. Sending the same one again returns the original message instead of sending twice.
• replyToMessageId quotes a message of the same conversation.
• Limits. Messages hold up to 8,000 characters. The key's owner can send 20 messages per minute into one conversation, the same limit the dashboard has.
• In a group, @[channel](channel) notifies every member. Creators are otherwise only notified when they are mentioned.

Edit and delete. PATCH and DELETE /chat/threads/{chatId}/messages/{messageId} work on messages this key sent. Messages the key's owner typed in the dashboard, and other keys' messages, are refused.

Reactions. POST and DELETE /chat/threads/{chatId}/messages/{messageId}/reactions with { "emoji": "🔥" }. A reaction is exactly one emoji; skin tones and combined emoji count as one.

Pins. POST and DELETE /chat/threads/{chatId}/messages/{messageId}/pin pin a message for everyone in the conversation.

Send files

Files take three steps:

1. Reserve a slot. POST /chat/threads/{chatId}/attachments/presign with the file's fileName, mimeType and sizeBytes returns an attachmentId and a signedUrl.
2. Upload. PUT the file's bytes to signedUrl with the same Content-Type, within 5 minutes.
3. Send. Pass the attachmentId in attachmentIds of the message, up to 10 per message. The text may be empty when the message carries files.

Images (JPEG, PNG, WebP, GIF) and PDFs take up to 25 MB, and videos (MP4, MOV, WebM) up to 512 MB. Each conversation accepts up to 30 unsent uploads an hour.

A sent file is served from a permanent public URL, and deleting the message does not revoke it. Don't send anything that must stay private.

Read state

POST /chat/threads/{chatId}/read marks the conversation as read up to a message, or up to the newest one. It moves the key owner's read pointer, as if they had opened the conversation, and creators see "Seen" as usual. Sending a message also marks the conversation as read for the sender.

Group chats

Campaign groups and "all creators" groups follow your roster, so their members can't be changed by hand (400, MANUAL_ONLY). A creator you add before they were ever invited to viral.app shows up in pendingOrgCreatorIds; they can read the group once invited.

Broadcasts

A broadcast sends one message to many creators as individual direct messages, one per creator, into each creator's own conversation. Recipients never see each other. The audience picks who:

• creators: the creators you list in orgCreatorIds (up to 100);
• campaigns: every creator actively assigned to the campaigns in campaignIds;
• all: every active creator;
• groups: posts the message once into each group chat in groupChatIds (up to 50) instead.

Then:

1. Check the reach. GET /chat/broadcasts/preview with the same audience counts the creators it reaches right now.
2. Send. POST /chat/broadcasts with the audience, content and a broadcastId of your own (8 to 24 letters, digits, _ or -). It answers 202 Accepted with { broadcastId, status: "queued", recipientCount, groupCount }.
3. Delivery. The messages go out over the next moments. Each one arrives as its own chat.message.sent webhook event carrying the broadcastId.

Some rules:

• Retries are safe. Sending the same broadcastId with the same message and audience again answers 202 and only sends what is still missing. The same id with a different message or audience is refused with 400.
• Text only. Broadcasts can't carry attachments.
• Signature. Like single messages, they are signed as your brand, or with senderIdentity: "member" as the key owner.
• Limits. A broadcast reaches up to 500 creators, and each teammate can start 10 broadcasts an hour (429 beyond that).

During a payout hold

While creator payouts are long overdue (a hard payout hold), the API refuses most writes with 402. Conversations keep working:

• Still works: sending and replying (POST /applications/{id}/reply included), editing and deleting your messages, reactions, pins, files and marking as read.
• Waits until the hold is lifted: starting new conversations, broadcasts, and creating or changing groups.

Webhooks for chat

Subscribe an endpoint to the chat events in the Webhooks tab so you don't have to poll:

• chat.message.received: a creator wrote. This is the event an AI agent answers.
• chat.message.sent: your side wrote, from the dashboard, the API, the Copilot or a broadcast. source says which.
• Also sent: edits, deletions, reactions, status messages, and group and thread changes.

If your integration answers through the API and also listens to chat.message.sent, skip the events that carry your own key's apiKeyId. Otherwise it keeps answering itself.