Document polls.

[tpcstld]

Summary

Polls!

Hey folks, Discord plans to add first-party support for polls. The feature has started it's old good experimentation phase today, so now's about the time to document it as well. We expect that bots will be able to create these first-party polls when they become available. As usual this is subject to change yadda yadda no guarentees yadda yadda, but I personally I don't expect any changes.

However... some things are still being implemented right now for bots:

1. We will have a separate gateway intent for poll votes, currently it's backpacking upon the reactions intent, but there will be a new one!
2. Currently content, components and a variety of other fields are not able to be sent alongside the poll field.
3. A kind of corollary of (2), but you can't edit a message that has a poll right now either. You won't be able to edit a poll's data anyways in the future for now, but you will be able to edit everything else (like content) after (2) is done.

Most of this stuff will be done next week, after people are back from GDC. :)

Anyways cheers. I probably got some stuff wrong in this documentation so I look forward to the online community telling me that :)

[Misha-133]

Probably should mention answers limit (10 answers per poll)

[Lulalaby]

Can guilds with BOT_DEVELOPER_EARLY_ACCESS get access to test implementations?

[tpcstld]

Can guilds with BOT_DEVELOPER_EARLY_ACCESS get access to test implementations?

Should be done now.

[sebm253]

it seems like this version of the documentation is missing the duration field when creating polls. creation could use some clarification as well :-)

[Lulalaby]

Thank you, works!

[KiterWork]

Create a seperate permission node so the communities we are in won't just spam a gazillion polls?

[almeidx]

Is it intended that results.answer_counts is always empty when retrieved from the Get Channel Message endpoint for ongoing polls?
The Get Channel Messages endpoint returns the correct answer count data

[tpcstld]

Is it intended that results.answer_counts is always empty when retrieved from the Get Channel Message endpoint for ongoing polls? The Get Channel Messages endpoint returns the correct answer count data

No. Thanks for catching this. Might be a little while until we fix this though as we're heading into the weekend. :(

[DonovanDMC]

results seems to be nullable only for messages received over a gateway connection, I've yet to see it null over rest

[tpcstld]

Our intention is that it should be always non-null (with just... default values for polls without votes yet). Are you still seeing it null through the Gateway? I'm going to check later just wondering if anyone knows right now. :P

[Misha-133]

I can still reproduce it

[tpcstld]

A quick question, can webhook started polls be pre-expired (like, end them before the poll closes automatically)?

We're unlikely to support this. :( If you need to manually end your polls, create a bot so it can own the polls.

[budgetdevv]

Another question: Would it be possible to re-open polls ( Via API or otherwise ) ? For instance, when they expire after a week

[DA-344]

Discord has announced a Create Polls permission or similar, they are going to be documented, right? 😅

[jhgg]

Another question: Would it be possible to re-open polls ( Via API or otherwise ) ? For instance, when they expire after a week

No, polls closing is a final state.

Discord has announced a Create Polls permission or similar, they are going to be documented, right? 😅

Yes.

[tpcstld]

it is also empty in GET /webhooks/{webhook.id}/{webhook.token}/messages/{message.id}

This endpoint will start including both reactions and poll results.

But actually I've been thinking about my decision in #6746 (comment) and I actually think it's better for the future if results is nullable for gateway events and maybe some API endpoints. There is a certain amount of complexity for getting results for the gateway event that I feel should probably not be tackled, just like how reactions are not always returned for the message. I will update the documentation to reflect this and I'll probably make the field missing instead of it returning null.

[tpcstld]

In case you missed it, this newest update to the docs includes the SEND_POLLS permission. Client support is still rolling out for it (like graying it out) but it should be done in at most a few hours :)

I believe that I have resolved all outstanding issues. If nothing bad comes up, this PR will be merged by EOD.

[NeloBlivion]

Does a poll naturally "expiring" also fire a MESSAGE_UPDATE event, or is this only when someone manually ends it?

[FozzieHi]

Does a poll naturally "expiring" also fire a MESSAGE_UPDATE event, or is this only when someone manually ends it?

I believe it does from what I have seen myself (to be clear, I don't work for Discord so I don't know for certain).

[tpcstld]

Does a poll naturally "expiring" also fire a MESSAGE_UPDATE event, or is this only when someone manually ends it?

Yes, specifically it is sent right now when the poll finishes counting the votes. :)

[NeloBlivion]

Final issue i've found, sending content and embeds with polls works fine but it seems attachments collide with undocumented poll features; could this be disabled for now, or are we meant to implement compatibility...?
Specifically, 50035 Invalid Form Body - In poll: Poll attachment_ids must correspond with attachments data

[MCausc78]

Final issue i've found, sending content and embeds with polls works fine but it seems attachments collide with undocumented poll features; could this be disabled for now, or are we meant to implement compatibility...?
Specifically, 50035 Invalid Form Body - In poll: Poll attachment_ids must correspond with attachments data

Yes, there was PollLayoutType.IMAGE_ONLY_ANSWERS with value 2 available, probably that.

[tpcstld]

Final issue i've found, sending content and embeds with polls works fine but it seems attachments collide with undocumented poll features; could this be disabled for now, or are we meant to implement compatibility...?

For now you're not able to have attachments with the poll, sorry. :P

[tpcstld]

I said EOD but got distracted. :P

[GeniusTimo]

Will there be an addition to the change log with information about this new feature in the future?

[Lulalaby]

Not sure if this is a bug but the results object behaves weird

If the poll is open, it returns only the till not selected options in answer_counts:

If the poll gets closed with /expire, the answer_counts object is empty and the is_finalized is still false:

If the message gets re-fetched, it's correct:

Is that a bug or expected behavior due to the polls implementation or something?

[tpcstld]

@Lulalaby I think you're saying that the message returned from the /expire endpoint has empty results right? I will fix this. This is a bug.

Please note that is_finalized will still probably be false though, as the counting happens in a background job that does not block the endpoint. The non-finalized results are probably fine for most applications though.

[Lulalaby]

yeah, thank you

[budgetdevv]

Anyone able to reproduce MESSAGE_UPDATE not sending a poll result with is_finalized = true after a poll expires?