Poll

Reference for Discord poll objects and endpoints for creating polls and retrieving voter data.

A poll allows users to vote on a question with up to 10 answers. Polls are attached to messages and expire after a set duration.

Poll object

The poll object contains nested structures designed to support future extensibility.

Poll object structure

question · Poll Media Object · required

The question of the poll. Only text is supported for the question.

answers · array of Poll Answer Objects · required

Each of the answers available in the poll.

expiry · ?ISO8601 timestamp · required

The time when the poll ends. Marked as nullable to support non-expiring polls in the future, but all polls currently have an expiry.

allow_multiselect · boolean · required

Whether a user can select multiple answers.

layout_type · integer · required

The layout type of the poll.

results · Poll Results Object

The results of the poll. May be absent in certain responses where results are not fetched. Treat absence as “unknown results”, not “no results”. Optional field.

---

Poll create request object

Used when creating a poll. Similar to the poll object, but uses duration instead of expiry.

Poll create request structure

question · Poll Media Object · required

The question of the poll. Only text is supported.

answers · array of Poll Answer Objects · required

Each of the answers available in the poll. Up to 10 answers.

duration · integer

Number of hours the poll should be open for, up to 32 days. Defaults to 24.

allow_multiselect · boolean

Whether a user can select multiple answers. Defaults to false.

layout_type · integer

The layout type of the poll. Defaults to DEFAULT (1).

---

Layout type

Type	ID	Description
DEFAULT	1	The default layout type

---

Poll media object

A common object that backs both the poll question and answers. Allows extensible display options in the future.

text · string

The text of the field. Always non-null for questions and answers in practice. Maximum 300 characters for questions, 55 for answers.

emoji · partial emoji object

The emoji of the field. Optional; only applicable to answers (not the question). When creating an answer with an emoji, send either id (custom emoji) or name (standard emoji) as the only field.

---

Poll answer object

The answer_id labels each answer. It currently starts at 1 for the first answer and increments sequentially, though you should not depend on this behavior. There is a maximum of 10 answers per poll.

answer_id · integer

The ID of the answer. Only sent as part of responses from the API or Gateway.

poll_media · Poll Media Object · required

The data of the answer.

---

Poll results object

Contains the number of votes for each answer.

While a poll is in progress, results may not be perfectly accurate due to the intricacies of counting at scale. After a poll ends, a background job performs a final accurate tally. Results are finalized when is_finalized is true.

is_finalized · boolean · required

Whether the votes have been precisely counted.

answer_counts · array of Poll Answer Count Objects · required

The counts for each answer. If an answer has no votes, it will not appear in this list.

Poll answer count object structure

id · integer · required

The answer_id this count corresponds to.

count · integer · required

The number of votes for this answer.

me_voted · boolean · required

Whether the current user voted for this answer.

---

Poll endpoints

To create a poll, see Create Message. After creation, the poll message cannot be edited.

Apps are not allowed to vote on polls.

Get answer voters

GET /channels/{channel.id}/polls/{message.id}/answers/{answer_id}

Get a list of users that voted for this specific answer.

Query string params

after · snowflake

Get users after this user ID.

limit · integer · default: "25"

Max number of users to return (1–100).

Response body

users · array of user objects · required

Users who voted for this answer.

End poll

POST /channels/{channel.id}/polls/{message.id}/expire

Immediately ends the poll. You cannot end polls created by other users.

Returns a message object. Fires a Message Update gateway event.