Polls and Predictions

On this page
Edit

Create Prediction 2 Outcomes #

Creates a new prediction for your channel with 2 outcomes. Must be at least affiliate.
If you want to create a prediction with more than 2 outcomes, you can use Create Prediction command instead.

Box Name Type Description
Login Name Dropdown Your Twitch login name (all lowercase characters)
Prediction Name String Question displayed for the prediction. Maximum: 60 characters.
Choice 1 String Text displayed for the choice. Maximum: 25 characters.
Choice 2 String Text displayed for the choice. Maximum: 25 characters.
Dur.(s) Number Total duration for the prediction in seconds.

Twitch API Endpoint: POST /helix/predictions

Request Field Type Description
broadcaster_id string The ID of the broadcaster creating the prediction.
title string The question displayed for the prediction. Maximum: 60 characters.
outcomes array Array of outcome objects. Each must contain a title field (max 25 characters). Exactly 2 outcomes.
prediction_window integer The length of time (in seconds) that the prediction will run for. Minimum: 30, Maximum: 1800.

Edit

Create Prediction #

Creates a new prediction for your channel with 2-10 outcomes. Must be at least affiliate.

Box Name Type Description
Login Name Dropdown Your Twitch login name (all lowercase characters)
Prediction Name String Question displayed for the prediction. Maximum: 60 characters.
Choice Array Name String Name of the array containing all your outcome names (min 2, max 10)
Dur.(s) Number Total duration for the prediction in seconds.

Twitch API Endpoint: POST /helix/predictions

Request Field Type Description
broadcaster_id string The ID of the broadcaster creating the prediction.
title string The question displayed for the prediction. Maximum: 60 characters.
outcomes array Array of outcome objects built from the provided array. Each must contain a title field (max 25 characters). Minimum 2, maximum 10 outcomes.
prediction_window integer The length of time (in seconds) that the prediction will run for. Minimum: 30, Maximum: 1800.

Edit

End Prediction #

Ends a currently running prediction.

Box Name Type Description
Login Name Dropdown Your Twitch login name (all lowercase characters).
Status Dropdown Status of the ending prediction.
Prediction ID String Prediction ID, wrapped in /$$/ if a variable is being used.
Result ID (resolved only) String Result ID, wrapped in /$$/ if a variable is being used.

Twitch API Endpoint: PATCH /helix/predictions

Request Field Type Description
broadcaster_id string The ID of the broadcaster that’s running the prediction.
id string The ID of the prediction to update.
status string The status to set the prediction to. Possible values: RESOLVED, CANCELED, LOCKED.
winning_outcome_id string The ID of the winning outcome. Required only if status is RESOLVED.

Edit

Create Poll #

Creates a new poll for your channel. Must be at least affiliate. Minimum amount of 2 choices. For more information on creating polls, check out the Twitch API Reference Guide for Create Poll.

Box Name Type Description
Login Name Dropdown Your Twitch login name (all lowercase characters)
Poll Name String Question displayed for the poll. Maximum: 60 characters.
Choice 1 String Text displayed for the first choice. Maximum: 25 characters.
Choice 2 String Text displayed for the second choice. Maximum: 25 characters.
Choice 3 String Optional third choice. Maximum: 25 characters.
Choice 4 String Optional fourth choice. Maximum: 25 characters.
Choice 5 String Optional fifth choice. Maximum: 25 characters.
Dur.(s) Number Total duration for the poll in seconds.
Points Number Number of Channel Points required to vote once with Channel Points. Minimum: 0. Maximum: 1000000.

Twitch API Endpoint: POST /helix/polls

Request Field Type Description
broadcaster_id string The ID of the broadcaster creating the poll.
title string Question displayed for the poll. Maximum: 60 characters.
choices array Array of choice objects. Each must contain a title field (max 25 characters). Minimum 2, maximum 5 choices.
duration integer Total duration for the poll in seconds. Minimum: 15, Maximum: 1800.
channel_points_voting_enabled boolean Whether viewers can cast additional votes using Channel Points.
channel_points_per_vote integer Number of Channel Points required to cast one additional vote. Minimum: 0, Maximum: 1,000,000.

Edit

Get Latest Poll/Prediction ID #

Gets the latest poll ID, prediction ID, or outcome ID to use with Get Poll/Prediction Result or End Prediction. This only works for predictions/polls initiated through SAMMI.

Box Name Type Description
Login Name Dropdown Your Twitch login name (all lowercase characters)
Get Dropdown Whether it’s a poll or prediction ID
Save Variable As String Variable name to save the ID

Saved Value:

Get Selection Saved Type Description
Poll ID String ID of the latest poll returned by Twitch.
Prediction ID String ID of the latest prediction returned by Twitch.
Prediction Outcome ID String ID of the selected outcome on the latest prediction.
”” String Saved as an empty string if the selected prediction outcome does not exist.
undefined Undefined Saved if Twitch is not connected, the channel cannot be resolved, required scopes are missing, Twitch returns an empty response, or the request fails.

