Message Resource

Messages are the core of Discord. They are the primary way users communicate with each other, and they can contain text, images, and other media. Embeddable content, such as polls, system messages, and calls are also represented as messages.

A message sent in a channel within Discord.

¹ The author object follows the structure of the user object, but may not be a valid user in the case where the message is generated by a webhook; you can recognize this by checking for the webhook_id key on the message object. In these cases, the below notice about the additional member keys does not apply as webhooks are not guild members.

² Users must configure (or, in the case of bots, be approved for) the MESSAGE_CONTENT intent to receive non-empty values for these fields in most situations.

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

⁴ See the message reference types for more information on which message references have which fields.

⁵ Only returned for messages with a type of REPLY or THREAD_STARTER_MESSAGE. If the message is a reply 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.

¹ Can only be deleted by members with the MANAGE_MESSAGES permission.

The type of rendered message is determined via converting the message's timestamp to a unix timestamp with millisecond precision, modulo 13.

{
  "id": "1076229630052270231",
  "type": 0,
  "content": "guh",
  "channel_id": "1029316811088478299",
  "author": {
    "id": "545581357812678656",
    "username": "alien",
    "global_name": "Alien",
    "avatar": "60387de43133809b083fb0f7458d2708",
    "avatar_decoration_data": null,
    "discriminator": "0",
    "public_flags": 4194432
  },
  "attachments": [],
  "embeds": [],
  "mentions": [],
  "mention_roles": [],
  "pinned": false,
  "mention_everyone": false,
  "tts": false,
  "timestamp": "2023-02-17T19:52:19.184000+00:00",
  "edited_timestamp": null,
  "flags": 0,
  "components": [],
  "reactions": [
    {
      "emoji": { "id": null, "name": "‼️" },
      "count": 2,
      "count_details": { "burst": 0, "normal": 82 },
      "burst_colors": ["#f0ca59", "#4c704f", "#e07f45", "#f0ae59", "#f0bc59", "#f0a059", "#e08e45", "#f0984a"],
      "me_burst": false,
      "me": false
    }
  ]
}

{
  "id": "1076589465084104805",
  "type": 0,
  "content": "test",
  "channel_id": "909072028911423498",
  "author": {
    "bot": true,
    "id": "999498190359371866",
    "username": "Testing Server #News",
    "avatar": "47b30f67c7e2c15637936cd180dd681c",
    "discriminator": "0000"
  },
  "attachments": [],
  "embeds": [],
  "mentions": [],
  "mention_roles": [],
  "pinned": false,
  "mention_everyone": false,
  "tts": false,
  "timestamp": "2023-02-18T19:42:10.541000+00:00",
  "edited_timestamp": null,
  "flags": 2,
  "components": [],
  "webhook_id": "999498190359371866",
  "message_reference": {
    "type": 0,
    "channel_id": "901900332408381450",
    "guild_id": "901900332408381449",
    "message_id": "1076589456297054320"
  }
}

A rich presence invite in a message.

¹ This field is send-only.

A call in a private channel.

¹ This is a best-effort marker and may be unexpectedly null in some cases.

Metadata about the interaction, including the source of the interaction and the relevant guild and users.

A role subscription purchase or renewal.

A guild product purchase notification.

Determines the type of purchase notification.

Information on a gift that prompted a message. The relevant gift link is provided in the first embed of the message.

¹ The emoji name and id fields are user-provided and not guaranteed to be valid or accurate. The animated field is never present.

A reference to an originating (replied to) message.

Message references are generic attribution on a message. There are multiple message types that have a message_reference object.

¹ Optional when creating a reply, but will always be present when receiving this object. In future API versions this will become a required field.

² This field is send-only.

³ Only applicable to FORWARD type references.

Determines how associated data is populated.

¹ This can only be used for basic messages, i.e., messages which do not have strong bindings to a non-global entity. Thus it only supports messages with DEFAULT or REPLY types, without any polls, calls, or components. This is subject to change in the future.

A snapshot of a partial message at a point in time.

¹ Users must configure (or, in the case of bots, be approved for) the MESSAGE_CONTENT intent to receive non-empty values for these fields in most situations.

