Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

document the poll result message and embed #7050

Merged
merged 8 commits into from
Aug 16, 2024
Merged

document the poll result message and embed #7050

Changes from 2 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
ced77a3
document the poll result message and embed
anderswift Aug 2, 2024
409be51
fix redundant language
anderswift Aug 3, 2024
144fe78
create a new section for embed fields by embed type
anderswift Aug 15, 2024
222889c
edit text
advaith1 Aug 15, 2024
26998d3
links
advaith1 Aug 15, 2024
ee95649
Update docs/resources/Message.md
shaydewael Aug 16, 2024
59c3459
Update docs/resources/Message.md
shaydewael Aug 16, 2024
3952e81
tables
shaydewael Aug 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 25 additions & 8 deletions docs/resources/Message.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,7 @@ Represents a message sent in a channel within Discord.
| GUILD_INCIDENT_REPORT_RAID | 38 | true |
| GUILD_INCIDENT_REPORT_FALSE_ALARM | 39 | true |
| PURCHASE_NOTIFICATION | 44 | true |
| POLL_RESULT | 46 | true |

\* Can only be deleted by members with `MANAGE_MESSAGES` permission

Expand Down Expand Up @@ -345,6 +346,21 @@ There are multiple message types that have a `message_reference` object.
- These messages have `message_id`, `channel_id`, and `guild_id`.
- These messages will never have content, embeds, or attachments, mainly just the `message_reference` and `referenced_message` fields.

###### Poll result messages

- These are automatic messages sent after a poll has ended and the results have been finalized. (type 46)
- These messages have `message_id` and `channel_id`, which point to the original poll message. The `channel_id` will be the same as that of the poll.
- The author will be the same as the author of the poll and will be mentioned.
- These messages contain a `poll_result` embed that can have the following fields:
advaith1 marked this conversation as resolved.
Show resolved Hide resolved
- `poll_question_text` contains the question text from the original poll message.
- `victor_answer_votes` contains the number of votes for the answer(s) with the most votes.
- `total_votes` contains the total number of votes in the poll.
- `victor_answer_id` contains the id for the winning answer, if applicable.
- `victor_answer_text` contains the text for the winning answer, if applicable.
- `victor_answer_emoji_id` contains the id for the emoji associated with the winning answer, if applicable.
- `victor_answer_emoji_name` contains the name of the emoji associated with the winning answer, if applicable.
- `victor_answer_emoji_animated` specifies whether the emoji associated with the winning answer is animated, if applicable.
Copy link
Contributor

Choose a reason for hiding this comment

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

should we put this in a table so it's more readable?

Copy link
Contributor

Choose a reason for hiding this comment

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

Would be cleaner. Yes please 🙏

Copy link
Contributor

Choose a reason for hiding this comment

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

should we put this in a table so it's more readable?

I gave this whole documentation some more thought, and I think it could use some major changes:
I agree a table would probably be better than this list. But I think the whole embed documentation warrants a separate section and probably a code sample in addition to the table, since this format / way to use embeds (thankfully) isn't widespread.
This, in combination with some improvements to the wording would go a long way to clarify how poll result embeds are structured:
"embed that can have the following fields" should probably be changed to something like "embed field objects that can have the following names/entries/..." in combination with some mention of key-value pairs using the embed field name and value fields respectively.
From my understanding, the whole message reference content attribution section acts as a list of how different message types utilize the message reference object and not as an info dump. Hence why I'd consider the majority of the poll result message documentation off-topic for this section...

Copy link
Contributor

Choose a reason for hiding this comment

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

yeah this part about the embed fields should be in a new section in the embed object documentation. and we should add the automod embeds there later

Copy link
Member Author

Choose a reason for hiding this comment

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

sorry, i've been on vacation but just made some updates based on this feedback. i do agree that the specific embed fields for each type warrants a new section. i didn't want to take on documenting fields for some of the other embed types here, but i can at least get it started and we can flesh this out in another PR.


#### Voice Messages

Voice messages are messages with the `IS_VOICE_MESSAGE` flag. They have the following properties.
Expand Down Expand Up @@ -422,14 +438,15 @@ The reaction count details object contains a breakdown of normal and super react

Embed types are "loosely defined" and, for the most part, are not used by our clients for rendering. Embed attributes power what is rendered. Embed types should be considered deprecated and might be removed in a future API version.

| Type | Description |
|---------|----------------------------------------------------|
| rich | generic embed rendered from embed attributes |
| image | image embed |
| video | video embed |
| gifv | animated gif image embed rendered as a video embed |
| article | article embed |
| link | link embed |
| Type | Description |
|-------------|---------------------------------------------------------------------------------------------------------|
| rich | generic embed rendered from embed attributes |
| image | image embed |
| video | video embed |
| gifv | animated gif image embed rendered as a video embed |
| article | article embed |
| link | link embed |
| poll_result | [poll result embed](#DOCS_RESOURCES_MESSAGE/message-reference-content-attribution-poll-result-messages) |

###### Embed Thumbnail Structure

Expand Down