> ## Documentation Index > Fetch the complete documentation index at: https://docs.discord.com/llms.txt > Use this file to discover all available pages before exploring further. # Message Resource > Reference for Discord message objects and management endpoints. export const Route = ({method, children}) => { return
{method} {children}
; }; export const ManualAnchor = ({id}) => { return
; }; ### Message Object Represents a message sent in a channel within Discord. ###### Message Structure Fields specific to the `MESSAGE_CREATE` and `MESSAGE_UPDATE` events are listed in the [Gateway documentation](/developers/events/gateway-events#message-create). An app will receive empty values in the `content`, `embeds`, `attachments`, and `components` fields while `poll` will be omitted if they have not configured (or been approved for) the [`MESSAGE_CONTENT` privileged intent (`1 << 15`)](/developers/events/gateway#message-content-intent). | Field | Type | Description | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | snowflake | id of the message | | channel\_id | snowflake | id of the channel the message was sent in | | author \[1] | [user](/developers/resources/user#user-object) object | the author of this message (not guaranteed to be a valid user, see below) | | content \[2] | string | contents of the message | | timestamp | ISO8601 timestamp | when this message was sent | | edited\_timestamp | ?ISO8601 timestamp | when this message was edited (or null if never) | | tts | boolean | whether this was a TTS message | | mention\_everyone | boolean | whether this message mentions everyone | | mentions | array of [user](/developers/resources/user#user-object) objects | users specifically mentioned in the message | | mention\_roles | array of [role](/developers/topics/permissions#role-object) object ids | roles specifically mentioned in this message | | mention\_channels? \[3] | array of [channel mention](/developers/resources/message#channel-mention-object) objects | channels specifically mentioned in this message | | attachments \[2] | array of [attachment](/developers/resources/message#attachment-object) objects | any attached files that are not referenced in embeds or components | | embeds \[2] | array of [embed](/developers/resources/message#embed-object) objects | any embedded content | | reactions? | array of [reaction](/developers/resources/message#reaction-object) objects | reactions to the message | | nonce? | integer or string | used for validating a message was sent | | pinned | boolean | whether this message is pinned | | webhook\_id? | snowflake | if the message is generated by a webhook, this is the webhook's id | | type | integer | [type of message](/developers/resources/message#message-object-message-types) | | activity? | [message activity](/developers/resources/message#message-object-message-activity-structure) object | sent with Rich Presence-related chat embeds | | application? | partial [application](/developers/resources/application#application-object) object | sent with Rich Presence-related chat embeds | | application\_id? | snowflake | if the message is an [Interaction](/developers/interactions/receiving-and-responding) or application-owned webhook, this is the id of the application | | flags? | integer | [message flags](/developers/resources/message#message-object-message-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) | | message\_reference? | [message reference](/developers/resources/message#message-reference-structure) object | data showing the source of a crosspost, channel follow add, pin, or reply message | | message\_snapshots? \[5] | array of [message snapshot](/developers/resources/message#message-snapshot-object) objects | the message associated with the `message_reference`. This is a minimal subset of fields in a message (e.g. `author` is excluded.) | | referenced\_message? \[4] | ?[message object](/developers/resources/message#message-object) | the message associated with the message\_reference | | interaction\_metadata? | [message interaction metadata object](/developers/resources/message#message-interaction-metadata-object) | Sent if the message is sent as a result of an [interaction](/developers/interactions/receiving-and-responding) | | interaction? | [message interaction object](/developers/interactions/receiving-and-responding#message-interaction-object-message-interaction-structure) | **Deprecated in favor of `interaction_metadata`**; sent if the message is a response to an [interaction](/developers/interactions/receiving-and-responding) | | thread? | [channel](/developers/resources/channel#channel-object) object | the thread that was started from this message, includes [thread member](/developers/resources/channel#thread-member-object) object | | components? \[2] | array of [message components](/developers/components/reference#component-object) | sent if the message contains components like buttons, action rows, or other interactive components | | sticker\_items? | array of [message sticker item objects](/developers/resources/sticker#sticker-item-object) | sent if the message contains stickers | | stickers? | array of [sticker](/developers/resources/sticker#sticker-object) objects | **Deprecated** the stickers sent with the message | | 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 | | role\_subscription\_data? | [role subscription data](/developers/resources/message#role-subscription-data-object) object | data of the role subscription purchase or renewal that prompted this ROLE\_SUBSCRIPTION\_PURCHASE message | | resolved? | [resolved](/developers/interactions/receiving-and-responding#interaction-object-resolved-data-structure) data | data for users, members, channels, and roles referenced in this message | | poll? \[2] | [poll](/developers/resources/poll#poll-object) object | A poll! | | call? | [message call](/developers/resources/message#message-call-object) object | the call associated with the message | | shared\_client\_theme? | [shared client theme](/developers/resources/message#shared-client-theme-object) object | the custom client-side theme shared via the message | \[1] 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. \[2] An app will receive empty values in the `content`, `embeds`, `attachments`, and `components` fields while `poll` will be omitted if they have not configured (or been approved for) the [`MESSAGE_CONTENT` privileged intent (`1 << 15`)](/developers/events/gateway#message-content-intent). \[3] Not all channel mentions in a message will appear in `mention_channels`. Only textual channels that are visible to everyone in a public guild will ever be included. Only crossposted messages (via Channel Following) currently include `mention_channels` at all. If no mentions in the message meet these requirements, this field will not be sent. \[4] This field is only returned for messages with a `type` of `19` (REPLY), `21` (THREAD\_STARTER\_MESSAGE), or `23` (CONTEXT\_MENU\_COMMAND). If the message is one of these but the `referenced_message` field is not present, the backend did not attempt to fetch the message that was being replied to, so its state is unknown. If the field exists but is null, the referenced message was deleted. \[5] See [message reference types](/developers/resources/message#message-reference-types) ###### Message Types Type `19` and `20` are only available in API v8 and above. In v6, they are represented as type `0`. Additionally, type `21` is only available in API v9 and above. | Type | Value | Deletable | | ------------------------------------------------- | ----- | --------- | | DEFAULT | 0 | true | | RECIPIENT\_ADD | 1 | false | | RECIPIENT\_REMOVE | 2 | false | | CALL | 3 | false | | CHANNEL\_NAME\_CHANGE | 4 | false | | CHANNEL\_ICON\_CHANGE | 5 | false | | CHANNEL\_PINNED\_MESSAGE | 6 | true | | USER\_JOIN | 7 | true | | GUILD\_BOOST | 8 | true | | GUILD\_BOOST\_TIER\_1 | 9 | true | | GUILD\_BOOST\_TIER\_2 | 10 | true | | GUILD\_BOOST\_TIER\_3 | 11 | true | | CHANNEL\_FOLLOW\_ADD | 12 | true | | GUILD\_DISCOVERY\_DISQUALIFIED | 14 | true | | GUILD\_DISCOVERY\_REQUALIFIED | 15 | true | | GUILD\_DISCOVERY\_GRACE\_PERIOD\_INITIAL\_WARNING | 16 | true | | GUILD\_DISCOVERY\_GRACE\_PERIOD\_FINAL\_WARNING | 17 | true | | THREAD\_CREATED | 18 | true | | REPLY | 19 | true | | CHAT\_INPUT\_COMMAND | 20 | true | | THREAD\_STARTER\_MESSAGE | 21 | false | | GUILD\_INVITE\_REMINDER | 22 | true | | CONTEXT\_MENU\_COMMAND | 23 | true | | AUTO\_MODERATION\_ACTION | 24 | true\* | | ROLE\_SUBSCRIPTION\_PURCHASE | 25 | true | | INTERACTION\_PREMIUM\_UPSELL | 26 | true | | STAGE\_START | 27 | true | | STAGE\_END | 28 | true | | STAGE\_SPEAKER | 29 | true | | STAGE\_TOPIC | 31 | true | | GUILD\_APPLICATION\_PREMIUM\_SUBSCRIPTION | 32 | true | | GUILD\_INCIDENT\_ALERT\_MODE\_ENABLED | 36 | true | | GUILD\_INCIDENT\_ALERT\_MODE\_DISABLED | 37 | true | | 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 ###### Message Activity Structure | Field | Type | Description | | ---------- | ------- | ----------------------------------------------------------------------------------------------- | | type | integer | [type of message activity](/developers/resources/message#message-object-message-activity-types) | | party\_id? | string | party\_id from a Rich Presence event | ###### Message Activity Types | Type | Value | | ------------- | ----- | | JOIN | 1 | | SPECTATE | 2 | | LISTEN | 3 | | JOIN\_REQUEST | 5 | ###### Message Flags | Flag | Value | Description | | -------------------------------------------- | --------- | --------------------------------------------------------------------------------------- | | CROSSPOSTED | `1 << 0` | this message has been published to subscribed channels (via Channel Following) | | IS\_CROSSPOST | `1 << 1` | this message originated from a message in another channel (via Channel Following) | | SUPPRESS\_EMBEDS | `1 << 2` | do not include any embeds when serializing this message | | SOURCE\_MESSAGE\_DELETED | `1 << 3` | the source message for this crosspost has been deleted (via Channel Following) | | URGENT | `1 << 4` | this message came from the urgent message system | | HAS\_THREAD | `1 << 5` | this message has an associated thread, with the same id as the message | | EPHEMERAL | `1 << 6` | this message is only visible to the user who invoked the Interaction | | LOADING | `1 << 7` | this message is an Interaction Response and the bot is "thinking" | | FAILED\_TO\_MENTION\_SOME\_ROLES\_IN\_THREAD | `1 << 8` | this message failed to mention some roles and add their members to the thread | | SUPPRESS\_NOTIFICATIONS | `1 << 12` | this message will not trigger push and desktop notifications | | IS\_VOICE\_MESSAGE | `1 << 13` | this message is a voice message | | HAS\_SNAPSHOT | `1 << 14` | this message has a snapshot (via Message Forwarding) | | IS\_COMPONENTS\_V2 \* | `1 << 15` | allows you to create fully [component](/developers/components/overview)-driven messages | \* Once a message has been sent with this flag, it can't be removed from that message. ###### Example Message ```json theme={"system"} { "reactions": [ { "count": 1, "count_details": { "burst": 0, "normal": 1 }, "me": false, "me_burst": false, "emoji": { "id": null, "name": "🔥" }, "burst_colors": [] } ], "attachments": [], "tts": false, "embeds": [], "timestamp": "2017-07-11T17:27:07.299000+00:00", "mention_everyone": false, "id": "334385199974967042", "pinned": false, "edited_timestamp": null, "author": { "username": "Mason", "discriminator": "9999", "id": "53908099506183680", "avatar": "a_bab14f271d565501444b2ca3be944b25" }, "mention_roles": [], "content": "Supa Hot", "channel_id": "290926798999357250", "mentions": [], "type": 0 } ``` ###### Example Crossposted Message ```json theme={"system"} { "reactions": [ { "count": 1, "count_details": { "burst": 0, "normal": 1 }, "me": false, "me_burst": false, "emoji": { "id": null, "name": "🔥" }, "burst_colors": [] } ], "attachments": [], "tts": false, "embeds": [], "timestamp": "2017-07-11T17:27:07.299000+00:00", "mention_everyone": false, "id": "334385199974967042", "pinned": false, "edited_timestamp": null, "author": { "username": "Mason", "discriminator": "9999", "id": "53908099506183680", "avatar": "a_bab14f271d565501444b2ca3be944b25" }, "mention_roles": [], "mention_channels": [ { "id": "278325129692446722", "guild_id": "278325129692446720", "name": "big-news", "type": 5 } ], "content": "Big news! In this <#278325129692446722> channel!", "channel_id": "290926798999357250", "mentions": [], "type": 0, "flags": 2, "message_reference": { "type": 0, "channel_id": "278325129692446722", "guild_id": "278325129692446720", "message_id": "306588351130107906" } } ``` ### Message Interaction Metadata Object Metadata about the interaction, including the source of the interaction and relevant server and user IDs. One of [Application Command Interaction Metadata](/developers/resources/message#message-interaction-metadata-object-application-command-interaction-metadata-structure), [Message Component Interaction Metadata](/developers/resources/message#message-interaction-metadata-object-message-component-interaction-metadata-structure), or [Modal Submit Interaction Metadata](/developers/resources/message#message-interaction-metadata-object-modal-submit-interaction-metadata-structure). ###### Application Command Interaction Metadata Structure | Field | Type | Description | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | snowflake | ID of the interaction | | type | [interaction type](/developers/interactions/receiving-and-responding#interaction-object-interaction-type) | Type of interaction | | user | [user](/developers/resources/user#user-object) object | User who triggered the interaction | | authorizing\_integration\_owners | dictionary with keys of [application integration types](/developers/resources/application#application-object-application-integration-types) | IDs for installation context(s) related to an interaction. Details in [Authorizing Integration Owners Object](/developers/interactions/receiving-and-responding#interaction-object-authorizing-integration-owners-object) | | original\_response\_message\_id? | snowflake | ID of the original response message, present only on [follow-up messages](/developers/interactions/receiving-and-responding) | | target\_user? | [user](/developers/resources/user#user-object) object | The user the command was run on, present only on [user command](/developers/interactions/application-commands#user-commands) interactions | | target\_message\_id? | snowflake | The ID of the message the command was run on, present only on [message command](/developers/interactions/application-commands#message-commands) interactions. The original response message will also have `message_reference` and `referenced_message` pointing to this message. | ###### Message Component Interaction Metadata Structure | Field | Type | Description | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | snowflake | ID of the interaction | | type | [interaction type](/developers/interactions/receiving-and-responding#interaction-object-interaction-type) | Type of interaction | | user | [user](/developers/resources/user#user-object) object | User who triggered the interaction | | authorizing\_integration\_owners | dictionary with keys of [application integration types](/developers/resources/application#application-object-application-integration-types) | IDs for installation context(s) related to an interaction. Details in [Authorizing Integration Owners Object](/developers/interactions/receiving-and-responding#interaction-object-authorizing-integration-owners-object) | | original\_response\_message\_id? | snowflake | ID of the original response message, present only on [follow-up messages](/developers/interactions/receiving-and-responding) | | interacted\_message\_id | snowflake | ID of the message that contained the interactive component | ###### Modal Submit Interaction Metadata Structure | Field | Type | Description | | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | snowflake | ID of the interaction | | type | [interaction type](/developers/interactions/receiving-and-responding#interaction-object-interaction-type) | Type of interaction | | user | [user](/developers/resources/user#user-object) object | User who triggered the interaction | | authorizing\_integration\_owners | dictionary with keys of [application integration types](/developers/resources/application#application-object-application-integration-types) | IDs for installation context(s) related to an interaction. Details in [Authorizing Integration Owners Object](/developers/interactions/receiving-and-responding#interaction-object-authorizing-integration-owners-object) | | original\_response\_message\_id? | snowflake | ID of the original response message, present only on [follow-up messages](/developers/interactions/receiving-and-responding) | | triggering\_interaction\_metadata | [Application Command Interaction Metadata](/developers/resources/message#message-interaction-metadata-object-application-command-interaction-metadata-structure) or [Message Component Interaction Metadata](/developers/resources/message#message-interaction-metadata-object-message-component-interaction-metadata-structure) object | Metadata for the interaction that was used to open the modal | ### Message Call Object Information about the call in a private channel. ###### Message Call Object Structure | Field | Type | Description | | ----------------- | ------------------- | ------------------------------------------------------------------------------------------------ | | participants | array of snowflakes | array of [user](/developers/resources/user#user-object) object ids that participated in the call | | ended\_timestamp? | ?ISO8601 timestamp | time when call ended | ### Message Reference Object #### Message Reference Structure | Field | Type | Description | | ---------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------- | | type? \* | integer | [type of reference](/developers/resources/message#message-reference-types). | | message\_id? | snowflake | id of the originating message | | channel\_id? \*\* | snowflake | id of the originating message's channel | | guild\_id? | snowflake | id of the originating message's guild | | fail\_if\_not\_exists? | boolean | when sending, whether to error if the referenced message doesn't exist instead of sending as a normal (non-reply) message, default true | \* If `type` is unset, `DEFAULT` can be assumed in order to match the behavior before message reference had types. In future API versions this will become a required field. \*\* `channel_id` is optional when creating a reply, but will always be present when receiving an event/response that includes this data model. **Required for forwards.** #### Message Reference Types Determines how associated data is populated. | Type | Value | Coupled Message Field | Description | | ------- | ----- | --------------------- | -------------------------------------------------------- | | DEFAULT | 0 | `referenced_message` | A standard reference used by replies. | | FORWARD | 1 | `message_snapshot` | Reference used to point to a message at a point in time. | `FORWARD` can only be used for basic messages; i.e. messages which do not have strong bindings to a non global entity. Thus we support only messages with type `DEFAULT`, `REPLY`, `CHAT_INPUT_COMMAND`, or `CONTEXT_MENU_COMMAND`, and don't support messages with a poll, call, or activity. This is subject to change in the future. #### Message Reference Content Attribution Message references are generic attribution on a message. There are multiple message types that have a `message_reference` object. ###### Crosspost messages * These are messages that originated from another channel (IS\_CROSSPOST flag). * These messages have all three fields, which point to the original message that was crossposted. ###### Channel Follow Add messages * These are automatic messages sent when a channel is followed into the current channel (type 12). * These messages have the `channel_id` and `guild_id` fields, which point to the followed announcement channel. ###### Pin messages * These are automatic messages sent when a message is pinned (type 6). * These messages have `message_id` and `channel_id`, and `guild_id` if it is in a guild, which point to the message that was pinned. ###### Forwards * These are messages which capture a snapshot of a message. * These messages have an array of [`message_snapshot`](/developers/resources/message#message-snapshot-object) objects containing a copy of the original message. This copy follows the same structure as a message, but has only the minimal set of fields returned required for context/rendering. * of note: `author` will be excluded * A forwarded message can be identified by looking at its `message_reference.type` field * `message_snapshots` will be the message data associated with the forward. Currently we support only 1 snapshot. * prevents spoofing forwarded data * `message_snapshots` are taken the moment a forward message is created, and are **immutable**; any mutations to the original message will not be propagated. * Forwards are created by including a message\_reference with `FORWARD` type when sending a message. * Required fields: `type`, `message_id`, `channel_id` * the requestor must have `VIEW_CHANNEL` permissions ###### Replies * These are messages replying to a previous message (type 19). * These messages have `message_id` and `channel_id`, and `guild_id` if it is in a guild, which point to the message that was replied to. The channel\_id and guild\_id will be the same as the reply. * Replies are created by including a message\_reference when sending a message. When sending, only `message_id` is required. * These messages can have the referenced message resolved in the `referenced_message` field. ###### Thread Created messages * These are automatic messages sent when a public thread is created from an old message or without a message (type 18). * These messages have the `channel_id` and `guild_id` fields, which point to the created thread channel. ###### Thread starter messages * These are the first message in public threads created from messages. They point back to the message in the parent channel from which the thread was started. (type 21) * These messages have `message_id`, `channel_id`, and `guild_id`. * These messages can have the referenced message resolved in the `referenced_message` field. * 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](/developers/resources/message#embed-fields-by-embed-type-poll-result-embed-fields) ###### Context Menu Command messages * These are messages sent when a user uses a context menu Application Command. (type 23) * If the command was a [message command](/developers/interactions/application-commands#message-commands), the message will have `message_id` and `channel_id`, and `guild_id` if it is in a guild, which point to the message that the command was used on. The channel\_id and guild\_id will be the same as the new message. * These messages can have the referenced message resolved in the `referenced_message` field. #### Voice Messages Voice messages are messages with the `IS_VOICE_MESSAGE` flag. They have the following properties. * They cannot be edited. * Only a single audio attachment is allowed. No content, stickers, etc... * The [attachment](/developers/resources/message#attachment-object) has additional fields: `duration_secs` and `waveform`. The `Content-Type` of the attachment must begin with `audio/` to respect these fields. The `waveform` is intended to be a preview of the entire voice message, with 1 byte per datapoint encoded in base64. Clients sample the recording at most once per 100 milliseconds, but will downsample so that no more than 256 datapoints are in the waveform. As of 2023-04-14, clients upload a 1 channel, 48000 Hz, 32kbps Opus stream in an OGG container. The encoding, and the waveform details, are an implementation detail and may change without warning or documentation. ### Message Snapshot Object #### Message Snapshot Structure | Field | Type | Description | | --------- | ---------------------------------------------------------------------- | ------------------------------------------------- | | message\* | partial [message](/developers/resources/message#message-object) object | minimal subset of fields in the forwarded message | \* The current subset of message fields consists of: `type`, `content`, `embeds`, `attachments`, `timestamp`, `edited_timestamp`, `flags`, `mentions`, `mention_roles`, `stickers`, `sticker_items`, and `components`. While message snapshots are able to support nested snapshots, we currently limit the depth of nesting to 1. ### Reaction Object ###### Reaction Structure | Field | Type | Description | | -------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | count | integer | Total number of times this emoji has been used to react (including super reacts) | | count\_details | object | [Reaction count details object](/developers/resources/message#reaction-count-details-object) | | me | boolean | Whether the current user reacted using this emoji | | me\_burst | boolean | Whether the current user super-reacted using this emoji | | emoji | partial [emoji](/developers/resources/emoji#emoji-object) object | emoji information | | burst\_colors | array | HEX colors used for super reaction | ### Reaction Count Details Object The reaction count details object contains a breakdown of normal and super reaction counts for the associated emoji. ###### Reaction Count Details Structure | Field | Type | Description | | ------ | ------- | ------------------------- | | burst | integer | Count of super reactions | | normal | integer | Count of normal reactions | ### Embed Object ###### Embed Structure | Field | Type | Description | | ------------ | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | | title? | string | title of embed | | type? | string | [type of embed](/developers/resources/message#embed-object-embed-types) (always "rich" for webhook embeds) | | description? | string | description of embed | | url? | string | url of embed | | timestamp? | ISO8601 timestamp | timestamp of embed content | | color? | integer | color code of the embed | | footer? | [embed footer](/developers/resources/message#embed-object-embed-footer-structure) object | footer information | | image? | [embed image](/developers/resources/message#embed-object-embed-image-structure) object | image information | | thumbnail? | [embed image](/developers/resources/message#embed-object-embed-image-structure) object | thumbnail information | | video? | [embed video](/developers/resources/message#embed-object-embed-video-structure) object | video information | | provider? | [embed provider](/developers/resources/message#embed-object-embed-provider-structure) object | provider information | | author? | [embed author](/developers/resources/message#embed-object-embed-author-structure) object | author information | | fields? | array of [embed field](/developers/resources/message#embed-object-embed-field-structure) objects | fields information, max of 25 | | flags? | integer | [embed flags](/developers/resources/message#embed-object-embed-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) | ###### Embed Types | 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](/developers/resources/message#embed-fields-by-embed-type-poll-result-embed-fields) | ###### Embed Flags | Flag | Value | Description | | ----------------------------- | -------- | -------------------------------------------------------- | | IS\_CONTENT\_INVENTORY\_ENTRY | `1 << 5` | this embed is a fallback for a reply to an activity card | ###### Embed Video Structure | Field | Type | Description | | --------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | url? | string | source url of video | | proxy\_url? | string | a proxied url of the video | | height? | integer | height of video | | width? | integer | width of video | | content\_type? | string | the video's [media type](https://en.wikipedia.org/wiki/Media_type) | | placeholder? | string | [thumbhash](https://evanw.github.io/thumbhash/) placeholder of the video | | placeholder\_version? | integer | version of the placeholder | | description? | string | description (alt text) for the video | | flags? | integer | [embed media flags](/developers/resources/message#embed-object-embed-media-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) | ###### Embed Image Structure | Field | Type | Description | | --------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | url | string | source url of image (only supports http(s) and attachments) | | proxy\_url? | string | a proxied url of the image | | height? | integer | height of image | | width? | integer | width of image | | content\_type? | string | the image's [media type](https://en.wikipedia.org/wiki/Media_type) | | placeholder? | string | [thumbhash](https://evanw.github.io/thumbhash/) placeholder of the image | | placeholder\_version? | integer | version of the placeholder | | description? | string | description (alt text) for the image | | flags? | integer | [embed media flags](/developers/resources/message#embed-object-embed-media-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) | ###### Embed Media Flags | Flag | Value | Description | | ------------ | -------- | ---------------------- | | IS\_ANIMATED | `1 << 5` | this image is animated | ###### Embed Provider Structure | Field | Type | Description | | ----- | ------ | ---------------- | | name? | string | name of provider | | url? | string | url of provider | ###### Embed Author Structure | Field | Type | Description | | ----------------- | ------ | ---------------------------------------------------------- | | name | string | name of author | | url? | string | url of author (only supports http(s)) | | icon\_url? | string | url of author icon (only supports http(s) and attachments) | | proxy\_icon\_url? | string | a proxied url of author icon | ###### Embed Footer Structure | Field | Type | Description | | ----------------- | ------ | ---------------------------------------------------------- | | text | string | footer text | | icon\_url? | string | url of footer icon (only supports http(s) and attachments) | | proxy\_icon\_url? | string | a proxied url of footer icon | ###### Embed Field Structure | Field | Type | Description | | ------- | ------- | ----------------------------------------------- | | name | string | name of the field | | value | string | value of the field | | inline? | boolean | whether or not this field should display inline | ###### Embed Limits To facilitate showing rich content, rich embeds do not follow the traditional limits of message content. However, some limits are still in place to prevent excessively large embeds. The following table describes the limits: All of the following limits are measured inclusively. Leading and trailing whitespace characters are not included (they are trimmed automatically). | Field | Limit | | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | title | 256 characters | | description | 4096 characters | | fields | Up to 25 [field](/developers/resources/message#embed-object-embed-field-structure) objects | | [field.name](/developers/resources/message#embed-object-embed-field-structure) | 256 characters | | [field.value](/developers/resources/message#embed-object-embed-field-structure) | 1024 characters | | [footer.text](/developers/resources/message#embed-object-embed-footer-structure) | 2048 characters | | [author.name](/developers/resources/message#embed-object-embed-author-structure) | 256 characters | Additionally, the combined sum of characters in all `title`, `description`, `field.name`, `field.value`, `footer.text`, and `author.name` fields across all embeds attached to a message must not exceed 6000 characters. Violating any of these constraints will result in a `Bad Request` response. 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](/developers/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 For the `attachments` array in Message Create/Edit requests, only the `id` is required. | Field | Type | Description | | --------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | id | snowflake | attachment id | | filename | string | name of file attached | | title? | string | the title of the file | | description? | string | description (alt text) for the file (max 1024 characters) | | content\_type? | string | the attachment's [media type](https://en.wikipedia.org/wiki/Media_type) | | size | integer | size of file in bytes | | url | string | source url of file | | proxy\_url | string | a proxied url of file | | height? | ?integer | height of file (if image or video) | | width? | ?integer | width of file (if image or video) | | placeholder? | string | [thumbhash](https://evanw.github.io/thumbhash/) placeholder (if image or video) | | placeholder\_version? | integer | version of the placeholder (if image or video) | | ephemeral? \* | boolean | whether this attachment is ephemeral | | duration\_secs? | float | the duration of the audio file (currently for voice messages) | | waveform? | string | base64 encoded bytearray representing a sampled waveform (currently for voice messages) | | flags? | integer | [attachment flags](/developers/resources/message#attachment-object-attachment-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) | | clip\_participants? | array of [user](/developers/resources/user#user-object) objects | for Clips, array of users who were in the stream | | clip\_created\_at? | ISO8601 timestamp | for Clips, when the clip was created | | application? | ?[application](/developers/resources/application#application-object) | for Clips, the application in the stream, if recognized | \* Ephemeral attachments will automatically be removed after a set period of time. Ephemeral attachments on messages are guaranteed to be available as long as the message itself exists. ###### Attachment Flags | Flag | Value | Description | | ------------- | -------- | ------------------------------------------------------------------------------------------------------------- | | IS\_CLIP | `1 << 0` | this attachment is a [Clip from a stream](https://support.discord.com/hc/en-us/articles/16861982215703) | | IS\_THUMBNAIL | `1 << 1` | this attachment is the thumbnail of a thread in a media channel, displayed in the grid but not on the message | | IS\_REMIX | `1 << 2` | this attachment has been edited using the remix feature on mobile (deprecated) | | IS\_SPOILER | `1 << 3` | this attachment was marked as a spoiler and is blurred until clicked | | IS\_ANIMATED | `1 << 5` | this attachment is an animated image | ### Channel Mention Object ###### Channel Mention Structure | Field | Type | Description | | --------- | --------- | --------------------------------------------------------------------------------- | | id | snowflake | id of the channel | | guild\_id | snowflake | id of the guild containing the channel | | type | integer | the [type of channel](/developers/resources/channel#channel-object-channel-types) | | name | string | the name of the channel | ### Allowed Mentions Object Setting the `allowed_mentions` field lets you determine whether users will receive notifications when you include mentions in the message content, or the content of components attached to that message. This field is always validated against your permissions and the presence of said mentions in the message, to avoid "phantom" pings where users receive a notification without a visible mention in the message. For example, if you want to ping everyone, including it in the `allowed_mentions` field is not enough, the mention format (`@everyone`) must also be present in the content of the message or its components. It is important to note that setting this field **does not** guarantee a push notification will be sent, as additional factors can influence this: * To mention roles and notify their members, the role's `mentionable` field must be set to `true`, or the bot must have the `MENTION_EVERYONE` permission * To mention `@everyone` and `@here`, the bot must have the `MENTION_EVERYONE` permission * Setting the `SUPPRESS_NOTIFICATIONS` flag when sending a message will disable push notifications and only cause a notification badge * Users can customize their notification settings through the Discord app, which might cause them to only receive a notification badge and no push notification ###### Allowed Mention Types | Type | Value | Description | | ----------------- | ---------- | ------------------------------------- | | Role Mentions | "roles" | Controls role mentions | | User Mentions | "users" | Controls user mentions | | Everyone Mentions | "everyone" | Controls @everyone and @here mentions | ###### Default Settings for Allowed Mentions The default value for the `allowed_mentions` field, used when it is not passed in the body, varies depending on the context: In **regular messages**, all mention types are parsed, which is equivalent to sending the following data: ```json theme={"system"} { "parse": ["users", "roles", "everyone"] } ``` In **interactions** and **webhooks**, only user mentions are parsed, which corresponds to the following: ```json theme={"system"} { "parse": ["users"] } ``` | Field | Type | Description | | -------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | | parse? | array of allowed mention types | An array of [allowed mention types](/developers/resources/message#allowed-mentions-object-allowed-mention-types) to parse from the content | | roles? | array of snowflakes | Array of role ids to mention, max 100 | | users? | array of snowflakes | Array of user ids to mention, max 100 | | replied\_user? | boolean | For replies, whether to mention the author of the message being replied to, defaults to false | ###### Allowed Mentions Examples Because the behavior of the `allowed_mentions` field is more complex than it seems, here's a set of examples: In the following case, we are sending a regular message **without** configuring `allowed_mentions`. As a result, all included mentions will be parsed. ```json theme={"system"} { "content": "@here Hello <@&1234> and <@5678> 👋" } ``` If you want to completely suppress all mentions in the message, you can configure the `allowed_mentions` field as we've documented above: ```json theme={"system"} { "content": "@here Hello <@&1234> and <@5678> 👋", "allowed_mentions": { "parse": [] } } ``` It is important to note that the `parse` field is **mutually exclusive** with the other fields. In the example below, only the `1234` role and the `5678` user mentions would be parsed, but **not** the `@here` at the beginning. Passing a falsy value such as `null` or an empty array into the `users` field does not trigger a validation error. ```json theme={"system"} { "content": "@here Hello <@&1234> and <@5678> 👋", "allowed_mentions": { "parse": ["users", "roles"], "users": [] } } ``` In this next example, **only** `@everyone` would be parsed, as well as users `1234` and `5678` in case they suppressed `@everyone` mentions in their settings. ```json theme={"system"} { "content": "@everyone <@1234> <@5678> <@&789> 👋", "allowed_mentions": { "parse": ["everyone"], "users": ["1234", "5678"] } } ``` Due to possible ambiguities, not all configurations are accepted. Here's an example of an *invalid* configuration, because it includes both `parse` and `users`, despite those fields being mutually exclusive, causing a validation error. ```json theme={"system"} { "content": "@everyone <@1234> <@5678> <@9012> <@&200>", "allowed_mentions": { "parse": ["users"], "users": ["1234", "5678"] } } ``` Any entities whose id is included can be mentioned. Do note the API will silently ignore entities whose id are present in the `allowed_mentions` field, but not in the content of the message or its components. For example, in the following configuration, the user 123 mention would be parsed because it is present in the `content`. However, since there is no mention of user 456 in the `content`, they would not be notified. ```json theme={"system"} { "content": "<@123> Time for some memes 🤠", "allowed_mentions": { "users": ["123", "456"] } } ``` ### Role Subscription Data Object ###### Role Subscription Data Object Structure | Field | Type | Description | | ------------------------------- | --------- | --------------------------------------------------------------------- | | role\_subscription\_listing\_id | snowflake | the id of the sku and listing that the user is subscribed to | | tier\_name | string | the name of the tier that the user is subscribed to | | total\_months\_subscribed | integer | the cumulative number of months that the user has been subscribed for | | is\_renewal | boolean | whether this notification is for a renewal rather than a new purchase | ### Message Pin Object ###### Message Pin Object Struture | Field | Type | Description | | ---------- | -------------------------------------------------------------- | ------------------------------- | | pinned\_at | ISO8601 timestamp | the time the message was pinned | | message | [message](/developers/resources/message#message-object) object | the pinned message | ### Shared Client Theme Object ###### Shared Client Theme Object Struture | Field | Type | Description | | --------------- | ------------------------------------------------------------- | ------------------------------------------------------ | | colors | array of strings | the hexadecimal-encoded colors of the theme (max of 5) | | gradient\_angle | integer | the direction of the theme's colors (max of 360) | | base\_mix | integer | the intensity of the theme's colors (max of 100) | | base\_theme? | ?[base theme](/developers/resources/message#base-theme-types) | the mode of the theme | ###### Base Theme Types | Type | Value | | ---------- | ----- | | UNSET \[1] | 0 | | DARK | 1 | | LIGHT | 2 | | DARKER | 3 | | MIDNIGHT | 4 | \[1] Equivalent to the `DARK` type. ###### Example Shared Client Theme ```json theme={"system"} { "shared_client_theme": { "colors": ["5865F2", "7258F2", "9858F2", "BE58F2", "E558F2"], "gradient_angle": 0, "base_mix": 58, "base_theme": 1 } } ``` ## Get Channel Messages /channels/[\{channel.id}](/developers/resources/channel#channel-object)/messages Retrieves the messages in a channel. Returns an array of [message](/developers/resources/message#message-object) objects from newest to oldest on success. If operating on a guild channel, this endpoint requires the current user to have the `VIEW_CHANNEL` permission. If the channel is a voice channel, they must *also* have the `CONNECT` permission. If the current user is missing the `READ_MESSAGE_HISTORY` permission in the channel, then no messages will be returned. The `before`, `after`, and `around` parameters are mutually exclusive, only one may be passed at a time. ###### Query String Params | Field | Type | Description | Default | | ------- | --------- | ---------------------------------------- | ------- | | around? | snowflake | Get messages around this message ID | absent | | before? | snowflake | Get messages before this message ID | absent | | after? | snowflake | Get messages after this message ID | absent | | limit? | integer | Max number of messages to return (1-100) | 50 | ## Search Guild Messages /guilds/[\{guild.id}](/developers/resources/guild#guild-object)/messages/search Returns a list of messages without the `reactions` key that match a search query in the guild. Requires the `READ_MESSAGE_HISTORY` permission. This endpoint is restricted according to whether the `MESSAGE_CONTENT` [Privileged Intent](/developers/events/gateway#privileged-intents) is enabled for your application. If the entity you are searching is not yet indexed, the endpoint will return a 202 accepted response. The response body will not contain any search results, and will look similar to an error response: ```json theme={"system"} { "message": "Index not yet available. Try again later", "code": 110000, "documents_indexed": 0, "retry_after": 2 } ``` You should retry the request after the timeframe specified in the `retry_after` field. If the `retry_after` field is `0`, you should retry the request after a short delay. Due to speed optimizations, search may return slightly fewer results than the limit specified when messages have not been accessed for a long time. Clients should not rely on the length of the `messages` array to paginate results. Additionally, when messages are actively being created or deleted, the `total_results` field may not be accurate. ###### Query String Params | Field | Type | Description | | ------------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | limit? | integer | Max number of messages to return (1-25, default 25) | | offset? | integer | Number to offset the returned messages by (max 9975) | | max\_id? | snowflake | Get messages before this message ID | | min\_id? | snowflake | Get messages after this message ID | | slop? | integer | Max number of words to skip between matching tokens in the search `content` (max 100, default 2) | | content? | string | Filter messages by content (max 1024 characters) | | channel\_id? | [array](/developers/reference#array-query-strings) of snowflakes | Filter messages by these channels (max 500) | | author\_type? | [array](/developers/reference#array-query-strings) of strings | Filter messages by [author type](/developers/resources/message#search-guild-messages-author-types) | | author\_id? | [array](/developers/reference#array-query-strings) of snowflakes | Filter messages by these authors (max 100) | | mentions? | [array](/developers/reference#array-query-strings) of snowflakes | Filter messages that mention these users (max 100) | | mentions\_role\_id? | [array](/developers/reference#array-query-strings) of snowflakes | Filter messages that mention these roles (max 100) | | mention\_everyone? | [boolean](/developers/reference#boolean-query-strings) | Filter messages that do or do not mention @everyone | | replied\_to\_user\_id? | [array](/developers/reference#array-query-strings) of snowflakes | Filter messages that reply to these users (max 100) | | replied\_to\_message\_id? | [array](/developers/reference#array-query-strings) of snowflakes | Filter messages that reply to these messages (max 100) | | pinned? | [boolean](/developers/reference#boolean-query-strings) | Filter messages by whether they are or are not pinned | | has? | [array](/developers/reference#array-query-strings) of strings | Filter messages by whether or not they [have specific things](/developers/resources/message#search-guild-messages-search-has-types) | | embed\_type? | [array](/developers/reference#array-query-strings) of strings | Filter messages by [embed type](/developers/resources/message#search-guild-messages-search-embed-types) | | embed\_provider? | [array](/developers/reference#array-query-strings) of strings | Filter messages by embed provider (case-sensitive, e.g. `Tenor`) (max 256 characters, max 100) | | link\_hostname? | [array](/developers/reference#array-query-strings) of strings | Filter messages by link hostname (e.g. `discordapp.com`) (max 256 characters, max 100) | | attachment\_filename? | [array](/developers/reference#array-query-strings) of strings | Filter messages by attachment filename (max 1024 characters, max 100) | | attachment\_extension? | [array](/developers/reference#array-query-strings) of strings | Filter messages by attachment extension (e.g. `txt`) (max 256 characters, max 100) | | sort\_by? \[1] | string | The [sorting algorithm](/developers/resources/message#search-guild-messages-search-sort-modes) to use | | sort\_order? \[1] | string | The direction to sort (`asc` or `desc`, default `desc`) | | include\_nsfw? | [boolean](/developers/reference#boolean-query-strings) | Whether to include results from age-restricted channels (default false) | \[1] Sort order is not respected when sorting by relevance. ###### Author Types All types can be negated by prefixing them with `-`, which means results will not include messages that match the type. | Type | Description | | ------- | ------------------------------------- | | user | Return messages sent by user accounts | | bot | Return messages sent by bot accounts | | webhook | Return messages sent by webhooks | ###### Search Has Types All types can be negated by prefixing them with `-`, which means results will not include messages that match the type. | Type | Description | | -------- | --------------------------------------------- | | image | Return messages that have an image | | sound | Return messages that have a sound attachment | | video | Return messages that have a video | | file | Return messages that have an attachment | | sticker | Return messages that have a sent sticker | | embed | Return messages that have an embed | | link | Return messages that have a link | | poll | Return messages that have a poll | | snapshot | Return messages that have a forwarded message | ###### Search Embed Types These do not correspond 1:1 to actual [embed types](/developers/resources/message#embed-object-embed-types) and encompass a wider range of actual types. | Type | Description | | -------- | ------------------------------------------ | | image | Return messages that have an image embed | | video | Return messages that have a video embed | | gif \[1] | Return messages that have a gifv embed | | sound | Return messages that have a sound embed | | article | Return messages that have an article embed | \[1] Messages sent before February 24, 2026 may not be properly indexed under the `gif` embed type. ###### Search Sort Modes | Type | Description | | --------- | -------------------------------------------------------- | | timestamp | Sort by the message creation time (default) | | relevance | Sort by the relevance of the message to the search query | ###### Response Body | Field | Type | Description | | ------------------------------ | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- | | doing\_deep\_historical\_index | boolean | Whether the guild is undergoing a deep historical indexing operation | | documents\_indexed? | integer | The number of documents that have been indexed during the current index operation, if any | | total\_results | integer | The total number of results that match the query | | messages \[1] | array of array of [message](/developers/resources/message#message-object) objects | A nested array of messages that match the query | | threads? | array of [channel](/developers/resources/channel#channel-object) objects | The threads that contain the returned messages | | members? | array of [thread member](/developers/resources/channel#thread-member-object) objects | A thread member object for each returned thread the current user has joined | \[1] The nested array was used to provide surrounding context to search results. However, surrounding context is no longer returned. ## Get Channel Message /channels/[\{channel.id}](/developers/resources/channel#channel-object)/messages/[\{message.id}](/developers/resources/message#message-object) Retrieves a specific message in the channel. Returns a [message](/developers/resources/message#message-object) object on success. If operating on a guild channel, this endpoint requires the current user to have the `VIEW_CHANNEL` and `READ_MESSAGE_HISTORY` permissions. If the channel is a voice channel, they must *also* have the `CONNECT` permission. ## Create Message /channels/[\{channel.id}](/developers/resources/channel#channel-object)/messages Discord may strip certain characters from message content, like invalid unicode characters or characters which cause unexpected message formatting. If you are passing user-generated strings into message content, consider sanitizing the data to prevent unexpected behavior and using `allowed_mentions` to prevent unexpected mentions. Post a message to a guild text or DM channel. Returns a [message](/developers/resources/message#message-object) object. Fires a [Message Create](/developers/events/gateway-events#message-create) Gateway event. See [message formatting](/developers/reference#message-formatting) for more information on how to properly format messages. To create a message as a reply or forward of another message, apps can include a [`message_reference`](/developers/resources/message#message-reference-structure). Refer to the documentation for required fields. Files must be attached using a `multipart/form-data` body as described in [Uploading Files](/developers/reference#uploading-files). ###### Limitations * When operating on a guild channel, the current user must have the `SEND_MESSAGES` permission. * When sending a message with `tts` (text-to-speech) set to `true`, the current user must have the `SEND_TTS_MESSAGES` permission. * When creating a message as a reply to another message, the current user must have the `READ_MESSAGE_HISTORY` permission. * The referenced message must exist and cannot be a system message. * The maximum request size when sending a message is **25 MiB** * For the embed object, you can set every field except `type` (it will be `rich` regardless of if you try to set it), `provider`, `video`, and any `height`, `width`, or `proxy_url` values for images. ###### JSON/Form Params | Field | Type | Description | | ---------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | content?\* | string | Message contents (up to 2000 characters) | | nonce? | integer or string | Can be used to verify a message was sent (up to 25 characters). Value will appear in the [Message Create event](/developers/events/gateway-events#message-create). | | tts? | boolean | `true` if this is a TTS message | | embeds?\* | array of [embed](/developers/resources/message#embed-object) objects | Up to 10 `rich` embeds (up to 6000 characters) | | allowed\_mentions? | [allowed mention object](/developers/resources/message#allowed-mentions-object) | Allowed mentions for the message | | message\_reference?\* | [message reference](/developers/resources/message#message-reference-structure) | Include to make your message a reply or a forward | | components?\* | array of [message component](/developers/components/reference#component-object) objects | Components to include with the message | | sticker\_ids?\* | array of snowflakes | IDs of up to 3 [stickers](/developers/resources/sticker#sticker-object) in the server to send in the message | | files\[n]?\* | file contents | Contents of the file being sent. See [Uploading Files](/developers/reference#uploading-files) | | payload\_json? | string | JSON-encoded body of non-file params, only for `multipart/form-data` requests. See [Uploading Files](/developers/reference#uploading-files) | | attachments? | array of partial [attachment](/developers/resources/message#attachment-object) objects | Attachment objects with filename and description. See [Uploading Files](/developers/reference#uploading-files) | | flags?\*\* | integer | [Message flags](/developers/resources/message#message-object-message-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) (only `SUPPRESS_EMBEDS`, `SUPPRESS_NOTIFICATIONS`, `IS_VOICE_MESSAGE`, and `IS_COMPONENTS_V2` can be set) | | 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. | | poll? | [poll](/developers/resources/poll#poll-create-request-object) request object | A poll! | | shared\_client\_theme? | [shared client theme object](/developers/resources/message#shared-client-theme-object) | The custom client-side theme to share via the message | \* At least one of `content`, `embeds`, `sticker_ids`, `components`, `files[n]`, `poll`, or `shared_client_theme` is required. When forwarding a message, only `message_reference` is required. \*\* When the flag `IS_COMPONENTS_V2` is set, the message can only contain `components`. Providing `content`, `embeds`, `sticker_ids`, `files[n]`, `poll`, or `shared_client_theme` will fail with a 400 BAD REQUEST response. ###### Example Request Body (application/json) ```json theme={"system"} { "content": "Hello, World!", "tts": false, "embeds": [{ "title": "Hello, Embed!", "description": "This is an embedded message." }] } ``` Examples for file uploads are available in [Uploading Files](/developers/reference#uploading-files). ## Crosspost Message /channels/[\{channel.id}](/developers/resources/channel#channel-object)/messages/[\{message.id}](/developers/resources/message#message-object)/crosspost Crosspost a message in an Announcement Channel to following channels. This endpoint requires the `SEND_MESSAGES` permission, if the current user sent the message, or additionally the `MANAGE_MESSAGES` permission, for all other messages, to be present for the current user. Returns a [message](/developers/resources/message#message-object) object. Fires a [Message Update](/developers/events/gateway-events#message-update) Gateway event. ## Create Reaction /channels/[\{channel.id}](/developers/resources/channel#channel-object)/messages/[\{message.id}](/developers/resources/message#message-object)/reactions/[\{emoji.id}](/developers/resources/emoji#emoji-object)/@me Create a reaction for the message. This endpoint requires the `READ_MESSAGE_HISTORY` permission to be present on the current user. Additionally, if nobody else has reacted to the message using this emoji, this endpoint requires the `ADD_REACTIONS` permission to be present on the current user. Returns a 204 empty response on success. Fires a [Message Reaction Add](/developers/events/gateway-events#message-reaction-add) Gateway event. The `emoji` must be [URL Encoded](https://en.wikipedia.org/wiki/Percent-encoding) or the request will fail with `10014: Unknown Emoji`. To use custom emoji, you must encode it in the format `name:id` with the emoji name and emoji id. ## Delete Own Reaction /channels/[\{channel.id}](/developers/resources/channel#channel-object)/messages/[\{message.id}](/developers/resources/message#message-object)/reactions/[\{emoji.id}](/developers/resources/emoji#emoji-object)/@me Delete a reaction the current user has made for the message. Returns a 204 empty response on success. Fires a [Message Reaction Remove](/developers/events/gateway-events#message-reaction-remove) Gateway event. The `emoji` must be [URL Encoded](https://en.wikipedia.org/wiki/Percent-encoding) or the request will fail with `10014: Unknown Emoji`. To use custom emoji, you must encode it in the format `name:id` with the emoji name and emoji id. ## Delete User Reaction /channels/[\{channel.id}](/developers/resources/channel#channel-object)/messages/[\{message.id}](/developers/resources/message#message-object)/reactions/[\{emoji.id}](/developers/resources/emoji#emoji-object)/[\{user.id}](/developers/resources/user#user-object) Deletes another user's reaction. This endpoint requires the `MANAGE_MESSAGES` permission to be present on the current user. Returns a 204 empty response on success. Fires a [Message Reaction Remove](/developers/events/gateway-events#message-reaction-remove) Gateway event. The `emoji` must be [URL Encoded](https://en.wikipedia.org/wiki/Percent-encoding) or the request will fail with `10014: Unknown Emoji`. To use custom emoji, you must encode it in the format `name:id` with the emoji name and emoji id. ## Get Reactions /channels/[\{channel.id}](/developers/resources/channel#channel-object)/messages/[\{message.id}](/developers/resources/message#message-object)/reactions/[\{emoji.id}](/developers/resources/emoji#emoji-object) Get a list of users that reacted with this emoji. Returns an array of [user](/developers/resources/user#user-object) objects on success. The `emoji` must be [URL Encoded](https://en.wikipedia.org/wiki/Percent-encoding) or the request will fail with `10014: Unknown Emoji`. To use custom emoji, you must encode it in the format `name:id` with the emoji name and emoji id. ###### Query String Params | Field | Type | Description | Default | | ------ | --------- | ---------------------------------------------------------------------------------- | ------- | | type? | integer | The [type of reaction](/developers/resources/message#get-reactions-reaction-types) | 0 | | after? | snowflake | Get users after this user ID | absent | | limit? | integer | Max number of users to return (1-100) | 25 | ###### Reaction Types | Type | Value | | ------ | ----- | | NORMAL | 0 | | BURST | 1 | ## Delete All Reactions /channels/[\{channel.id}](/developers/resources/channel#channel-object)/messages/[\{message.id}](/developers/resources/message#message-object)/reactions Deletes all reactions on a message. This endpoint requires the `MANAGE_MESSAGES` permission to be present on the current user. Fires a [Message Reaction Remove All](/developers/events/gateway-events#message-reaction-remove-all) Gateway event. ## Delete All Reactions for Emoji /channels/[\{channel.id}](/developers/resources/channel#channel-object)/messages/[\{message.id}](/developers/resources/message#message-object)/reactions/[\{emoji.id}](/developers/resources/emoji#emoji-object) Deletes all the reactions for a given emoji on a message. This endpoint requires the `MANAGE_MESSAGES` permission to be present on the current user. Fires a [Message Reaction Remove Emoji](/developers/events/gateway-events#message-reaction-remove-emoji) Gateway event. The `emoji` must be [URL Encoded](https://en.wikipedia.org/wiki/Percent-encoding) or the request will fail with `10014: Unknown Emoji`. To use custom emoji, you must encode it in the format `name:id` with the emoji name and emoji id. ## Edit Message /channels/[\{channel.id}](/developers/resources/channel#channel-object)/messages/[\{message.id}](/developers/resources/message#message-object) Edit a previously sent message. The fields `content`, `embeds`, `flags` and `components` can be edited by the original message author. Other users can only edit `flags` and only if they have the `MANAGE_MESSAGES` permission in the corresponding channel. When specifying flags, ensure to include all previously set flags/bits in addition to ones that you are modifying. Only `flags` documented in the table below may be modified by users (unsupported flag changes are currently ignored without error). When the `content` field is edited, the arrays `mentions` and `mention_roles` and the boolean `mention_everyone` in the message object will be reconstructed from scratch based on the new content. When the message flag `IS_COMPONENTS_V2` is set, the reconstructed arrays and boolean are based on the edited content in the `components` array. The `allowed_mentions` field of the edit request controls how this happens. If there is no explicit `allowed_mentions` in the edit request, the content will be parsed with *default* allowances, that is, without regard to whether or not an `allowed_mentions` was present in the request that originally created the message. Returns a [message](/developers/resources/message#message-object) object. Fires a [Message Update](/developers/events/gateway-events#message-update) Gateway event. Refer to [Uploading Files](/developers/reference#uploading-files) for details on attachments and `multipart/form-data` requests. Any provided files will be **appended** to the message. To remove or replace files you will have to supply the `attachments` field which specifies the files to retain on the message after edit. Starting with API v10, the `attachments` array must contain all attachments that should be present after edit, including **retained and new** attachments provided in the request body. All parameters to this endpoint are optional and nullable. ###### JSON/Form Params | Field | Type | Description | | ----------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | content | string | Message contents (up to 2000 characters) | | embeds | array of [embed](/developers/resources/message#embed-object) objects | Up to 10 `rich` embeds (up to 6000 characters) | | flags\* | integer | Edit the [flags](/developers/resources/message#message-object-message-flags) of a message (`SUPPRESS_EMBEDS` and `IS_COMPONENTS_V2` only) | | allowed\_mentions | [allowed mention object](/developers/resources/message#allowed-mentions-object) | Allowed mentions for the message | | components | array of [message component](/developers/components/reference#component-object) | Components to include with the message | | files\[n] | file contents | Contents of the file being sent/edited. See [Uploading Files](/developers/reference#uploading-files) | | payload\_json | string | JSON-encoded body of non-file params (multipart/form-data only). See [Uploading Files](/developers/reference#uploading-files) | | attachments | array of [attachment](/developers/resources/message#attachment-object) objects | Attached files to keep and possible descriptions for new files. See [Uploading Files](/developers/reference#uploading-files) | \* The `SUPPRESS_EMBEDS` flag can be both set and unset, while the `IS_COMPONENTS_V2` flag can only be set. When the `IS_COMPONENTS_V2` flag is set, any of the used `content`, `embeds`, `sticker_ids`, or `poll` fields must have their values reset to empty. For `content` and `poll` this is `null`. For `embeds` and `sticker_ids` this is `[]`. Failing to do this will result in a 400 BAD REQUEST response. ## Delete Message /channels/[\{channel.id}](/developers/resources/channel#channel-object)/messages/[\{message.id}](/developers/resources/message#message-object) Delete a message. If operating on a guild channel and trying to delete a message that was not sent by the current user, this endpoint requires the `MANAGE_MESSAGES` permission. Returns a 204 empty response on success. Fires a [Message Delete](/developers/events/gateway-events#message-delete) Gateway event. This endpoint supports the `X-Audit-Log-Reason` header. ## Bulk Delete Messages /channels/[\{channel.id}](/developers/resources/channel#channel-object)/messages/bulk-delete Delete multiple messages in a single request. This endpoint can only be used on guild channels and requires the `MANAGE_MESSAGES` permission. Returns a 204 empty response on success. Fires a [Message Delete Bulk](/developers/events/gateway-events#message-delete-bulk) Gateway event. Any message IDs given that do not exist or are invalid will count towards the minimum and maximum message count (currently 2 and 100 respectively). This endpoint will not delete messages older than 2 weeks, and will fail with a 400 BAD REQUEST if any message provided is older than that or if any duplicate message IDs are provided. This endpoint supports the `X-Audit-Log-Reason` header. ###### JSON Params | Field | Type | Description | | -------- | ------------------- | ----------------------------------------- | | messages | array of snowflakes | an array of message ids to delete (2-100) | ## Get Channel Pins /channels/[\{channel.id}](/developers/resources/channel#channel-object)/messages/pins Retrieves the list of pins in a channel. Requires the `VIEW_CHANNEL` permission. If the user is missing the `READ_MESSAGE_HISTORY` permission in the channel, then no pins will be returned. ###### Query String Params | Field | Type | Description | Default | | ------- | ----------------- | ----------------------------------------- | ------- | | before? | ISO8601 timestamp | Get messages pinned before this timestamp | absent | | limit? | integer | Max number of pins to return (1-50) | 50 | ###### Response Structure | Field | Type | | --------- | -------------------------------------------------------------------------------- | | items | array of [message pin](/developers/resources/message#message-pin-object) objects | | has\_more | boolean | ###### Example If you want to get 100 pins you'd send these two requests: `GET /channels/:id/messages/pins?limit=50` `GET /channels/:id/messages/pins?limit=50&before={pins[pins.len() - 1].pinned_at}` ## Pin Message /channels/[\{channel.id}](/developers/resources/channel#channel-object)/messages/pins/[\{message.id}](/developers/resources/message#message-object) Pin a message in a channel. Requires the `PIN_MESSAGES` permission. Fires a [Channel Pins Update](/developers/events/gateway-events#channel-pins-update) Gateway event. This endpoint supports the `X-Audit-Log-Reason` header. ## Unpin Message /channels/[\{channel.id}](/developers/resources/channel#channel-object)/messages/pins/[\{message.id}](/developers/resources/message#message-object) Unpin a message in a channel. Requires the `PIN_MESSAGES` permission. Returns a 204 empty response on success. Fires a [Channel Pins Update](/developers/events/gateway-events#channel-pins-update) Gateway event. This endpoint supports the `X-Audit-Log-Reason` header. ## Get Pinned Messages (deprecated) /channels/[\{channel.id}](/developers/resources/channel#channel-object)/pins Gets the first 50 pinned messages in a channel, returning an array of [message](/developers/resources/message#message-object) objects on success. This endpoint is deprecated. Use [Get Channel Pins](/developers/resources/message#get-channel-pins) instead. ## Pin Message (deprecated) /channels/[\{channel.id}](/developers/resources/channel#channel-object)/pins/[\{message.id}](/developers/resources/message#message-object) This endpoint is deprecated. Use [Pin Message](/developers/resources/message#pin-message) instead. ## Unpin Message (deprecated) /channels/[\{channel.id}](/developers/resources/channel#channel-object)/pins/[\{message.id}](/developers/resources/message#message-object) This endpoint is deprecated. Use [Unpin Message](/developers/resources/message#unpin-message) instead.