{
  "message": {
    "channel_id": "1029316811088478299",
    "content": "guh",
    "timestamp": "2023-02-17T19:52:19.184000+00:00",
    "edited_timestamp": null,
    "attachments": [],
    "embeds": [],
    "type": 0,
    "flags": 0,
    "components": []
  }
}

There are multiple message types that have a message_reference object. Since message references are generic attribution to a previous message, there will be more types of messages which have this information in the future.

• These are messages that originated from another channel (IS_CROSSPOST flag).
• These messages have all three fields, with data of the original message that was crossposted.

• These are messages which capture a snapshot of a message, preventing spoofing or tampering.
• These messages have an array of message_snapshots field 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.
• A forwarded message can be identified by looking at it's message_reference.type field.
  • Message snapshots will be the message data associated with the forward. Currently only 1 snapshot is supported.
  • Message snapshots are taken at moment the forward message is created, and are immutable; any mutations to the orignal message will not be propagated.
• Forwards are created by including a message_reference of a FORWARD type when sending a message. When sending, type, message_id, and channel_id are required, and the requester must have VIEW_CHANNEL permissions.
• You can opt to only include specific attachments and embed in the forward by including the forward_only field in the message_reference.

• 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, with data of 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, with data of the message that was pinned.

• 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, with data of 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 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, with data of 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 will never have content, embeds, or attachments, mainly just the message_reference and referenced_message fields.

Voice messages are messages with the VOICE_MESSAGE flag. They have the following properties:

• They cannot be edited.
• Only a single audio attachment is allowed. No other attachments, content, embeds, stickers, etc.
• The attachment has the additional fields duration_secs and waveform.

The waveform is intended to be a preview of the entire voice message, with 1 byte per datapoint encoded in base64. Official clients sample the recording at most once per 100 milliseconds, but will downsample so that no more than 256 datapoints are in the waveform.

Official clients upload a 1 channel, 48000 Hz, 32 kbps Opus stream in an OGG container. The encoding and waveform details are an implementation detail and may change without warning.

Clips are a special type of attachment that can be sent with a message. They are created by recording a stream and then clipping a portion of the recording.

Clip attachments have the CLIP flag set, and have the additional fields clip_created_at, clip_participants, and optionally title and application.

An attachment can be sent as a clip by specifying the is_clip, clip_created_at, and clip_participant_ids fields, and optionally the title and application_id fields. For an attachment to be a valid clip, it must have a UUID appended to the end of the file in binary format. An example in hexadecimal format is 75 75 69 64 A1 C8 52 99 33 46 4D B8 88 F0 83 F5 7A 75 A5 EF. This can be done with the following pseudocode:

import uuid

with open("cat.mp4", "r+b") as file:
    file.seek(0, 2)
    file.write(b"uuid")
    file.write(uuid.uuid4().bytes)

Most embed types are "loosely defined" and, for the most part, are not used by our clients for rendering. Embed attributes power what is rendered.

¹ These embed types are system-generated and cannot be sent by users. Their fields array represents the object linked in the description as a list of key-value pairs.

² This embed type is used to signal to the client to render a preview of the linked media channel post. This embed is created for URLs that link to a media channel post if the channel is a paywalled role subscription benefit. The URL is always in the format https://discord.com/channels/:guild_id/:parent_id/threads/:thread_id/:initial_message_id.

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

² These fields are received only and cannot be set.

³ This field is send-only. See uploading to Google Cloud for more information.

⁴ The proxy URL only supports attachments with a defined width and height, such as images and videos. For all other attachments, the proxy returns a 415 unsupported media type error.

⁵ The flags field is received only and cannot be set directly. To set flags, use the is_clip, is_thumbnail, and is_remix send-only fields.

⁶ When sending a clip, is_clip, clip_created_at, and clip_participant_ids are required. See message types for more information.

⁷ The clip_participant_ids and application_id fields are send-only. You will receive the clip_participants and application fields back when retrieving the message.

The allowed mention field allows for more granular control over mentions without various hacks to the message content. This will always validate against message content to avoid phantom pings (e.g. to ping everyone, you must still have @everyone in the message content), and check against user permissions.

Due to the complexity of possibilities, we have included a set of examples and behavior for the allowed mentions field.

If allowed_mentions is not passed in (i.e. the key does not exist), the mentions will be parsed via the content. This corresponds with existing behavior.

In the example below we would ping @here (and also @role124 and @user123)

