document the poll result message and embed (#7050)

* document the poll result message and embed

* fix redundant language

Co-authored-by: val.le <[email protected]>

* create a new section for embed fields by embed type

* edit text

* links

* Update docs/resources/Message.md

* Update docs/resources/Message.md

* tables

---------

Co-authored-by: val.le <[email protected]>
Co-authored-by: Advaith Jagathesan <[email protected]>
Co-authored-by: shay <[email protected]>
Co-authored-by: Shay <[email protected]>

Author: 4 people

docs/resources/Message.md

@@ -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
 
@@ -345,6 +346,13 @@ 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](#DOCS_RESOURCES_MESSAGE/embed-fields-by-embed-type-poll-result-embed-fields)
+
 #### Voice Messages
 
 Voice messages are messages with the `IS_VOICE_MESSAGE` flag. They have the following properties.
@@ -420,16 +428,15 @@ The reaction count details object contains a breakdown of normal and super react
 
 ###### Embed Types
 
-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/embed-fields-by-embed-type-poll-result-embed-fields) |
 
 ###### Embed Thumbnail Structure
 
@@ -510,6 +517,23 @@ Additionally, the combined sum of characters in all `title`, `description`, `fie
 
 Embeds are deduplicated by URL.  If a message contains multiple embeds with the same URL, only the first is shown.
 
+#### Embed Fields by Embed Type
+
+Certain embed types are used to power special UIs. These embeds use [fields](#DOCS_RESOURCES_MESSAGE/embed-object-embed-field-structure) to include additional data in key-value pairs. Below is a reference of possible embed fields for each of the following embed types. 
+
+###### Poll Result Embed Fields
+
+| Field                         | Description                                                |
+|-------------------------------|------------------------------------------------------------|
+| poll_question_text            | question text from the original poll                       |
+| victor_answer_votes           | number of votes for the answer(s) with the most votes      |
+| total_votes                   | total number of votes in the poll                          |
+| victor_answer_id?             | id for the winning answer                                  |
+| victor_answer_text?           | text for the winning answer                                |
+| victor_answer_emoji_id?       | id for an emoji associated with the winning answer         |
+| victor_answer_emoji_name?     | name of an emoji associated with the winning answer        |
+| victor_answer_emoji_animated? | if an emoji associated with the winning answer is animated |
+
 ### Attachment Object
 
 ###### Attachment Structure