REST: Polls
Polls in a channel: create, vote, end. Generated from mnema-talk v3.3.13 (cca4f0fdb723).
Get a poll with my votes
GET /api/channels/{channelID}/messages/{messageID}/poll
The poll as in the message, plus the options the caller voted for (my_votes) and whether they voted at all (has_voted). An anonymous poll stores no choices: my_votes is empty there and only has_voted tells that the caller took part. Needs View channels.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
channelID | path | string (uuid) | yes | Channel ID. |
messageID | path | string (uuid) | yes | ID of the poll message. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The poll. | Detail |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 404 | NOT_FOUND: no such poll, or the channel is hidden from the caller. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Detail
| Field | Type | Description |
|---|---|---|
anonymous (required) | boolean | Anonymous polls never name voters: options carry counts only, and only once the poll has ended (a running one reports 0 for every option). |
closed (required) | boolean | Closed is true once ClosesAt has passed, as the server saw it. |
closes_at (required) | string (date-time) | ClosesAt is when voting ends; ending the poll early moves it to that moment. |
has_voted | boolean | HasVoted says that the caller voted, also in an anonymous poll. |
multiple (required) | boolean | Multiple lets a member vote for several options. |
my_votes (required) | string (uuid)[] | MyVotes are the options the caller voted for. It is always empty in an anonymous poll, which does not know the choice. |
options (required) | PollOption[] | |
total_voters (required) | integer | TotalVoters counts members who voted for at least one option. |
End a poll early
POST /api/channels/{channelID}/messages/{messageID}/poll/end
The poll's author, or a member with Manage messages in the channel, closes voting now. Ending an ended poll changes nothing. A moderator ending someone else's poll is recorded in the audit log (poll.end). Broadcasts poll_update.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
channelID | path | string (uuid) | yes | Channel ID. |
messageID | path | string (uuid) | yes | ID of the poll message. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The poll with the caller's votes. | Detail |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 403 | FORBIDDEN: you are neither the poll's author nor hold Manage messages in the channel, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: no such poll, or the channel is hidden from the caller. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Detail
| Field | Type | Description |
|---|---|---|
anonymous (required) | boolean | Anonymous polls never name voters: options carry counts only, and only once the poll has ended (a running one reports 0 for every option). |
closed (required) | boolean | Closed is true once ClosesAt has passed, as the server saw it. |
closes_at (required) | string (date-time) | ClosesAt is when voting ends; ending the poll early moves it to that moment. |
has_voted | boolean | HasVoted says that the caller voted, also in an anonymous poll. |
multiple (required) | boolean | Multiple lets a member vote for several options. |
my_votes (required) | string (uuid)[] | MyVotes are the options the caller voted for. It is always empty in an anonymous poll, which does not know the choice. |
options (required) | PollOption[] | |
total_voters (required) | integer | TotalVoters counts members who voted for at least one option. |
Vote in a poll
PUT /api/channels/{channelID}/messages/{messageID}/poll/votes
Replaces the caller's votes with option_ids (one for a single-choice poll, any number of distinct options for a multiple-choice one; an empty list withdraws the vote). Allowed until the poll ends (409 afterwards). In an anonymous poll exactly one vote is possible and it cannot be changed or withdrawn (409 on a second vote, 400 on an empty list); the server records only that the member voted and raises the option counters. Needs View channels and Add reactions. Broadcasts poll_update with the new tallies; an anonymous poll broadcasts nothing per vote (it would let a small audience infer the choice) and announces the result when it is ended, and nobody learns who voted for what. At most 60 a minute per member.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
channelID | path | string (uuid) | yes | Channel ID. |
messageID | path | string (uuid) | yes | ID of the poll message. |
Request body (application/json, required): VoteRequest
| Field | Type | Description |
|---|---|---|
option_ids (required) | string (uuid)[] | OptionIDs replace the caller's votes; an empty list withdraws them. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The poll with the caller's votes. | Detail |
| 400 | Invalid input (INVALID_INPUT): unknown or repeated option, several options in a single-choice poll. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 403 | FORBIDDEN: missing the View channels or Add reactions permission in the channel, a vote in a direct message conversation of two, or the chat of its Talk, after a block (withdrawing stays possible), or cross-origin request rejected. RULES_NOT_ACCEPTED: the member has not accepted the community rules yet. | ErrorResponse |
| 404 | NOT_FOUND: no such poll, or the channel is hidden from the caller. | ErrorResponse |
| 409 | CONFLICT: the poll has ended, or the caller already voted in an anonymous poll. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Detail
| Field | Type | Description |
|---|---|---|
anonymous (required) | boolean | Anonymous polls never name voters: options carry counts only, and only once the poll has ended (a running one reports 0 for every option). |
closed (required) | boolean | Closed is true once ClosesAt has passed, as the server saw it. |
closes_at (required) | string (date-time) | ClosesAt is when voting ends; ending the poll early moves it to that moment. |
has_voted | boolean | HasVoted says that the caller voted, also in an anonymous poll. |
multiple (required) | boolean | Multiple lets a member vote for several options. |
my_votes (required) | string (uuid)[] | MyVotes are the options the caller voted for. It is always empty in an anonymous poll, which does not know the choice. |
options (required) | PollOption[] | |
total_voters (required) | integer | TotalVoters counts members who voted for at least one option. |
Post a poll
POST /api/channels/{channelID}/polls
The same as the /poll command: a message whose content is the question, with 2 to 10 options (55 characters each), single or multiple choice, optionally anonymous, open for 1h, 4h, 8h, 24h (default), 3d or 1w. Needs Send messages in the channel. Mentions in the question work as in any message. Broadcasts message_create. A poll cannot be edited.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
channelID | path | string (uuid) | yes | Channel ID. |
Request body (application/json, required): CreateRequest
| Field | Type | Description |
|---|---|---|
anonymous | boolean | Anonymous stores only that a member voted and the count per option, never the choice; a vote in it cannot be changed. Offered with the polls.anonymous feature. |
duration | string | Duration is how long voting stays open; 24h when omitted. |
multiple | boolean | Multiple lets members vote for several options. |
options (required) | string[] | |
question (required) | string |
Responses
| Status | Meaning | Body |
|---|---|---|
| 201 | The poll message. | Message |
| 400 | Invalid input (INVALID_INPUT): question or options out of bounds, duplicate options, unknown duration. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 403 | FORBIDDEN: missing the Send messages permission in the channel, or cross-origin request rejected. RULES_NOT_ACCEPTED: the member has not accepted the community rules yet. | ErrorResponse |
| 404 | NOT_FOUND: no such channel, or it is hidden from the caller. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests, or slow mode. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Message
| Field | Type | Description |
|---|---|---|
attachments (required) | MediaAttachment[] | |
avatar_url | string | |
channel_id (required) | string (uuid) | |
components | ActionRow[] | Components are the buttons and select menus of a bot's message, in action rows (doc/bots.md, Message components). Only bots set them. |
content (required) | string | |
created_at (required) | string (date-time) | |
direct_mentions | string (uuid)[] | DirectMentions are the users of Mentions this message addresses by name or through a role, not only by @all or @here: those a mute lets through. A name the sender's mention policy left as plain text is not in it. The server always sends it; it is optional so that a client can tell an older server (no field: read the text) from an empty list. |
display_name (required) | string | |
embeds | Embed[] | Embeds are the rich cards of a webhook message (a subset). |
expires_at | string (date-time) | ExpiresAt is when the server deletes the message: the end of the lifetime its sender chose (doc/timed-messages.md). Absent on a message without one. Clients hide the message at that moment on their own clock. |
forward | ForwardRef | Forward is set when the message forwards another one. It says so and nothing more: no id and no text of the original travels with the message, because readers differ in what they may see. Each reader gets the original (with its ids) from GET /api/messages/{id}/forward. |
id (required) | string (uuid) | |
is_bot | boolean | IsBot is true for messages posted by a webhook. Their author is a hidden bot account; DisplayName is the webhook's name or the username the sender gave for this message. |
is_edited (required) | boolean | |
is_locked | boolean | IsLocked marks a forum post as locked: only moderators can post replies. |
is_pinned (required) | boolean | |
is_resolved | boolean | IsResolved marks a forum post as solved or answered. |
is_webhook | boolean | IsWebhook narrows IsBot: the author is an incoming webhook (shown with a Webhook label), not a bot account (shown with a BOT label). |
last_activity_at | string (date-time) | LastActivityAt is the timestamp of the latest reply in the thread, or the post's creation time. |
mention_roles | string (uuid)[] | MentionRoles are the roles this message mentions (@Role); the client draws them as role pills. A role that was deleted since drops out. The server always sends it; it is optional for clients that build messages themselves. |
mentions (required) | string (uuid)[] | Mentions are the users this message mentions (@username, @all, @here). |
nonce | string (uuid) | Nonce is the id the author's client put on this send. Only the message_create event and the reply to that send carry it, so the client can replace its pending copy; history never does. |
number (required) | integer | Number is the message's short, stable link number (/m/4821). |
parent_id | string (uuid) | |
pinned_at | string (date-time) | PinnedAt and PinnedBy say when and by whom a pinned message was pinned; both are absent on an unpinned message (PinnedBy also when the member is gone). |
pinned_by | UserRef | |
poll | Poll | Poll is set when the message is a poll; its content is the question. |
reactions (required) | ReactionSummary[] | |
reply_count (required) | integer | |
reply_to | ReplyPreview | |
reply_to_id | string (uuid) | |
tags | ForumTag[] | Tags are the forum tags attached to a forum post (up to 5 tags). |
title | string | Title is the required title of a root post in a forum channel (max 100 characters). |
updated_at (required) | string (date-time) | |
user_id (required) | string (uuid) | |
username (required) | string |