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.

Message Object

A message sent in a channel within Discord.

Message Structure

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

Message Type

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

User Join Message Type

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

However, if the guild has the CLAN feature, the same is determined via dividing the message's timestamp with millisecond precision by modulo 10.

See the below table for the system welcome messages specific to clans.

Message Flags

Example Message

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

Example Crossposted Message

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

Message Activity Object

A rich presence invite in a message.

Message Activity Structure

¹ This field is send-only.

Message Call Object

A call in a private channel.

Message Call Structure

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

Message Interaction Metadata Object

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

Message Interaction Metadata Structure

Ephemerality Reason

Message Role Subscription Object

A role subscription purchase or renewal.

Message Role Subscription Structure

Message Purchase Notification Object

A guild product purchase notification.

Message Purchase Notification Structure

Message Purchase Notification Type

Determines the type of purchase notification.

Guild Product Purchase Structure

Message Gift Info Object

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

Message Gift Info Structure

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

Message Soundboard Sound Structure

Message Reference Object

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.

Message Reference Structure

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

Message Forward Only Structure

Message Reference Type

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.

Message Snapshot Object

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

Message Snapshot Structure

Snapshot Message Structure

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

Example Message Snapshot

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

Message Types

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.

Crosspost Messages

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

Forwarded Messages

• These are messages which capture a snapshot of a message, preventing spoofing or tampering (HAS_SNAPSHOT flag).
• 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.
• Stricter rate limits for this feature have been applied based on:
  • Number of forwards sent
  • Total attachment size

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

Reply Messages

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

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

Voice Messages

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.

When uploading a voice message attachment directly, the provided content type must match an audio content type to support the additional fields.

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

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)

Reaction Object

Reaction Structure

Reaction Count Details Structure

Reaction Type

Embed Object

Embed Structure

Embed Type

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.

Embed Thumbnail Structure

Embed Video Structure

Embed Image Structure

Embed Provider Structure

Embed Author Structure

Embed Footer Structure

Embed Field Structure

Attachment Object

Attachment Structure

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

Attachment Flags

Allowed Mentions Object

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.

Allowed Mention Types

Allowed Mentions Structure

Allowed Mentions Reference

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

Poll Object

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.

Poll Structure

¹ Only text is supported.

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

Poll Create Structure

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.

Poll Layout Type

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

Poll Media Structure

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 do not depend on that in the future.

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

Poll Answer Structure

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.

Poll Results Structure

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.

Poll Answer Count Structure

Example Poll

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

Poll Result Notifications

Poll result notifications are sent as standard messages in the channel with the POLL_RESULT message type. The author of the message is the user who created the poll, and the message has a reference pointing to the original poll message.

These messages have a special embed structure which contains information about the poll results. The custom embed fields below are collapsed as a list of key-value pairs into the fields array on the embed object.

Poll Result Embed Structure

¹ If these fields are omitted, the poll did not have a decisive winner.

Example Poll Result Embed

{
  "type": "poll_result",
  "fields": [
    {
      "name": "poll_question_text",
      "value": "aliens?",
      "inline": false
    },
    {
      "name": "victor_answer_votes",
      "value": "100",
      "inline": false
    },
    {
      "name": "total_votes",
      "value": "101",
      "inline": false
    },
    {
      "name": "victor_answer_id",
      "value": "1",
      "inline": false
    },
    {
      "name": "victor_answer_text",
      "value": "ofc",
      "inline": false
    },
    {
      "name": "victor_answer_emoji_id",
      "value": "1243729917288386560",
      "inline": false
    },
    {
      "name": "victor_answer_emoji_name",
      "value": "cheeks",
      "inline": false
    },
    {
      "name": "victor_answer_emoji_animated",
      "value": "true",
      "inline": false
    }
  ]
}

Endpoints

Get Messages

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

Query String Params

Search Messages

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.

Query String Params

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

Author Type

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

Has Type

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

Message Sort Type

Response Body

¹ Surrounding context messages are no longer returned.

Example Response

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

Get Message

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

Create Message

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.

Limitations

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

JSON/Form Params

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

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.

Create Greet Message

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.

JSON Params

Create Attachments

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.

JSON Params

Upload Attachment Structure

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

Cloud Attachment Structure

Example Response

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

Delete Attachment

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.

Refresh Attachment URLs

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.

JSON Params

Response Body

Refreshed Attachment Structure

Example Response

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

Acknowledge Message

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.

JSON Params

¹ Requires manual to be true.

Response Body

Crosspost Message

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.

Hide Message from Guild Feed

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

Get Reactions

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.

Query String Params

Create Reaction

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

Query String Params

Delete Own Reaction

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.

Delete Reaction

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.

Delete Reaction Emoji

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.

Delete All Reactions

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.

Edit Message

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.

JSON/Form Params

¹ See Uploading Files for details.

Delete Message

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.

Bulk Delete Messages

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

JSON Params

Get Pinned Messages

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

Pin Message

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

Unpin Message

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

Acknowledge Pinned Messages

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

Get Channel Media Preview

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.

Response Body

Media Preview Structure

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

Example Response

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

Unfurl Embed

Returns debug information about an embed.

JSON Params

Response Body

Embed Response Structure

Unfurl Embeds

Returns embed data from a list of URLs.

JSON Params

Response Body

Get Answer Voters

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

Query String Params

Response Body

End Poll

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

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

Create Poll Vote

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.

JSON Params