Fan Voices

A Fan Voice asks fans for a message. Show its prompt and a way to reply, in the kinds of message it takes. Fans never see each other’s messages, and your team moderates every one.

Limits

Message	Kind	Limit
Text	`text`	The Fan Voice’s `max_text_length`, at most 500 characters
Voice note	`voice`	60 seconds and 5 MB. Signed-in fans only
Photo	`image`	10 MB. Signed-in fans only

Video isn’t supported. The Fan Voice’s limits say how many of each kind one fan can send, keyed by kind in per_fan: ignore a kind you don’t know. Every message counts, approved or not, and the allowance never resets, even if the Fan Voice opens again. To show what’s left, count the fan’s own messages of that kind.

Sending text

POST /v1/fan-voices/0192fa7b-8dff-71e2-a8b3-f199293b905d/messages
x-api-key: <your API key>
Authorization: Bearer <the fan's token>
Idempotency-Key: <a new UUID for this message>
Content-Type: application/json

{ "kind": "text", "text": "Brilliant second half. Keep pressing!", "on_air_consent": true }

Sending a voice note or photo

Create an upload with the fan’s token and a new Idempotency-Key, giving the file’s kind, content_type and bytes. The answer has an upload_id, and a url that works for 5 minutes.
Send the file to that url with a PUT. Send only Content-Type and Content-Length, the same as you asked for, with no API key or fan token: the link is already signed.
Send the message within an hour, with "kind": "voice" or "image", the upload_id, and a new Idempotency-Key of its own.

An upload that’s never used is deleted after an hour, and only a message the fan sends counts towards their allowance.

After sending

Show the Fan Voice’s confirmation message. Sending isn’t approval. A message can be used on air only if its on_air_consent is true: show the fan a separate box for it, unticked to start with. List the fan’s messages to show what happened to each one:

Status	Show
`sent`	Waiting for your team
`approved`	Approved. A voice note or photo can now be played or shown
`not_approved`	Not approved, with the reason given
`removed`	Approved, then taken down, with the reason given

Read them when the Fan Voice opens on screen, and every 30 seconds while any are waiting for your team. Fans can’t ask for a decision to be reviewed.

Introduction

Experiences

Limits

Sending text

Sending a voice note or photo

After sending