{
  "content": "@here Hi there from <@123>, cc <@&124>"
}

To suppress all mentions in a message use:

{
  "content": "@everyone hi there, <@&123>",
  "allowed_mentions": {
    "parse": []
  }
}

This will suppress all mentions in the message (no @everyone or user mention).

The parse field is mutually exclusive with the other fields. In the example below, we would ping users 123 and role 124, but not @everyone. Note that passing a falsy value ([], null) into the users field does not trigger a validation error.

{
  "content": "@everyone <@123> <@&124>",
  "allowed_mentions": {
    "parse": ["users", "roles"],
    "users": []
  }
}

In the next example, we would ping @everyone, (and also users 123 and 124 if they suppressed @everyone mentions), but we would not ping any roles.

{
  "content": "@everyone <@123> <@124> <@125> <@&200>",
  "allowed_mentions": {
    "parse": ["everyone"],
    "users": ["123", "124"]
  }
}

Due to possible ambiguities, not all configurations are valid. An invalid configuration is as follows

{
  "content": "@everyone <@123> <@124> <@125> <@&200>",
  "allowed_mentions": {
    "parse": ["users"],
    "users": ["123", "124"]
  }
}

Because parse: ["users"] and users: ["123", "124"] are both present, we would throw a validation error. This is because the conditions cannot be fulfilled simultaneously (they are mutually exclusive).

Any entities with an ID included in the list of IDs can be mentioned. Note that the IDs of entities not present in the message's content will simply be ignored. e.g. The following example is valid, and would mention user 123, but not user 125 since there is no mention of user 125 in the content.

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

The poll object has a lot of levels and nested structures. It was also designed to support future extensibility, so some fields may appear to be more complex than necessary.

¹ Only text is supported.

² expiry is marked as nullable to support non-expiring polls in the future, but all polls have an expiry currently.

This is the request object used when creating a poll across the different endpoints. It is similar but not exactly identical to the main poll object. The main difference is that the request has duration which eventually becomes expiry.

¹ Only text is supported.

Different layouts for polls will come in the future. For now though, this value will always be DEFAULT.

The poll media object is a common object that backs both the question and answers. For now, question only supports text, while answers can have an optional emoji.

¹ text should always be non-null for both questions and answers, but please do not depend on that in the future.

² When creating a poll answer with an emoji, one only needs to send either the id (custom emoji) or name (default emoji) as the only field.

The answer_id is a number that labels each answer. As an implementation detail, it currently starts at 1 for the first answer and goes up sequentially. We recommend against depending on this sequence.

Currently, there is a maximum of 10 answers per poll.

¹ When sending, this field is optional.

In a nutshell, this contains the number of votes for each answer. The results field may be not present in certain responses where, as an implementation detail, Discord does not fetch the poll results in the backend. This should be treated as "unknown results", as opposed to "no results". You can keep using the results if you have previously received them through other means. Due to the intricacies of counting at scale, while a poll is in progress the results may not be perfectly accurate. They usually are accurate, and shouldn't deviate significantly—it's just difficult to make guarantees. To compensate for this, after a poll is finished there is a background job which performs a final, accurate tally of votes. This tally concludes once is_finalized is true. Polls that have ended will also always contain results. If answer_counts does not contain an entry for a particular answer, then there are no votes for that answer.

{
  "question": {
    "text": "Aliens?"
  },
  "answers": [
    {
      "answer_id": 1,
      "poll_media": {
        "text": "Alien"
      }
    },
    {
      "answer_id": 2,
      "poll_media": {
        "text": "Alien 2",
        "emoji": {
          "id": null,
          "name": "👽"
        }
      }
    },
    {
      "answer_id": 3,
      "poll_media": {
        "text": "Alien 3",
        "emoji": {
          "id": "1120790948302033046",
          "name": "meowlien"
        }
      }
    }
  ],
  "expiry": "2024-05-02T10:00:02.039342+00:00",
  "allow_multiselect": true,
  "layout_type": 1,
  "results": {
    "answer_counts": [
      {
        "id": 1,
        "count": 1,
        "me_voted": false
      }
    ],
    "is_finalized": false
  }
}

Returns an array of message objects in the channel. Requires the VIEW_CHANNEL permission if operating on a guild channel. If the current user is missing the READ_MESSAGE_HISTORY permission in the channel then this will return no messages (since they cannot read the message history).

