> ## Documentation Index
> Fetch the complete documentation index at: https://developer.dizplai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Drawing widgets

> The fields each widget type needs, what to show in each state, and when results are visible.

Every widget arrives in an experience's `items`, in display order, and `type` says which drawing to use. Ignore a type you don't know: new types are added within v1. Widgets carry no images yet; they arrive in a later version.

## Every widget

| Field | Use |
| - | - |
| `type` | Which drawing to use |
| `status` | What to show. See [States](#states) |
| `question`, `subtitle` | The heading and the line under it, where the type has them |
| `requires_sign_in` | When `true`, show a fan who isn't signed in your sign-in prompt instead of the widget |
| `results_visibility` | When fans may see results. See [Results](#results) |
| `total_votes` | Fans who voted. Null until the first result |
| `final` | `true` once votes have stopped and been recounted: the official result |
| `starts_at`, `ends_at` | When it opens and closes, if timed. Null when the producer cues it |

## By type

### Poll

`question` and one choice per entry in `options`, each with a `label`. The fan picks one, and your app sends its `id` to `POST /polls/{poll_id}/votes` as `option_id`. Results: each option's `votes` and `percent`.

### Picker

A run of head-to-head rounds between the people in `options` (`label`, plus `first_name` and `last_name` where given), each round lasting `timer_seconds`, which your app enforces. The fan's last pick is their vote. Results: each option's `votes` and `percent`.

### Rating

`question`, then every player in `options` with a score from 1 to `max_rating`. A fan needn't rate every player. Results, per player: `average_vote`, `rating_count`, and `distribution`, the fans who gave each score.

### Predictor

`subtitle`, the two teams (`team1.name`, `team2.name`) and a score for each, from 0 to `max_score`. Votes stop at `locks_at`, usually kick-off, when it turns `locked`. Results: `predictions`, every predicted score line with its `votes`, most popular first. Once it's `settled`, each team carries its final `score`.

### Line-up

`question`, the `formations` a fan may use (one means it's fixed), and the players in `teams[].players`, each with a `label` and `position_group`, and a `shirt_number` where given. The fan picks a formation and a player for each position. Results: `positions`, the top three players for each, with `votes` and `percent`, and `formation_votes` when fans choose the formation.

### Fan Zone

`type` is `messaging`. Show `prompt`, an input with `placeholder`, and the kinds of message in `kinds`: `text`, and `voice` notes and `image` photos for signed-in fans only, within `limits`. After a message is sent, show `confirmation_message`. Fans never see each other's messages, and there are no results: your team reviews messages, and only approved ones reach air, with the fan's consent.

### Sponsor

Show each of `slides` in turn, for `display_duration_ms` each. A slide's `url` is where it links to. No votes, no results.

## States

| `status` | Show |
| - | - |
| `scheduled` | Nothing yet, or a "coming up" teaser with `starts_at` if it has one |
| `live` | The widget, taking votes or messages |
| `locked` | Predictors: votes have stopped at kick-off. Waiting for the final score |
| `closed` | Votes have stopped. Results if fans may see them, marked final once `final` |
| `settled` | Predictors: the final score, beside the fans' predictions |
| `hidden` | Nothing. It can come back |
| `deleted` | Nothing |

Lists return live widgets unless you ask for other statuses, such as `?status=live,scheduled`.

## Results

| `results_visibility` | Fans see results |
| - | - |
| `live` | While it's live, updating every second |
| `after_vote` | Once they've voted. Your app's reads include results from when votes have stopped |
| `after_close` | Once votes have stopped |
| `hidden` | Never |

Your servers' reads always include results. To keep them current, see [Live updates](https://developer.dizplai.com/live-updates.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.