Creating polls

This page covers building a poll and sending it: on its own with post or reply with, or attached to a message builder. Reading a poll back, ending it and its vote events are on the polls page. You're assumed to have a bot named "my-bot" logged in and to know how sending messages works.

How a poll is built

a new poll titled %string% creates a poll from its question. Add its answers to poll answer drafts, then hand the poll to post or reply with like any other content. with and asking work in place of titled.

on message received seen by "my-bot":
    if discord content of event-message is "!lunch":
        set {_poll} to a new poll titled "Where do we eat?"
        add "Pizza", "Burgers" and "Sushi" to poll answer drafts of {_poll}
        post {_poll} to event-channel

A poll is not a builder in the builder sense: it has no build result of, and sending it never needs await. It is checked when it is sent or attached, so a poll with no answer fails on that line, not on the line that created it. The poll that leaves is a copy: editing {_poll} afterwards changes nothing on Discord, and the same poll can be posted twice.

Options

Unlike most builders, these properties read back, so a script can check the poll before sending it.

on message received seen by "my-bot":
    if discord content of event-message is "!vote":
        set {_poll} to a new poll asking "Which features next?"
        add "Music" and "Levels" to poll answer drafts of {_poll}
        set poll duration of {_poll} to 3 days
        set multi answer of {_poll} to true
        reply with "%size of poll answer drafts of {_poll}% options, open for %poll duration of {_poll}%"
        reply with {_poll}

Answers with an emoji

A plain text added to poll answer drafts becomes an answer without emoji. For an emoji, add a new poll answer with text %string% with emoji %emote/string% instead: the emoji is a unicode emoji, an emote, or the <:name:id> form of a custom one.

set {_poll} to a new poll titled "Favorite food?"
add (a new poll answer with text "Pizza" with emoji "🍕") to poll answer drafts of {_poll}
add (a new poll answer with text "Sushi" with emoji "🍣") to poll answer drafts of {_poll}
remove "Pizza" from poll answer drafts of {_poll}

remove matches answers by their text, whether they were added as a text or as an answer object. An answer object can still be changed through draft answer text and draft answer emoji before it is added; once added, the poll holds its own copy.

Polls on a message builder

post and reply with forget the message they send. To keep it, to end the poll later or read its voters, set attached poll on a message builder and build it: the poll goes out with the message's content.

on message received seen by "my-bot":
    if discord content of event-message is "!poll-kept":
        set {_poll} to a new poll titled "Ship it?"
        add "Yes" and "No" to poll answer drafts of {_poll}
        set {_m} to a new message with content "Release vote" in event-channel
        set attached poll of {_m} to {_poll}
        await set {_sent} to the build result of {_m}
        set {poll::release} to {_sent}

A message carries one poll at most: setting attached poll again replaces the previous one. A poll cannot share a message with V2 components (containers, sections, text displays).

Errors you may see