Returns messages without the reactions key that match a search query in the guild or channel. The messages that are direct results will have an extra hit key set to true. Requires the READ_MESSAGE_HISTORY permission if operating on a guild channel.

¹ Not applicable when using the GET /channels/{channel.id}/messages/search endpoint.

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.

¹ Surrounding context messages are no longer returned.

{
  "total_results": 1,
  "messages": [
    [
      {
        "id": "1076986676557131916",
        "type": 0,
        "content": "domainreaction fear",
        "channel_id": "885895521909227581",
        "author": {
          "id": "545581357812678656",
          "username": "alien",
          "global_name": "Alien",
          "avatar": "60387de43133809b083fb0f7458d2708",
          "avatar_decoration_data": null,
          "discriminator": "0",
          "public_flags": 4194432
        },
        "attachments": [],
        "embeds": [],
        "mentions": [],
        "mention_roles": [],
        "pinned": false,
        "mention_everyone": false,
        "tts": false,
        "timestamp": "2023-02-19T22:00:33.136000+00:00",
        "edited_timestamp": null,
        "flags": 0,
        "components": [],
        "hit": true
      }
    ]
  ],
  "analytics_id": "largealienalphanumericstring"
}

Returns a specific message object in the channel. Requires the READ_MESSAGE_HISTORY permission if operating on a guild channel.

Posts a message to a text-based channel. Returns a message object on success. 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 to another message, you can include a message_reference with a message_id. The channel_id and guild_id in the message_reference are optional, but will be validated if provided.

Files must be attached using a multipart/form-data body (or pre-uploaded to Discord's GCP bucket) 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 poll, the current user must have the SEND_POLLS 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 100 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.

¹ See Uploading Files for details.

² Cannot be used by user accounts.

³ Sending multiple messages in the same channel with the same nonce in a short period of time will result in only the first message being sent.

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

Examples for file uploads are available in Uploading Files.

Posts a greet message to a channel. This endpoint requires the channel is a DM channel or you reply to a system message. Returns a message object on success. Fires a Message Create Gateway event.

Creates attachment URLs to upload the intended attachments directly to Discord's GCP storage bucket. Returns an array of cloud attachment objects. Requires the same permissions as uploading an attachment inline with a message. See Uploading to Google Cloud for more information.

¹ When uploading a clip, is_clip, clip_created_at, and clip_participant_ids are required. See message types for more information.

{
  "attachments": [
    {
      "id": "23",
      "upload_url": "https://discord-attachments-uploads-prd.storage.googleapis.com/87e49c99-43f8-4a33-baad-5a834c94424c/cat.png?upload_id=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "upload_filename": "87e49c99-43f8-4a33-baad-5a834c94424c/cat.png"
    }
  ]
}

Deletes an attachment from Discord's GCP storage bucket. Returns a 204 empty response on success.

This endpoint should be used to delete an uploaded attachment that was not used. See Uploading to Google Cloud for more information.

Refreshes the URLs of attachments that were uploaded to Discord's CDN. The provided URLs do not have to be valid or signed. Existing query string parameters are preserved.

{
  "refreshed_urls": [
    {
      "original": "https://cdn.discordapp.com/attachments/1012345678900020080/1234567891233211234/my_image.png?ex=65d903de&is=65c68ede&hm=2481f30dd67f503f54d020ae3b5533b9987fae4e55f2b4e3926e08a3fa3ee24f&",
      "refreshed": "https://cdn.discordapp.com/attachments/1012345678900020080/1234567891233211234/my_image.png?ex=66143372&is=6601be72&hm=5a90a0ac363d9de3619044102ffe963041517f0e2f78baecabfc2f544a14eace&"
    }
  ]
}

Sets the channel's latest acknowledged message (marks a message as read) for the current user. Fires a Message Ack Gateway event.

The message ID parameter does not need to be a valid message ID, but it must be a valid snowflake. If the message ID is being set to a message sent prior to the latest acknowledged one, manual should be true or the resulting read state update should be ignored by clients (but is still saved), resulting in undefined behavior. In this case, mention_count should also be set to the amount of mentions unacknowledged as it is not automatically calculated by Discord.

¹ Requires manual to be true.

Crossposts a message in a News Channel to following channels. Requires the SEND_MESSAGES permission if the current user sent the message, or additionally the MANAGE_MESSAGES permission for all other messages. Returns a message object on success. Fires a Message Update (and possibly multiple Message Create) Gateway event.

Hides a message from the feed of the guild the channel belongs to. Returns a 204 empty response on success.

Get a list of users that reacted with this emoji. Returns an array of partial user objects. The emoji must be URL Encoded or the request will fail. To use custom emoji, you must encode it in the format name:id with the emoji name and emoji ID.

Creates a reaction for the message. Requires the READ_MESSAGE_HISTORY permission if operating on a guild channel. Additionally, if nobody else has reacted to the message using this emoji, this endpoint requires the ADD_REACTIONS permission. Returns a 204 empty response on success. Fires a Message Reaction Add (and optionally a Burst Credit Balance Update) Gateway event. The emoji must be URL Encoded or the request will fail. To use custom emoji, you must encode it in the format name:id with the emoji name and emoji ID.

Deletes 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. To use custom emoji, you must encode it in the format name:id with the emoji name and emoji ID.

Deletes another user's reaction. Requires the MANAGE_MESSAGES permission. 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. To use custom emoji, you must encode it in the format name:id with the emoji name and emoji ID.

Deletes all the reactions for a given emoji on a message. Returns a 204 empty response on success. Requires the MANAGE_MESSAGES permission. Fires a Message Reaction Remove Emoji Gateway event. The emoji must be URL Encoded or the request will fail. To use custom emoji, you must encode it in the format name:id with the emoji name and emoji ID.

Deletes all reactions on a message. Returns a 204 empty response on success. Requires the MANAGE_MESSAGES permission. Fires a Message Reaction Remove All Gateway event.

Edits a previously sent message. All fields 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.

When the content field is edited, the mentions array in the message object will be reconstructed from scratch based on the new content. 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.

¹ See Uploading Files for details.

Deletes a message. Requires the MANAGE_MESSAGES permission if operating on a guild channel and trying to delete a message that was not sent by the current user. Returns a 204 empty response on success. Fires a Message Delete Gateway event.

Deletes multiple messages from a guild channel in a single request. 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).