Twitch API Endpoints:

GET /helix/polls — used when fetching the latest Poll ID.

GET /helix/predictions — used when fetching the latest Prediction ID or Prediction Outcome ID.

Query Parameter Type Description
broadcaster_id string The ID of the broadcaster whose polls or predictions to get.
first integer Maximum number of items to return per page (set to 1 to retrieve the latest).

Edit

Get Poll/Prediction Result #

Gets the result of a poll or prediction. Must provide its ID which can be retrieved by listening to Twitch Poll/Prediction triggers or from Get Latest Poll/Prediction ID command.

Box Name Type Description
Login Name Dropdown Your Twitch login name (all lowercase characters)
Poll/Prediction ID The ID of your poll or prediction  
Get Dropdown Whether it’s a poll or prediction
Save Variable As String Variable name to save the response

You can access the response object’s data by using Get Object Variable command.

Saved Poll Payload:

Variable Name Type Description
id string ID of the poll.
broadcaster_id string ID of the broadcaster.
broadcaster_name string Name of the broadcaster.
broadcaster_login string Login of the broadcaster.
title string Question displayed for the poll.
choices object[] Array of the poll choices.  
choice.id string ID for the choice.
choice.title string Text displayed for the choice.
choice.votes number Total number of votes received for the choice across all methods of voting.
choice.channel_points_votes number Number of votes received via Channel Points.
choice.bits_votes number Number of votes received via Bits.
bits_voting_enabled boolean Indicates if Bits can be used for voting.
bits_per_vote number Number of Bits required to vote once with Bits.
channel_points_voting_enabled boolean Indicates if Channel Points can be used for voting.
channel_points_per_vote number Number of Channel Points required to vote once with Channel Points.
status string Poll status. Valid values are:
ACTIVE: Poll is currently in progress.
COMPLETED: Poll has reached its ended_at time.
TERMINATED: Poll has been manually terminated before its ended_at time.
ARCHIVED: Poll is no longer visible on the channel.
MODERATED: Poll is no longer visible to any user on Twitch.
INVALID: Something went wrong determining the state.
duration number Total duration for the poll (in seconds).
started_at string UTC timestamp for the poll’s start time.
ended_at string UTC timestamp for the poll’s end time. Set to null if the poll is active.


Saved Prediction Payload:

Variable Name Type Description
id string ID of the Prediction.
broadcaster_id string ID of the broadcaster.
broadcaster_name string Name of the broadcaster.
broadcaster_login string Login of the broadcaster.
title string Title for the Prediction.
winning_outcome_id string ID of the winning outcome. If the status is ACTIVE, this is set to null.
outcomes object[] Array of possible outcomes for the Prediction.
outcome.id string ID for the outcome.
outcome.title string Text displayed for outcome.
outcome.users number Number of unique uesrs that chose the outcome.
outcome.channel_points number Number of Channel Points used for the outcome.
outcome.top_predictors object[] Array of users who were the top predictors. null if none.
outcome.top_predictors.user.id string ID of the user.
outcome.top_predictors.user.name string Display name of the user.
outcome.top_predictors.user.login string Login of the user.
outcome.top_predictors.user.channel_points_used number Number of Channel Points used by the user.
outcome.top_predictors.user.channel_points_won number Number of Channel Points won by the user.
outcome.color string Color for the outcome. Valid values: BLUE, PINK
prediction_window number Total duration for the Prediction (in seconds).
status string Status of the Prediction. Valid values are:
RESOLVED: A winning outcome has been chosen and the Channel Points have been distributed to the users who guessed the correct outcome.
ACTIVE: The Prediction is active and viewers can make predictions.
CANCELED: The Prediction has been canceled and the Channel Points have been refunded to participants.
LOCKED: The Prediction has been locked and viewers can no longer make predictions.
created_at string UTC timestamp for the Prediction’s start time.
ended_at string UTC timestamp for when the Prediction ended. If the status is ACTIVE, this is set to null.
locked_at string UTC timestamp for when the Prediction was locked. If the status is not LOCKED, this is set to null.

Twitch API Endpoints:

GET /helix/polls — used when retrieving poll results.

GET /helix/predictions — used when retrieving prediction results.

Query Parameter Type Description
broadcaster_id string The ID of the broadcaster whose poll or prediction to look up.
id string The ID of the specific poll or prediction to retrieve.

Edit

End Poll #

Ends a poll that is currently active.

Box Name Type Description
Login Name Dropdown Your Twitch login name (all lowercase characters)
Status Dropdown TERMINATED: End the poll manually, but allow it to be viewed publicly.
ARCHIVED: End the poll manually and do not allow it to be viewed publicly.
Poll ID String ID of the poll.

Twitch API Endpoint: PATCH /helix/polls

Request Field Type Description
broadcaster_id string The ID of the broadcaster that’s running the poll.
id string The ID of the poll to update.
status string The status to set the poll to. Possible values: TERMINATED, ARCHIVED.