Message Resource

Represents a message sent in a channel within Discord.

[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).

[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

* Can only be deleted by members with MANAGE_MESSAGES permission

* Once a message has been sent with this flag, it can't be removed from that message.

{
  "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
}

{
  "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"
  }
}

Metadata about the interaction, including the source of the interaction and relevant server and user IDs.

One of Application Command Interaction Metadata, Message Component Interaction Metadata, or Modal Submit Interaction Metadata.

Information about the call in a private channel.

* 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.

Determines how associated data is populated.

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 references are generic attribution on a message. There are multiple message types that have a message_reference object.

• 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.

• 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.

• 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.

• These are messages which capture a snapshot of a message.
• These messages have an array of message_snapshot 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

• 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.

• 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.

• 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.

• 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

• These are messages sent when a user uses a context menu Application Command. (type 23)
• If the command was a message command, 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 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 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.

* The current subset of message fields consists of: type, content, embeds, attachments, timestamp, edited_timestamp, flags, mentions, mention_roles, stickers, sticker_items, and components.

The reaction count details object contains a breakdown of normal and super reaction counts for the associated emoji.

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

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.

Certain embed types are used to power special UIs. These embeds use fields to include additional data in key-value pairs. Below is a reference of possible embed fields for each of the following embed types.

* 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.

This structure is used in Message Create and Edit requests to set which attachments are in the message and provide their metadata.

When editing, you must provide the id of each file to keep, and you can optionally update the description and is_spoiler fields of existing attachments.

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

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:

{
  "parse": ["users", "roles", "everyone"]
}

In interactions and webhooks, only user mentions are parsed, which corresponds to the following:

{
  "parse": ["users"]
}

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.

{
  "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:

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "content": "<@123> Time for some memes 🤠",
  "allowed_mentions": {
    "users": ["123", "456"]
  }
}

[1] Equivalent to the DARK type.

{
  "shared_client_theme": {
    "colors": ["5865F2", "7258F2", "9858F2", "BE58F2", "E558F2"],
    "gradient_angle": 0,
    "base_mix": 58,
    "base_theme": 1
  }
}

/channels/{channel.id}/messages

Retrieves the messages in a channel. Returns an array of message 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.

/guilds/{guild.id}/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.

[1] Sort order is not respected when sorting by relevance.

All types can be negated by prefixing them with -, which means results will not include messages that match the type.

All types can be negated by prefixing them with -, which means results will not include messages that match the type.

These do not correspond 1:1 to actual embed types and encompass a wider range of actual types.

[1] Messages sent before February 24, 2026 may not be properly indexed under the gif embed type.

[1] The nested array was used to provide surrounding context to search results. However, surrounding context is no longer returned.

/channels/{channel.id}/messages/{message.id}

Retrieves a specific message in the channel. Returns a message 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.

/channels/{channel.id}/messages

Post a message to a guild text or DM channel. Returns a message object. Fires a Message Create Gateway event. See 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. Refer to the documentation for required fields.

Files must be attached using a multipart/form-data body as described in Uploading Files.

• 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.

* 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, poll, or shared_client_theme will fail with a 400 BAD REQUEST response.

{
  "content": "Hello, World!",
  "tts": false,
  "embeds": [{
    "title": "Hello, Embed!",
    "description": "This is an embedded message."
  }]
}

Examples for file uploads are available in Uploading Files.

/channels/{channel.id}/messages/{message.id}/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 object. Fires a Message Update Gateway event.

/channels/{channel.id}/messages/{message.id}/reactions/{emoji.id}/@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 Gateway event. The emoji must be URL Encoded 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.

/channels/{channel.id}/messages/{message.id}/reactions/{emoji.id}/@me

Delete a reaction the current user has made for the message. Returns a 204 empty response on success. Fires a Message Reaction Remove Gateway event. The emoji must be URL Encoded 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.

/channels/{channel.id}/messages/{message.id}/reactions/{emoji.id}/{user.id}

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 Gateway event. The emoji must be URL Encoded 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.

/channels/{channel.id}/messages/{message.id}/reactions/{emoji.id}

Get a list of users that reacted with this emoji. Returns an array of user objects on success. The emoji must be URL Encoded 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.

/channels/{channel.id}/messages/{message.id}/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 Gateway event.

/channels/{channel.id}/messages/{message.id}/reactions/{emoji.id}

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 Gateway event. The emoji must be URL Encoded 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.

/channels/{channel.id}/messages/{message.id}

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 object. Fires a Message Update Gateway event.

Refer to 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.

* 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.

/channels/{channel.id}/messages/{message.id}

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 Gateway event.

/channels/{channel.id}/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 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).

/channels/{channel.id}/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.

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}

/channels/{channel.id}/messages/pins/{message.id}

Pin a message in a channel. Requires the PIN_MESSAGES permission. Fires a Channel Pins Update Gateway event.

/channels/{channel.id}/messages/pins/{message.id}

Unpin a message in a channel. Requires the PIN_MESSAGES permission. Returns a 204 empty response on success. Fires a Channel Pins Update Gateway event.

/channels/{channel.id}/pins

Gets the first 50 pinned messages in a channel, returning an array of message objects on success. This endpoint is deprecated. Use Get Channel Pins instead.

/channels/{channel.id}/pins/{message.id}

This endpoint is deprecated. Use Pin Message instead.

/channels/{channel.id}/pins/{message.id}

This endpoint is deprecated. Use Unpin Message instead.