Message

Messages are the core unit of communication in Discord. They can contain text, embeds, attachments, reactions, and interactive components.

Message object

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

Message structure

snowflake

required

ID of the message

channel_id

snowflake

required

ID of the channel the message was sent in

author

user object

required

The author of this message. Not guaranteed to be a valid user — if the message is generated by a webhook, the author object corresponds to the webhook’s id, username, and avatar.

content

string

required

Contents of the message

timestamp

ISO8601 timestamp

required

When this message was sent

edited_timestamp

?ISO8601 timestamp

required

When this message was edited (or null if never)

tts

boolean

required

Whether this was a TTS message

mention_everyone

boolean

required

Whether this message mentions everyone

mentions

array of user objects

required

Users specifically mentioned in the message

mention_roles

array of role object ids

required

Roles specifically mentioned in this message

mention_channels

array of channel mention objects

Channels specifically mentioned in this message. Only textual channels visible to everyone in a public guild will ever be included. Only crossposted messages currently include mention_channels.

attachments

array of attachment objects

required

Any attached files

embeds

array of embed objects

required

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

required

Whether this message is pinned

webhook_id

snowflake

If the message is generated by a webhook, this is the webhook’s id

type

integer

required

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

array of message snapshot objects

The message associated with the message_reference. A minimal subset of fields in a message (e.g. author is excluded).

referenced_message

?message object

The message associated with the message_reference. Only returned for messages with a type of REPLY (19), THREAD_STARTER_MESSAGE (21), or CONTEXT_MENU_COMMAND (23).

interaction_metadata

message interaction metadata object

Sent if the message is sent as a result of an interaction

thread

channel object

The thread that was started from this message, includes thread member object

components

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

position

integer

A generally increasing integer that represents the approximate position of the message in a thread

role_subscription_data

role subscription data object

Data of the role subscription purchase or renewal that prompted this ROLE_SUBSCRIPTION_PURCHASE message

poll

poll object

A poll

call

message call object

The call associated with the 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
}

Message types

Types 19 and 20 are only available in API v8 and above. In v6, they are represented as type 0. 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
`STAGE_START`	27	true
`STAGE_END`	28	true
`STAGE_SPEAKER`	29	true
`STAGE_TOPIC`	31	true
`GUILD_APPLICATION_PREMIUM_SUBSCRIPTION`	32	true
`POLL_RESULT`	46	true

* Can only be deleted by members with MANAGE_MESSAGES permission.

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 set, cannot be removed.

Message reference object

Message reference structure

type

integer

Type of reference. Defaults to DEFAULT if unset.

message_id

snowflake

ID of the originating message

channel_id

snowflake

ID of the originating message’s channel. Optional when creating a reply; required for forwards.

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 message. Default true.

Message reference types

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

Embed object

Embed structure

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 limits

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

The combined sum of characters in all title, description, field.name, field.value, footer.text, and author.name fields across all embeds must not exceed 6000 characters.

Attachment object

Attachment structure

snowflake

required

Attachment id

filename

string

required

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

required

Size of file in bytes

url

string

required

Source URL of file

proxy_url

string

required

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. Ephemeral attachments will automatically be removed after a set period of time.

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

Attachment flags

Flag	Value	Description
`IS_REMIX`	`1 << 2`	This attachment has been edited using the remix feature on mobile

Reaction object

Reaction structure

count

integer

required

Total number of times this emoji has been used to react (including super reacts)

count_details

object

required

Reaction count details object

boolean

required

Whether the current user reacted using this emoji

me_burst

boolean

required

Whether the current user super-reacted using this emoji

emoji

partial emoji object

required

Emoji information

burst_colors

array

required

HEX colors used for super reaction

Allowed mentions object

The allowed_mentions field lets you determine whether users will receive notifications when you include mentions in the message content.

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

Allowed mentions structure

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

The parse field is mutually exclusive with the roles and users fields. You cannot use both parse: ["users"] and users: [...] in the same request.

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.

The before, after, and around parameters are mutually exclusive, only one may be passed at a time.

Query string params

around

snowflake

Get messages around this message ID

before

snowflake

Get messages before this message ID

after

snowflake

Get messages after this message ID

limit

integer

default:"50"

Max number of messages to return (1-100)

