Skip to main content
A poll asks fans to pick one of its options. Once it has gone live, its options are fixed: your producers can correct a label, but can’t add or remove an option.

Voting

When the fan picks an option, send its ID with the fan’s token and a new Idempotency-Key:
The answer is 202 Accepted: received, not yet counted. It has a snapshot of the poll’s results with the vote added. See Cast a vote.
  • Show the snapshot straight away, as a static view. It doesn’t update, and it follows the poll’s results_visibility.
  • Only the fan’s first vote counts. A later vote, from any device, also answers 202, but is never counted.
  • To show the fan’s choice, get the fan’s vote whenever you show the poll. Straight after a 202 it can still be null, until the vote is counted: keep showing the fan’s pick until it appears.

Results

The poll’s results_visibility says when fans may see its results. Your producers choose it for each poll in Dizplai’s tools, and can change it later. If they don’t choose, it’s after_vote. With after_vote, the numbers are in every response, so anyone who reads it can see them. If results mustn’t be seen early, your producers choose after_close or hidden. The poll’s results.state says what to show now:
  • withheld: no counts yet. Show nothing, or a note such as “Results when voting closes” for after_close.
  • live: the current votes and percentages, which change as fans vote.
  • final: voting has stopped, and these are the confirmed totals. They can differ from the last live numbers.
  • A state you don’t know: treat it as withheld, and show no counts.
Match each result to its option by option_id. Percentages are rounded, so they may not add up to exactly 100.

Keeping results current

  • Read an open poll every 10 seconds. After a vote, show its snapshot and wait for your next read: a read straight after the vote may not include it yet.
  • After the poll closes, keep reading until results.state is final, then stop. A hidden poll never shows results, so stop when it closes.
  • If your producers open it again, it shows as live in lists, and its results go back to live, or withheld for after_close. Start reading it again.
Results reach your app and Dizplai’s on-air graphics separately, so they don’t change at the same moment.