Skip to content

Commit 0aaf76e

Browse files
tpcstldtpcstld
committed
Document polls.
Done: These are things that should have some semblence of stability. * Document model * Document gateway events * Document endpoints. * Abort errors. TODO: Things that are still in-flight might still change. - Gateway event for votes - currently it's still reactions intent but that will change. - Allowing message content (and other fields). - Allowing editing (of message content, not of poll)
1 parent 6326e41 commit 0aaf76e

File tree

7 files changed

+195
-18
lines changed

7 files changed

+195
-18
lines changed

‎docs/interactions/Receiving_and_Responding.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -241,6 +241,7 @@ Not all message fields are currently supported.
241241
| flags? | integer | [message flags](#DOCS_RESOURCES_CHANNEL/message-object-message-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) (only `SUPPRESS_EMBEDS`, `EPHEMERAL`, and `SUPPRESS_NOTIFICATIONS` can be set) |
242242
| components? | array of [components](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/) | message components |
243243
| attachments? \* | array of partial [attachment](#DOCS_RESOURCES_CHANNEL/attachment-object) objects | attachment objects with filename and description |
244+
| poll? | [poll](#DOCS_RESOURCES_POLL/poll-create-request-object) request object | A poll! |
244245

245246
\* See [Uploading Files](#DOCS_REFERENCE/uploading-files) for details.
246247

‎docs/resources/Channel.md

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -264,7 +264,7 @@ Represents a message sent in a channel within Discord.
264264
> Fields specific to the `MESSAGE_CREATE` and `MESSAGE_UPDATE` events are listed in the [Gateway documentation](#DOCS_TOPICS_GATEWAY_EVENTS/message-create).
265265
266266
> warn
267-
> `content`, `embeds`, `attachments`, and `components` require the [`MESSAGE_CONTENT` intent](#DOCS_TOPICS_GATEWAY/message-content-intent) to receive non-empty values.
267+
> `content`, `embeds`, `attachments`, `components`, and `poll` require the [`MESSAGE_CONTENT` intent](#DOCS_TOPICS_GATEWAY/message-content-intent) to receive non-empty values.
268268
269269
| Field | Type | Description |
270270
|-----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -301,6 +301,7 @@ Represents a message sent in a channel within Discord.
301301
| position? | integer | A generally increasing integer (there may be gaps or duplicates) that represents the approximate position of the message in a thread, it can be used to estimate the relative position of the message in a thread in company with `total_message_sent` on parent thread |
302302
| role_subscription_data? | [role subscription data](#DOCS_RESOURCES_CHANNEL/role-subscription-data-object) object | data of the role subscription purchase or renewal that prompted this ROLE_SUBSCRIPTION_PURCHASE message |
303303
| resolved? | [resolved](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-object-resolved-data-structure) data | data for users, members, channels, and roles in the message's [auto-populated select menus](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/select-menus) |
304+
| poll? | [poll](#DOCS_RESOURCES_POLL/poll-create-request-object) request object | A poll! |
304305

305306

306307
\* The author object follows the structure of the user object, but is only a valid user in the case where the message is generated by a user or bot user. If the message is generated by a webhook, the author object corresponds to the webhook's id, username, and avatar. You can tell if a message is generated by a webhook by checking for the `webhook_id` on the message object.
@@ -1068,7 +1069,7 @@ Files must be attached using a `multipart/form-data` body as described in [Uploa
10681069
###### JSON/Form Params
10691070

10701071
> info
1071-
> When creating a message, apps must provide a value for **at least one of** `content`, `embeds`, `sticker_ids`, `components`, or `files[n]`.
1072+
> When creating a message, apps must provide a value for **at least one of** `content`, `embeds`, `sticker_ids`, `components`, `files[n]`, or `poll`.
10721073
10731074
| Field | Type | Description |
10741075
|--------------------|---------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -1085,8 +1086,9 @@ Files must be attached using a `multipart/form-data` body as described in [Uploa
10851086
| attachments? | array of partial [attachment](#DOCS_RESOURCES_CHANNEL/attachment-object) objects | Attachment objects with filename and description. See [Uploading Files](#DOCS_REFERENCE/uploading-files |
10861087
| flags? | integer | [Message flags](#DOCS_RESOURCES_CHANNEL/message-object-message-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) (only `SUPPRESS_EMBEDS` and `SUPPRESS_NOTIFICATIONS` can be set) |
10871088
| enforce_nonce? | boolean | If true and nonce is present, it will be checked for uniqueness in the past few minutes. If another message was created by the same author with the same nonce, that message will be returned and no new message will be created. |
1089+
| poll? | [poll](#DOCS_RESOURCES_POLL/poll-create-request-object) request object | A poll! |
10881090

1089-
\* At least one of `content`, `embeds`, `sticker_ids`, `components`, or `files[n]` is required.
1091+
\* At least one of `content`, `embeds`, `sticker_ids`, `components`, `files[n]`, or `poll` is required.
10901092

10911093
###### Example Request Body (application/json)
10921094

‎docs/resources/Poll.md

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# Poll Resource
2+
3+
A poll is... well... a poll! It holds information about a poll!
4+
5+
![Example message containing a poll](example-poll.png)
6+
7+
### Poll Object
8+
9+
The poll object has a lot of levels and nested structures. It was also designed
10+
to support future extensibility, so some fields may appear to be more complex than
11+
necessary.
12+
13+
###### Poll Object Structure
14+
15+
| Field | Type | Description |
16+
|-------------------|-----------------------------------------------------------------------------------------------------|-----------------------------------------------------------------|
17+
| question | [Poll Media Object](#DOCS_RESOURCES_POLL/poll-media-object-poll-media-object-structure) | The question of the poll. Only `text` is supported. |
18+
| answers | List of [Poll Answer Objects](#DOCS_RESOURCES_POLL/poll-answer-object-poll-answer-object-structure) | Each of the answers available in the poll. |
19+
| expiry | IS08601 timestamp | The time when the poll ends. |
20+
| allow_multiselect | boolean | Whether a user can select multiple answers |
21+
| layout_type | integer | The [layout type](#DOCS_RESOURCES_POLL/layout-type) of the poll |
22+
| results | [Poll Results Object](#DOCS_RESOURCES_POLL/poll-results-object-poll-results-object-structure) | The results of the poll |
23+
24+
### Poll Create Request Object
25+
26+
This is the request object used when creating a poll across the different endpoints.
27+
It is similar but not exactly identical to the main [poll object](#DOCS_RESOURCES_POLL/poll-object-poll-object-structure).
28+
The main difference is that the request has `duration` which eventually becomes `expiry`.
29+
30+
###### Poll Create Request Object Structure
31+
32+
| Field | Type | Description |
33+
|-------------------|-----------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|
34+
| question | [Poll Media Object](#DOCS_RESOURCES_POLL/poll-media-object-poll-media-object-structure) | The question of the poll. Only `text` is supported. |
35+
| answers | List of [Poll Answer Objects](#DOCS_RESOURCES_POLL/poll-answer-object-poll-answer-object-structure) | Each of the answers available in the poll. |
36+
| duration | integer | Number of hours the poll should be open for, up to 7 days |
37+
| allow_multiselect | boolean | Whether a user can select multiple answers |
38+
| layout_type? | integer | The [layout type](#DOCS_RESOURCES_POLL/layout-type) of the poll. Defaults to... DEFAULT! |
39+
40+
### Layout Type
41+
42+
We might have different layouts for polls in the future.
43+
For now though, this number will be 1.
44+
45+
| Type | ID | Description |
46+
|---------|----|--------------------------------|
47+
| DEFAULT | 1 | The, uhm, default layout type. |
48+
49+
### Poll Media Object
50+
51+
The poll media object is a common object that backs both the question and answers.
52+
The intention is that it allows us to extensibly add new ways to display things in the future.
53+
For now, `question` only supports `text`, while answers can have an optional `emoji`.
54+
55+
###### Poll Media Object Structure
56+
57+
| Field | Type | Description |
58+
|--------|-----------------------------------------------------|------------------------|
59+
| text? | string | The text of the field |
60+
| emoji? | partial [emoji](#DOCS_RESOURCES_EMOJI/emoji-object) | The emoji of the field |
61+
62+
`text` should always be non-null for both questions and answers, but please do not depend on that in the future.
63+
The maximum length of `text` is 300 for the question, and 55 for any answer.
64+
65+
When creating a poll answer with an emoji, one only needs to send either the `id` (custom emoji) or `name` (default emoji) as the only field.
66+
67+
### Poll Answer Object
68+
69+
The `answer_id` is a number that labels each answer.
70+
As an implementation detail, it currently starts at 1 for the first answer and goes up sequentially.
71+
We recommend against depending on this sequence.
72+
73+
Currently, there is a maximum of 10 answers per poll.
74+
75+
###### Poll Answer Object Structure
76+
77+
| Field | Type | Description |
78+
|-------------|-----------------------------------------------------------------------------------------|------------------------|
79+
| answer_id\* | integer | The ID of the answer |
80+
| poll_media | [Poll Media Object](#DOCS_RESOURCES_POLL/poll-media-object-poll-media-object-structure) | The data of the answer |
81+
82+
### Poll Results Object
83+
84+
In a nutshell, this contains the number of votes for each answer.
85+
86+
Due to the intricacies of counting at scale, while a poll is in progress the results may not be perfectly accurate.
87+
They usually are accurate, and shouldn't deviate significantly -- it's just difficult to make guarantees.
88+
89+
To compensate for this, after a poll is finished there is a background job which performs a final, accurate tally of votes.
90+
This tally concludes once `is_finalized` is `true`.
91+
92+
If `answer_counts` does not contain an entry for a particular answer, then there are no votes for that answer.
93+
94+
###### Poll Results Object Structure
95+
96+
| Field | Type | Description |
97+
|---------------|-----------------------------------------------------------------------------------------------------------------|-----------------------------------------------|
98+
| is_finalized | boolean | Whether the votes have been precisely counted |
99+
| answer_counts | List of [Poll Answer Count Object](#DOCS_RESOURCES_POLL/poll-results-object-poll-answer-count-object-structure) | The counts for each answer |
100+
101+
###### Poll Answer Count Object Structure
102+
103+
| Field | Type | Description |
104+
|----------|---------|------------------------------------------------|
105+
| id | integer | The `answer_id` |
106+
| count | integer | The number of votes for this answer |
107+
| me_voted | boolean | Whether the current user voted for this answer |
108+
109+
# Poll Endpoints
110+
111+
For creating a poll, see [Create Message](#DOCS_RESOURCES_CHANNEL/create-message). After creation, the poll message cannot be edited.
112+
113+
Apps are not allowed to vote on polls. No rights! :)
114+
115+
## Get Answer Voters % GET /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/polls/{message.id#DOCS_RESOURCES_CHANNEL/message-object}/answers/{answer_id#DOCS_RESOURCES_POLL/poll-answer-object}
116+
117+
Get a list of users that voted for this specific answer.
118+
119+
###### Query String Params
120+
121+
| Field | Type | Description | Default |
122+
|--------|-----------|---------------------------------------|---------|
123+
| after? | snowflake | Get users after this user ID | absent |
124+
| limit? | integer | Max number of users to return (1-100) | 25 |
125+
126+
###### Response Body
127+
128+
| Field | Type | Description |
129+
|-------|---------------------------------------------------|---------------------------------|
130+
| users | array of [user](#DOCS_RESOURCES_USER/user-object) | Users who voted for this answer |
131+
132+
## Expire Poll % POST /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/polls/{message.id#DOCS_RESOURCES_CHANNEL/message-object}/expire
133+
134+
Immediately expires (i.e. ends) the poll.
135+
136+
Returns a [message](#DOCS_RESOURCES_CHANNEL/message-object) object. Fires a [Message Update](#DOCS_TOPICS_GATEWAY_EVENTS/message-update) Gateway event.

0 commit comments

Comments
 (0)