Message Resource - Documentation

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.

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

Field	Type	Description
id	snowflake	id of the message
channel_id	snowflake	id of the channel the message was sent in
author [1]	user 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 objects	users specifically mentioned in the message
mention_roles	array of role object ids	roles specifically mentioned in this message
mention_channels? [3]	array of channel mention objects	channels specifically mentioned in this message
attachments [2]	array of attachment objects	any attached files
embeds [2]	array of embed objects	any embedded content
reactions?	array of reaction 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
activity?	message activity object	sent with Rich Presence-related chat embeds
application?	partial application object	sent with Rich Presence-related chat embeds
application_id?	snowflake	if the message is an Interaction or application-owned webhook, this is the id of the application
flags?	integer	message flags combined as a bitfield
message_reference?	message reference object	data showing the source of a crosspost, channel follow add, pin, or reply message
message_snapshots? [5]	array of message snapshot 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	the message associated with the message_reference
interaction_metadata?	message interaction metadata object	Sent if the message is sent as a result of an interaction
interaction?	message interaction object	Deprecated in favor of `interaction_metadata`; sent if the message is a response to an interaction
thread?	channel object	the thread that was started from this message, includes thread member object
components? [2]	array of message components	sent if the message contains components like buttons, action rows, or other interactive components
sticker_items?	array of message sticker item objects	sent if the message contains stickers
stickers?	array of sticker 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 object	data of the role subscription purchase or renewal that prompted this ROLE_SUBSCRIPTION_PURCHASE message
resolved?	resolved data	data for users, members, channels, and roles in the message’s auto-populated select menus
poll? [2]	poll object	A poll!
call?	message call object	the call associated with 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). [3] Not all channel mentions in a message will appear in mention_channels. Only textual channels that are visible to everyone in a lurkable 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

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
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-driven messages

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

Example 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
}

Example Crossposted 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": [],
  "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, Message Component Interaction Metadata, or Modal Submit Interaction Metadata.

Application Command Interaction Metadata Structure

Field	Type	Description
id	snowflake	ID of the interaction
type	interaction type	Type of interaction
user	user object	User who triggered the interaction
authorizing_integration_owners	dictionary with keys of application integration types	IDs for installation context(s) related to an interaction. Details in Authorizing Integration Owners Object
original_response_message_id?	snowflake	ID of the original response message, present only on follow-up messages
target_user?	user object	The user the command was run on, present only on user command interactions
target_message_id?	snowflake	The ID of the message the command was run on, present only on message command 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	Type of interaction
user	user object	User who triggered the interaction
authorizing_integration_owners	dictionary with keys of application integration types	IDs for installation context(s) related to an interaction. Details in Authorizing Integration Owners Object
original_response_message_id?	snowflake	ID of the original response message, present only on follow-up messages
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	Type of interaction
user	user object	User who triggered the interaction
authorizing_integration_owners	dictionary with keys of application integration types	IDs for installation context(s) related to an interaction. Details in Authorizing Integration Owners Object
original_response_message_id?	snowflake	ID of the original response message, present only on follow-up messages
triggering_interaction_metadata	Application Command Interaction Metadata or Message Component Interaction Metadata 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 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.
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 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

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, the message will have 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 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 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
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 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 (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 object	footer information
image?	embed image object	image information
thumbnail?	embed thumbnail object	thumbnail information
video?	embed video object	video information
provider?	embed provider object	provider information
author?	embed author object	author information
fields?	array of embed field objects	fields information, max of 25

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

Embed Thumbnail Structure

Field	Type	Description
url	string	source url of thumbnail (only supports http(s) and attachments)
proxy_url?	string	a proxied url of the thumbnail
height?	integer	height of thumbnail
width?	integer	width of thumbnail

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

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

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 objects
field.name	256 characters
field.value	1024 characters
footer.text	2048 characters
author.name	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 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 for the file (max 1024 characters)
content_type?	string	the attachment’s 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)
width?	?integer	width of file (if image)
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 combined as a bitfield

* 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_REMIX	`1 << 2`	this attachment has been edited using the remix feature on mobile

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

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

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

{
  "parse": ["users"]
} 

Field	Type	Description
parse?	array of allowed mention types	An array of 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.

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

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 object	the pinned message

Get Channel Messages

GET/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.

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

Get Channel Message

GET/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.

