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

NameInTypeRequiredDescription
channelIDpathstring (uuid)yesChannel ID.
messageIDpathstring (uuid)yesID of the poll message.

Responses

StatusMeaningBody
200The poll.Detail
401No valid session (UNAUTHORIZED).ErrorResponse
404NOT_FOUND: no such poll, or the channel is hidden from the caller.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
Detail
FieldTypeDescription
anonymous (required)booleanAnonymous 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)booleanClosed 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_votedbooleanHasVoted says that the caller voted, also in an anonymous poll.
multiple (required)booleanMultiple 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)integerTotalVoters 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

NameInTypeRequiredDescription
channelIDpathstring (uuid)yesChannel ID.
messageIDpathstring (uuid)yesID of the poll message.

Responses

StatusMeaningBody
200The poll with the caller's votes.Detail
401No valid session (UNAUTHORIZED).ErrorResponse
403FORBIDDEN: you are neither the poll's author nor hold Manage messages in the channel, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: no such poll, or the channel is hidden from the caller.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
Detail
FieldTypeDescription
anonymous (required)booleanAnonymous 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)booleanClosed 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_votedbooleanHasVoted says that the caller voted, also in an anonymous poll.
multiple (required)booleanMultiple 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)integerTotalVoters 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

NameInTypeRequiredDescription
channelIDpathstring (uuid)yesChannel ID.
messageIDpathstring (uuid)yesID of the poll message.

Request body (application/json, required): VoteRequest

FieldTypeDescription
option_ids (required)string (uuid)[]OptionIDs replace the caller's votes; an empty list withdraws them.

Responses

StatusMeaningBody
200The poll with the caller's votes.Detail
400Invalid input (INVALID_INPUT): unknown or repeated option, several options in a single-choice poll.ErrorResponse
401No valid session (UNAUTHORIZED).ErrorResponse
403FORBIDDEN: 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
404NOT_FOUND: no such poll, or the channel is hidden from the caller.ErrorResponse
409CONFLICT: the poll has ended, or the caller already voted in an anonymous poll.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
Detail
FieldTypeDescription
anonymous (required)booleanAnonymous 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)booleanClosed 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_votedbooleanHasVoted says that the caller voted, also in an anonymous poll.
multiple (required)booleanMultiple 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)integerTotalVoters 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

NameInTypeRequiredDescription
channelIDpathstring (uuid)yesChannel ID.

Request body (application/json, required): CreateRequest

FieldTypeDescription
anonymousbooleanAnonymous 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.
durationstringDuration is how long voting stays open; 24h when omitted.
multiplebooleanMultiple lets members vote for several options.
options (required)string[]
question (required)string

Responses

StatusMeaningBody
201The poll message.Message
400Invalid input (INVALID_INPUT): question or options out of bounds, duplicate options, unknown duration.ErrorResponse
401No valid session (UNAUTHORIZED).ErrorResponse
403FORBIDDEN: 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
404NOT_FOUND: no such channel, or it is hidden from the caller.ErrorResponse
429RATE_LIMITED: too many requests, or slow mode.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
Message
FieldTypeDescription
attachments (required)MediaAttachment[]
avatar_urlstring
channel_id (required)string (uuid)
componentsActionRow[]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_mentionsstring (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
embedsEmbed[]Embeds are the rich cards of a webhook message (a subset).
expires_atstring (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.
forwardForwardRefForward 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_botbooleanIsBot 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_lockedbooleanIsLocked marks a forum post as locked: only moderators can post replies.
is_pinned (required)boolean
is_resolvedbooleanIsResolved marks a forum post as solved or answered.
is_webhookbooleanIsWebhook narrows IsBot: the author is an incoming webhook (shown with a Webhook label), not a bot account (shown with a BOT label).
last_activity_atstring (date-time)LastActivityAt is the timestamp of the latest reply in the thread, or the post's creation time.
mention_rolesstring (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).
noncestring (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)integerNumber is the message's short, stable link number (/m/4821).
parent_idstring (uuid)
pinned_atstring (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_byUserRef
pollPollPoll is set when the message is a poll; its content is the question.
reactions (required)ReactionSummary[]
reply_count (required)integer
reply_toReplyPreview
reply_to_idstring (uuid)
tagsForumTag[]Tags are the forum tags attached to a forum post (up to 5 tags).
titlestringTitle 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

Something wrong on this page? Tell us.