Returns all pinned messages in the channel as an array of message objects without the reactions key.

Pins a message in a channel. Requires the MANAGE_MESSAGES permission if operating on a guild channel. Returns a 204 empty response on success.

Unpins a message in a channel. Requires the MANAGE_MESSAGES permission if operating on a guild channel. Returns a 204 empty response on success.

Acknowledges the currently pinned messages in a channel. Returns a 204 empty response on success. Fires a Channel Pins Ack Gateway event.

Returns information on the media of a post (thread) in a media channel. The media channel must be a paywalled role subscription benefit. If the user is not in the guild, the guild must be discoverable.

¹ If a media attachment is present, a fake thumbnail will be rendered in the preview as a CTA to subscribe to the role that unlocks the media channel.

{
  "media": {
    "guild_id": "1046920999469330512",
    "channel_id": "1120793989809967114",
    "parent_channel_id": "1120793939562217483",
    "message_id": "1120793989809967114",
    "title": "feet picers",
    "description": "https://tenor.com/view/naomi-bunny-melon-gif-22514980",
    "guild_name": "Hood Network",
    "guild_icon": "a_78187748cb59baec2bf6a1f8766ff9fc",
    "author_id": "728342296696979526",
    "thumbnail": {
      "url": "https://media.tenor.com/ttfzDdgGOqgAAAAM/naomi-bunny.png",
      "proxy_url": "https://images-ext-2.discordapp.net/external/RGh8LSJbaADcUFgzFsvpODM6E2nz3xKVg_Mrg9UE58k/https/media.tenor.com/ttfzDdgGOqgAAAAe/naomi-bunny.png",
      "width": 388,
      "height": 640
    },
    "has_media_attachment": true
  }
}

Returns debug information about an embed.

Returns embed data from a list of URLs.

Get a list of users that voted for this specific answer.

Immediately ends the poll. You cannot end polls from other users.

Returns a message object. Fires a Message Update Gateway event.

Submits a poll vote for the current user. Returns a 204 empty response on success. Fires multiple Message Poll Vote Add and optionally Message Poll Vote Remove Gateway events.