Skip to main content
GET
Get a Fan Voice

Authorizations

x-api-key
string
header
required

Your organisation's API key, supplied by Dizplai. Send it on every request. It isn't a secret, so it can ship in your app: what a fan does is protected by the fan's token.

Path Parameters

fan_voice_id
string<uuid>
required

The Fan Voice's ID, from a list of experiences or Fan Voices. A Fan Voice's ID, a UUID.

Example:

"0192fa7b-a1a5-7ae6-8820-782ce84e0f49"

Response

The Fan Voice.

A Fan Voice: a prompt fans reply to in their own words, with text, a voice note or a photo. Show the prompt and a message box, offer the kinds in kinds, and keep within limits. It has no results: fans see only their own messages.

id
string<uuid>
required

A Fan Voice's ID, a UUID.

Example:

"0192fa7b-a1a5-7ae6-8820-782ce84e0f49"

type
enum<string>
required

Tells Fan Voices apart from other experiences in a list.

Available options:
fan_voice
status
string
required

Whether fans can take part now. scheduled: coming up, and goes live at starts_at. live: taking votes or messages. closed: taking part has stopped; it can reopen. An experience your producers take down or delete drops out of lists, and getting it answers 404. More statuses may be added: treat one you don't know as closed to taking part.

starts_at
string<date-time> | null
required

When it's due to open. Null if your producers open it by hand.

ends_at
string<date-time> | null
required

When it's due to close. Null if no closing time is set.

metadata
object
required

Tags for finding and grouping things, such as the match or show they're about. Filter lists by them with metadata[key]=value. Up to 50 keys of up to 40 characters, values up to 500. One key is reserved, event_id, set by your producers; every other key is yours, and never interpreted.

locale
string
required

The language the experience's text is written in, such as en-GB.

Maximum string length: 35
Pattern: ^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$
Example:

"en-GB"

created_at
string<date-time>
required

When the Fan Voice was created.

updated_at
string<date-time>
required

Changes when anything a fan can see changes.

requires_sign_in
boolean
required

True if only signed-in fans may take part: show a guest your sign-in prompt instead. A guest's vote or message here answers 403 (sign_in_required). Voice notes and photos are always for signed-in fans.

prompt
string
required

What fans are asked to reply to.

Required string length: 1 - 500
kinds
string[]
required

What fans may send: text, voice (voice notes) or image (photos). More kinds may be added: offer only the ones your app knows. Voice notes and photos are for signed-in fans only, with fixed limits: a voice note is audio/mp4 or audio/webm, up to 5 MB and 60 seconds; a photo is image/jpeg, image/png, image/heic or image/webp, up to 10 MB.

limits
object
required

max_text_length, 1 to 500, and per_fan, how many messages of each kind one fan may send, 1 to 100.

placeholder
string

Hint text for the message box, such as Your message.

Maximum string length: 500
confirmation_message
string

What to show the fan once their message is sent.

Maximum string length: 500