Get channel message

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

Retrieves a specific message in the channel. Returns a message object on success.

Create message

POST /channels/{channel.id}/messages

Post a message to a guild text or DM channel. Returns a message object. Fires a Message Create Gateway event.

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.

Limitations

When operating on a guild channel, the current user must have the SEND_MESSAGES permission.
When sending a message with tts set to true, the current user must have the SEND_TTS_MESSAGES permission.
The maximum request size when sending a message is 25 MiB.

JSON/form params

content

string

Message contents (up to 2000 characters). At least one of content, embeds, sticker_ids, components, files[n], poll, or shared_client_theme is required.

nonce

integer or string

Can be used to verify a message was sent (up to 25 characters)

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 object

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

attachments

array of partial attachment objects

Attachment objects with filename and description

flags

integer

Message flags; 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

poll

poll request object

A poll

Example request body

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

Crosspost message

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

Crosspost a message in an Announcement Channel to following channels. Requires SEND_MESSAGES permission if the current user sent the message, or MANAGE_MESSAGES for all other messages.

Create reaction

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

Create a reaction for the message. Requires READ_MESSAGE_HISTORY permission. Additionally, if nobody else has reacted to the message using this emoji, this endpoint requires ADD_REACTIONS permission. Returns a 204 empty response on success. The emoji must be URL Encoded or the request will fail with 10014: Unknown Emoji. To use custom emoji, encode it in the format name:id.

Delete own reaction

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

Delete a reaction the current user has made for the message. Returns a 204 empty response on success.

Delete user reaction

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

Deletes another user’s reaction. Requires the MANAGE_MESSAGES permission.

Search guild messages

GET /guilds/{guild.id}/messages/search

Returns a list of messages 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 is enabled for your application.

Query string params

content

string

Filter messages by content (max 1024 characters)

channel_id

array of snowflakes

Filter messages by these channels (max 500)

author_id

array of snowflakes

Filter messages by these authors (max 100)

mentions

array of snowflakes

Filter messages that mention these users (max 100)

pinned

boolean

Filter messages by whether they are or are not pinned

has

array of strings

Filter messages by whether or not they have specific things (image, sound, video, file, sticker, embed, link, poll, snapshot)

sort_by

string

The sorting algorithm to use: timestamp (default) or relevance

sort_order

string

default:"desc"

The direction to sort: asc or desc

limit

integer

default:"25"

Max number of messages to return (1-25)

offset

integer

Number to offset the returned messages by (max 9975)

Core Reference

Resources

Events & Gateway

Monetization Resources

Voice & RPC

Message object

Message structure

Example message

Message types

Message flags

Message reference object

Message reference structure

Message reference types

Embed object

Embed structure

Embed types

Embed limits

Attachment object

Attachment structure

Attachment flags

Reaction object

Reaction structure

Allowed mentions object

Allowed mention types

Allowed mentions structure

Get channel messages

Query string params

Get channel message

Create message

Limitations

JSON/form params

Example request body

Crosspost message

Create reaction

Delete own reaction

Delete user reaction

Search guild messages

Query string params

Core Reference

Resources

Events & Gateway

Monetization Resources

Voice & RPC

​Message object

​Message structure

​Example message

​Message types

​Message flags

​Message reference object

​Message reference structure

​Message reference types

​Embed object

​Embed structure

​Embed types

​Embed limits

​Attachment object

​Attachment structure

​Attachment flags

​Reaction object

​Reaction structure

​Allowed mentions object

​Allowed mention types

​Allowed mentions structure

​Get channel messages

​Query string params

​Get channel message

​Create message

​Limitations

​JSON/form params

​Example request body

​Crosspost message

​Create reaction

​Delete own reaction

​Delete user reaction

​Search guild messages

​Query string params

Message object

Message structure

Example message

Message types

Message flags

Message reference object

Message reference structure

Message reference types

Embed object

Embed structure

Embed types

Embed limits

Attachment object

Attachment structure

Attachment flags

Reaction object

Reaction structure

Allowed mentions object

Allowed mention types

Allowed mentions structure

Get channel messages

Query string params

Get channel message

Create message

Limitations

JSON/form params

Example request body

Crosspost message

Create reaction

Delete own reaction

Delete user reaction

Search guild messages

Query string params