poll_vote

Record the signed-in user’s choice on a poll. Each call replaces your previous selection, so the same command handles a first vote, a changed vote, and, on multiple-choice polls, taking a choice back.

Request

Vote for one option:

{
  "cmd": "poll_vote",
  "poll_id": "3c9d2f61-5b7e-4a0f-9e2c-1d8a6b4f0e57",
  "option_id": "1"
}

Set the full selection on a multiple-choice poll:

{
  "cmd": "poll_vote",
  "poll_id": "3c9d2f61-5b7e-4a0f-9e2c-1d8a6b4f0e57",
  "option_ids": ["0", "2"]
}

Field	Type	Required	Description
poll_id	string	Yes	ID of the poll. Surrounding spaces are trimmed.
option_id	string	One of option_id or option_ids	One option ID, such as "0". What it does depends on the poll type (see below).
option_ids	string[]	One of option_id or option_ids	Your complete new selection. Must hold at least one option ID. Wins over option_id if you send both.

How the server applies your vote:

• Single-choice poll (allow_multiselect: false): your vote becomes the one option you send. option_ids with more than one entry is rejected. There is no way to withdraw a vote.
• Multiple-choice poll, option_id: toggles that option. If you had picked it, it is removed; otherwise it is added to your existing picks. Toggling off your last pick leaves you with no votes.
• Multiple-choice poll, option_ids: replaces your picks with exactly this list.

Response

{
  "cmd": "poll_vote",
  "poll_id": "3c9d2f61-5b7e-4a0f-9e2c-1d8a6b4f0e57",
  "message_id": "8f14e45f-ceea-467a-9575-3d3b4c1b2a10",
  "channel": "general",
  "user": "alice",
  "option_ids": ["1"],
  "results": {
    "poll_id": "3c9d2f61-5b7e-4a0f-9e2c-1d8a6b4f0e57",
    "question": "When should we meet?",
    "allow_multiselect": false,
    "ended": false,
    "ended_at": null,
    "total_votes": 3,
    "results": [
      { "id": "0", "text": "Monday", "votes": 1, "voters": ["bob"] },
      { "id": "1", "text": "Tuesday", "votes": 2, "voters": ["alice", "carol"] }
    ]
  }
}

• user is the voter’s username and option_ids is their selection after this vote.
• results is a summary object. Its inner results array has one entry per option with votes and voters, but no voted flag, because the same frame goes to everyone.
• A poll in a thread also has thread_id; channel is then the parent forum.

The same frame is broadcast to every other connection whose user can view the channel, without listener. To read your own selection later, use poll_get.

Permissions

You need to be able to view the poll’s channel, or the parent forum of its thread. No extra permission is needed to vote.

The command is blocked while you are timed out.

Errors

val	When
Poll not found	No poll has this ID.
Poll has ended	The poll was ended or its expires_at has passed.
Invalid option: <id>	An option ID doesn’t exist on this poll.
Poll does not allow multiple options	You sent more than one option to a single-choice poll.
Unable to save vote	The server could not write the vote to storage.
Access denied to this channel	You can’t view the poll’s channel.
You do not have permission to view this thread	You can’t view the parent forum of the poll’s thread.
Channel not found or Thread not found	The poll’s channel or thread no longer exists.
value: Expected a value for at least one of [option_id option_ids]	You sent neither option_id nor option_ids.
Validation message	Another field is invalid, for example option_ids: Expected length at least 1 for an empty array.

See also

• poll_get
• poll_end
• Polls