Create Message

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

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.
tts?	boolean	`true` if this is a TTS message
embeds?*	array of embed objects	Up to 10 `rich` embeds (up to 6000 characters)
allowed_mentions?	allowed mention object	Allowed mentions for the message
message_reference?*	message reference	Include to make your message a reply or a forward
components?*	array of message component objects	Components to include with the message
sticker_ids?*	array of snowflakes	IDs of up to 3 stickers in the server to send in the message
files[n]?*	file contents	Contents of the file being sent. See Uploading Files
payload_json?	string	JSON-encoded body of non-file params, only for `multipart/form-data` requests. See Uploading Files
attachments?	array of partial attachment objects	Attachment objects with filename and description. See Uploading Files
flags?**	integer	Message flags combined as a bitfield (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 request object	A poll!

* At least one of content, embeds, sticker_ids, components, files[n], or poll 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], or poll will fail with a 400 BAD REQUEST response.

Example Request Body (application/json)

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

Examples for file uploads are available in Uploading Files.

Crosspost Message

POST/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.

Create Reaction

PUT/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.

Delete Own Reaction

DELETE/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.

Delete User Reaction

DELETE/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.

Get Reactions

GET/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.

Query String Params

Field	Type	Description	Default
type?	integer	The type of reaction	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

DELETE/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.

Delete All Reactions for Emoji

DELETE/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.

Edit Message

PATCH/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.

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 objects	Up to 10 `rich` embeds (up to 6000 characters)
flags*	integer	Edit the flags of a message (`SUPPRESS_EMBEDS` and `IS_COMPONENTS_V2` only)
allowed_mentions	allowed mention object	Allowed mentions for the message
components	array of message component	Components to include with the message
files[n]	file contents	Contents of the file being sent/edited. See Uploading Files
payload_json	string	JSON-encoded body of non-file params (multipart/form-data only). See Uploading Files
attachments	array of attachment objects	Attached files to keep and possible descriptions for new files. See 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

DELETE/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.

This endpoint supports the X-Audit-Log-Reason header.

Bulk Delete Messages

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

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

GET/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.

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

PUT/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.

This endpoint supports the X-Audit-Log-Reason header.

Unpin Message

DELETE/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.

This endpoint supports the X-Audit-Log-Reason header.

Get Pinned Messages (deprecated)

GET/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.

Pin Message (deprecated)

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

This endpoint is deprecated. Use Pin Message instead.

Unpin Message (deprecated)

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

This endpoint is deprecated. Use Unpin Message instead.

Home

Quick Start

Interactions

Components

Activities

Discord Social SDK

Rich Presence

Monetization

Discovery

Events

Developer Tools

Resources

Topics

Tutorials

Policies and Agreements

​Message Object

Message Structure

Message Types

Message Activity Structure

Message Activity Types

Message Flags

Example Message

Example Crossposted Message

​Message Interaction Metadata Object

Application Command Interaction Metadata Structure

Message Component Interaction Metadata Structure

Modal Submit Interaction Metadata Structure

​Message Call Object

Message Call Object Structure

​Message Reference Object

​Message Reference Structure

​Message Reference Types

​Message Reference Content Attribution

Crosspost messages

Channel Follow Add messages

Pin messages

Forwards

Replies

Thread Created messages

Thread starter messages

Poll result messages

Context Menu Command messages

​Voice Messages

​Message Snapshot Object

​Message Snapshot Structure

​Reaction Object

Reaction Structure

​Reaction Count Details Object

Reaction Count Details Structure

​Embed Object

Embed Structure

Embed Types

Embed Thumbnail Structure

Embed Video Structure

Embed Image Structure

Embed Provider Structure

Embed Author Structure

Embed Footer Structure

Embed Field Structure

Embed Limits

​Embed Fields by Embed Type

Poll Result Embed Fields

​Attachment Object

Attachment Structure

Attachment Flags

​Channel Mention Object

Channel Mention Structure

​Allowed Mentions Object

Allowed Mention Types

Default Settings for Allowed Mentions

Allowed Mentions Examples

​Role Subscription Data Object

Role Subscription Data Object Structure

​Message Pin Object

Message Pin Object Struture

​Get Channel Messages

Query String Params

​Get Channel Message

​Create Message

Limitations

Message Object

Message Interaction Metadata Object

Message Call Object

Message Reference Object

Message Reference Structure

Message Reference Types

Message Reference Content Attribution

Voice Messages

Message Snapshot Object

Message Snapshot Structure

Reaction Object

Reaction Count Details Object

Embed Object

Embed Fields by Embed Type

Attachment Object

Channel Mention Object

Allowed Mentions Object

Role Subscription Data Object

Message Pin Object

Get Channel Messages

Get Channel Message

Create Message

Crosspost Message

Create Reaction

Delete Own Reaction

Delete User Reaction

Get Reactions

Delete All Reactions

Delete All Reactions for Emoji

Edit Message

Delete Message

Bulk Delete Messages

Get Channel Pins

Pin Message

Unpin Message

Get Pinned Messages (deprecated)

Pin Message (deprecated)

Unpin Message (deprecated)