Skip to content

Document polls.#6746

Merged
tpcstld merged 1 commit into
mainfrom
polls
Apr 18, 2024
Merged

Document polls.#6746
tpcstld merged 1 commit into
mainfrom
polls

Conversation

@tpcstld

@tpcstld tpcstld commented Mar 21, 2024

Copy link
Copy Markdown
Contributor

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 :)

Comment thread docs/resources/Channel.md Outdated
@Misha-133

Misha-133 commented Mar 21, 2024

Copy link
Copy Markdown
Contributor

Probably should mention answers limit (10 answers per poll)

Comment thread docs/topics/Gateway_Events.md Outdated
@Lulalaby

Lulalaby commented Mar 21, 2024

Copy link
Copy Markdown
Contributor

Can guilds with BOT_DEVELOPER_EARLY_ACCESS get access to test implementations?

Comment thread docs/resources/Poll.md Outdated
Comment thread docs/resources/Poll.md Outdated
@tpcstld

tpcstld commented Mar 21, 2024

Copy link
Copy Markdown
Contributor Author

Can guilds with BOT_DEVELOPER_EARLY_ACCESS get access to test implementations?

Should be done now.

@sebm253 sebm253 mentioned this pull request Mar 21, 2024
6 tasks
@sebm253

sebm253 commented Mar 21, 2024

Copy link
Copy Markdown
Contributor

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

@Lulalaby

Copy link
Copy Markdown
Contributor

Thank you, works!

Comment thread docs/resources/Poll.md Outdated
Comment thread docs/resources/Poll.md
Comment thread docs/resources/Poll.md
Comment thread docs/resources/Poll.md Outdated
@kiterwork

Copy link
Copy Markdown

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

Comment thread docs/resources/Poll.md Outdated
Comment thread docs/resources/Poll.md Outdated
@almeidx

almeidx commented Mar 22, 2024

Copy link
Copy Markdown
Contributor

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

Comment thread docs/resources/Poll.md
Comment thread docs/resources/Poll.md Outdated
Comment thread docs/topics/Opcodes_and_Status_Codes.md
@tpcstld

tpcstld commented Mar 23, 2024

Copy link
Copy Markdown
Contributor Author

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. :(

Comment thread docs/resources/Poll.md Outdated
| expiry | IS08601 timestamp | The time when the poll ends. |
| allow_multiselect | boolean | Whether a user can select multiple answers |
| layout_type | integer | The [layout type](#DOCS_RESOURCES_POLL/layout-type) of the poll |
| results | [Poll Results Object](#DOCS_RESOURCES_POLL/poll-results-object-poll-results-object-structure) | The results of the poll |

@DonovanDMC DonovanDMC Mar 23, 2024

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

image
I can still reproduce it

@budgetdevv

budgetdevv commented Apr 17, 2024

Copy link
Copy Markdown

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

@DA-344

DA-344 commented Apr 17, 2024

Copy link
Copy Markdown
Contributor

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

@jhgg

jhgg commented Apr 17, 2024

Copy link
Copy Markdown
Contributor

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

tpcstld commented Apr 17, 2024

Copy link
Copy Markdown
Contributor Author

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.

Done: These are things that should have some semblence of stability.
* Document model
* Document gateway events
* Document endpoints.
* Abort errors.
@tpcstld

tpcstld commented Apr 17, 2024

Copy link
Copy Markdown
Contributor Author

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.

Comment thread docs/topics/Permissions.md
@NeloBlivion

Copy link
Copy Markdown

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

@FozzieHi

FozzieHi commented Apr 17, 2024

Copy link
Copy Markdown

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

tpcstld commented Apr 17, 2024

Copy link
Copy Markdown
Contributor Author

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

Copy link
Copy Markdown

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

Copy link
Copy Markdown
Contributor

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

tpcstld commented Apr 18, 2024

Copy link
Copy Markdown
Contributor Author

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
tpcstld merged commit df7d365 into main Apr 18, 2024
@tpcstld
tpcstld deleted the polls branch April 18, 2024 18:13
@tpcstld

tpcstld commented Apr 18, 2024

Copy link
Copy Markdown
Contributor Author

I said EOD but got distracted. :P

@GeniusTimo

Copy link
Copy Markdown
Contributor

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

DonovanDMC added a commit to OceanicJS/Oceanic that referenced this pull request Apr 18, 2024
@Lulalaby

Copy link
Copy Markdown
Contributor

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:
image

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

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

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

@tpcstld

tpcstld commented Apr 22, 2024

Copy link
Copy Markdown
Contributor Author

@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

Copy link
Copy Markdown
Contributor

yeah, thank you

shaydewael pushed a commit to Jupith/discord-api-docs that referenced this pull request May 14, 2024
@budgetdevv

Copy link
Copy Markdown

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

suneettipirneni added a commit to twilight-rs/twilight that referenced this pull request Jul 13, 2024
xavier-archlinux-tw pushed a commit to xavier-archlinux-tw/discord-api-docs that referenced this pull request Jul 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.