Messages¶

This section documents everything related to Discord messages.

Discord Models¶

Message¶

Methods

asyncadd_reaction
asyncclear_reaction
asyncclear_reactions
asynccreate_thread
asyncdelete
asyncedit
asyncforward
defis_system
asyncpin
asyncpublish
asyncremove_reaction
asyncreply
defto_reference
asyncunpin

class disnake.Message[source]¶

Represents a message from Discord.

x == y: Checks if two messages are equal.

x != y: Checks if two messages are not equal.

hash(x): Returns the message’s hash.

tts¶

Specifies if the message was done with text-to-speech. This can only be accurately received in on_message() due to a Discord limitation.

Type:: bool

type¶

The type of message. In most cases this should not be checked, but it is helpful in cases where it might be a system message for system_content.

Type:: MessageType

author¶

A Member that sent the message. If channel is a private channel or the user has the left the guild, then it is a User instead.

Type:: Member | abc.User

content¶

The actual contents of the message.

Type:: str

nonce¶

The value used by the Discord guild and the client to verify that the message is successfully sent. This is not stored long term within Discord’s servers and is only used ephemerally.

Type:: str | int | None

embeds¶

A list of embeds the message has.

Type:: list[Embed]

channel¶

The channel that the message was sent from. Could be a DMChannel or GroupChannel if it’s a private message.

Type:: TextChannel | VoiceChannel | StageChannel | Thread | DMChannel | GroupChannel | PartialMessageable

position¶

A number that indicates the approximate position of a message in a Thread. This is a number that starts at 0. e.g. the first message is position 0. This is None if the message was not sent in a Thread, or if it was sent before July 1, 2022.

New in version 2.6.

Type:: int | None

reference¶

The message that this message references. This is only applicable to messages of type MessageType.pins_add, crossposted messages created by a followed channel integration, message replies, or application command responses.

New in version 1.5.

Type:: MessageReference | None

interaction_metadata¶

The metadata about the interaction that caused this message, if any.

New in version 2.10.

Type:: InteractionMetadata | None

mention_everyone¶

Specifies if the message mentions everyone.

Note

This does not check if the @everyone or the @here text is in the message itself. Rather this boolean indicates if either the @everyone or the @here text is in the message and it did end up mentioning.

Type:: bool

mentions¶

A list of Member that were mentioned. If the message is in a private message then the list will be of User instead. For messages that are not of type MessageType.default, this array can be used to aid in system messages. For more information, see system_content.

Warning

The order of the mentions list is not in any particular order so you should not rely on it. This is a Discord limitation, not one with the library.

Type:: list[abc.User]

role_mentions¶

A list of Role that were mentioned. If the message is in a private message then the list is always empty.

Type:: list[Role]

id¶

The message ID.

Type:: int

application_id¶

If this message was sent from an interaction, or is an application owned webhook, then this is the ID of the application.

New in version 2.5.

Type:: int | None

webhook_id¶

If this message was sent by a webhook, then this is the webhook ID’s that sent this message.

Type:: int | None

attachments¶

A list of attachments given to a message.

Type:: list[Attachment]

pinned¶

Specifies if the message is currently pinned.

Type:: bool

flags¶

Extra features of the message.

New in version 1.3.

Type:: MessageFlags

reactions¶

Reactions to a message. Reactions can be either custom emoji or standard unicode emoji.

Type:: list[Reaction]

activity¶

The activity associated with this message. Sent with Rich-Presence related messages that for example, request joining, spectating, or listening to or with another member.

It is a dictionary with the following optional keys:

type: An integer denoting the type of message activity being requested.
party_id: The party ID associated with the party.

Type:: dict | None

application¶

The rich presence enabled application associated with this message.

It is a dictionary with the following keys:

id: A string representing the application’s ID.
name: A string representing the application’s name.
description: A string representing the application’s description.
icon: A string representing the icon ID of the application.
cover_image: A string representing the embed’s image asset ID.

Type:: dict | None

stickers¶

A list of sticker items given to the message.

New in version 1.6.

Type:: list[StickerItem]

components¶

A list of components in the message.

New in version 2.0.

Type:: list[Component]

message_snapshots¶

A list of forwarded messages.

New in version 2.10.

Type:: list[ForwardedMessage]

guild¶

The guild that the message belongs to, if applicable.

Type:: Guild | None

poll¶

The poll contained in this message.

New in version 2.10.

Type:: Poll | None

call¶

The call contained in this message. Only present when type is MessageType.call.

New in version 2.12.

Type:: MessageCall | None

raw_mentions¶

A property that returns an array of user IDs matched with the syntax of <@user_id> in the message content.

This allows you to receive the user IDs of mentioned users even in a private message context.

Type:: list[int]

raw_channel_mentions¶

A property that returns an array of channel IDs matched with the syntax of <#channel_id> in the message content.

Type:: list[int]

raw_role_mentions¶

A property that returns an array of role IDs matched with the syntax of <@&role_id> in the message content.

Type:: list[int]

channel_mentions¶

A list of abc.GuildChannel that were mentioned. If the message is in a private message then the list is always empty.

Type:: list[abc.GuildChannel]

clean_content¶

A property that returns the content in a “cleaned up” manner. This basically means that mentions are transformed into the way the client shows it. e.g. <#id> will transform into #name.

This will also transform @everyone and @here mentions into non-mentions.

Note

This does not affect markdown. If you want to escape or remove markdown then use utils.escape_markdown() or utils.remove_markdown() respectively, along with this function.

Type:: str

property created_at[source]¶

The message’s creation time in UTC.

Type:: datetime.datetime

property edited_at[source]¶

An aware UTC datetime object containing the edited time of the message.

Type:: datetime.datetime | None

property pinned_at[source]¶

An aware UTC datetime object containing the pin time of the message.

Note

This is only set on messages retrieved using abc.Messageable.pins().

New in version 2.11.

Type:: datetime.datetime | None

property jump_url[source]¶

Returns a URL that allows the client to jump to this message.

Type:: str

property thread[source]¶

The thread started from this message. None if no thread has been started.

New in version 2.4.

Type:: Thread | None

property role_subscription_data[source]¶

The metadata of the role subscription purchase/renewal, if this message is a MessageType.role_subscription_purchase.

New in version 2.9.

Type:: RoleSubscriptionData | None

is_system()[source]¶

Whether the message is a system message.

A system message is a message that is constructed entirely by the Discord API in response to something.

New in version 1.3.

Return type:: bool

system_content¶

A property that returns the content that is rendered regardless of the Message.type.

In the case of MessageType.default and MessageType.reply, this just returns the regular Message.content. Otherwise this returns an English message denoting the contents of the system message.

If the message type is unrecognised this method will return None.

Type:: str | None

property interaction[source]¶

The interaction that this message references. This exists only when the message is a response to an interaction without an existing message.

New in version 2.1.

Deprecated since version 2.10: Use interaction_metadata instead.

Type:: InteractionReference | None

await delete(*, delay=None)[source]¶

This function is a coroutine.

Deletes the message.

Your own messages could be deleted without any proper permissions. However to delete other people’s messages, you need the manage_messages permission.

Changed in version 1.1: Added the new delay keyword-only parameter.

Parameters:

delay (float | None) – If provided, the number of seconds to wait in the background before deleting the message. If the deletion fails then it is silently ignored.

Raises:

Forbidden – You do not have proper permissions to delete the message.
NotFound – The message was deleted already
HTTPException – Deleting the message failed.

await edit(content=..., *, embed=..., embeds=..., file=..., files=..., attachments=..., suppress=..., suppress_embeds=..., flags=..., allowed_mentions=..., view=..., components=..., delete_after=None)[source]¶

This function is a coroutine.

Edits the message.

The content must be able to be transformed into a string via str(content).

Note

If the original message has embeds with images that were created from local files (using the file parameter with Embed.set_image() or Embed.set_thumbnail()), those images will be removed if the message’s attachments are edited in any way (i.e. by setting file/files/attachments, or adding an embed with local files).

Note

This method cannot be used on messages authored by others, with one exception. The suppress_embeds parameter can be used to change the state of embeds on other users’ messages, requiring the manage_messages permission.

Changed in version 1.3: The suppress keyword-only parameter was added.

Changed in version 2.5: The suppress keyword-only parameter was deprecated in favor of suppress_embeds.

Changed in version 2.6: Raises TypeError instead of InvalidArgument.

Parameters:

content (str | None) – The new content to replace the message with. Could be None to remove the content.
embed (Embed | None) – The new embed to replace the original with. This cannot be mixed with the embeds parameter. Could be None to remove the embed.
embeds (list[Embed]) –
The new embeds to replace the original with. Must be a maximum of 10. This cannot be mixed with the embed parameter. To remove all embeds [] should be passed.

New in version 2.0.
file (File) –
The file to upload. This cannot be mixed with the files parameter. Files will be appended to the message, see the attachments parameter to remove/replace existing files.

New in version 2.1.
files (list[File]) –
A list of files to upload. This cannot be mixed with the file parameter. Files will be appended to the message, see the attachments parameter to remove/replace existing files.

New in version 2.1.
attachments (list[Attachment] | None) –
A list of attachments to keep in the message. If [] or None is passed then all existing attachments are removed. Keeps existing attachments if not provided.

Changed in version 2.5: Supports passing None to clear attachments.
suppress_embeds (bool) – Whether to suppress embeds for the message. This hides all the embeds from the UI if set to True. If set to False, this brings the embeds back if they were suppressed.
flags (MessageFlags) –
The new flags to set for this message. Overrides existing flags. Only suppress_embeds and is_components_v2 are supported.

If parameter suppress_embeds is provided, that will override the setting of MessageFlags.suppress_embeds.

New in version 2.9.
delete_after (float | None) – If provided, the number of seconds to wait in the background before deleting the message we just edited. If the deletion fails, then it is silently ignored.
allowed_mentions (AllowedMentions | None) –
Controls the mentions being processed in this message. If this is passed, then the object is merged with Client.allowed_mentions. The merging behaviour only overrides attributes that have been explicitly passed to the object, otherwise it uses the attributes set in Client.allowed_mentions. If no object is passed at all then the defaults given by Client.allowed_mentions are used instead.

New in version 1.4.
view (View | None) –
The updated view to update this message with. This cannot be mixed with components. If None is passed then the view is removed.

New in version 2.0.
components (UIComponent | list[UIComponent | list[WrappedComponent]]) –
The updated components to update this message with. This cannot be mixed with view. If None is passed then the components are removed.

New in version 2.4.

Note

Passing v2 components here automatically sets the is_components_v2 flag. Setting this flag cannot be reverted. Note that this also disables the content and embeds fields. If the message previously had any of these fields set, you must set them to None.

Raises:

HTTPException – Editing the message failed.
Forbidden – Tried to suppress embeds on a message without permissions or edited a message’s content or embed that isn’t yours.
TypeError – You specified both embed and embeds, or file and files, or view and components.
ValueError – You tried to send v2 components together with content or embeds.

Returns:

The message that was edited.

Return type:

Message

await publish()[source]¶

This function is a coroutine.

Publishes this message to your announcement channel.

You must have the send_messages permission to do this.

If the message is not your own then the manage_messages permission is also needed.

Raises:

Forbidden – You do not have the proper permissions to publish this message.
HTTPException – Publishing the message failed.

await pin(*, reason=None)[source]¶

This function is a coroutine.

Pins the message.

You must have the pin_messages permission to do this in a non-private channel context.

This does not work with messages sent in a VoiceChannel or StageChannel.

Parameters:

reason (str | None) –

The reason for pinning the message. Shows up on the audit log.

New in version 1.4.

Raises:

Forbidden – You do not have permissions to pin the message.
NotFound – The message or channel was not found or deleted.
HTTPException – Pinning the message failed, probably due to the channel having more than 50 pinned messages or the channel not supporting pins.

await unpin(*, reason=None)[source]¶

This function is a coroutine.

Unpins the message.

You must have the pin_messages permission to do this in a non-private channel context.

Parameters:

reason (str | None) –

The reason for unpinning the message. Shows up on the audit log.

New in version 1.4.

Raises:

Forbidden – You do not have permissions to unpin the message.
NotFound – The message or channel was not found or deleted.
HTTPException – Unpinning the message failed.

await add_reaction(emoji)[source]¶

This function is a coroutine.

Adds a reaction to the message.

The emoji may be a unicode emoji or a custom guild Emoji.

You must have the read_message_history permission to use this. If nobody else has reacted to the message using this emoji, the add_reactions permission is required.

Changed in version 2.6: Raises TypeError instead of InvalidArgument.

Parameters:

emoji (Emoji | Reaction | PartialEmoji | str) – The emoji to react with.

Raises:

HTTPException – Adding the reaction failed.
Forbidden – You do not have the proper permissions to react to the message.
NotFound – The emoji you specified was not found.
TypeError – The emoji parameter is invalid.

await remove_reaction(emoji, member)[source]¶

This function is a coroutine.

Removes a reaction by the member from the message.

The emoji may be a unicode emoji or a custom guild Emoji.

If the reaction is not your own (i.e. member parameter is not you) then the manage_messages permission is needed.

The member parameter must represent a member and meet the abc.Snowflake abc.

Changed in version 2.6: Raises TypeError instead of InvalidArgument.

Parameters:

emoji (Emoji | Reaction | PartialEmoji | str) – The emoji to remove.
member (abc.Snowflake) – The member for which to remove the reaction.

Raises:

HTTPException – Removing the reaction failed.
Forbidden – You do not have the proper permissions to remove the reaction.
NotFound – The member or emoji you specified was not found.
TypeError – The emoji parameter is invalid.

await clear_reaction(emoji)[source]¶

This function is a coroutine.

Clears a specific reaction from the message.

The emoji may be a unicode emoji or a custom guild Emoji.

You need the manage_messages permission to use this.

New in version 1.3.

Changed in version 2.6: Raises TypeError instead of InvalidArgument.

Parameters:

emoji (Emoji | Reaction | PartialEmoji | str) – The emoji to clear.

Raises:

HTTPException – Clearing the reaction failed.
Forbidden – You do not have the proper permissions to clear the reaction.
NotFound – The emoji you specified was not found.
TypeError – The emoji parameter is invalid.

await clear_reactions()[source]¶

This function is a coroutine.

Removes all the reactions from the message.

You need the manage_messages permission to use this.

Raises:

HTTPException – Removing the reactions failed.
Forbidden – You do not have the proper permissions to remove all the reactions.

await create_thread(*, name, auto_archive_duration=None, slowmode_delay=None, reason=None)[source]¶

This function is a coroutine.

Creates a public thread from this message.

You must have create_public_threads in order to create a public thread from a message.

The channel this message belongs in must be a TextChannel.

New in version 2.0.

Changed in version 2.6: Raises TypeError instead of InvalidArgument.

Parameters:

name (str) – The name of the thread.
auto_archive_duration (int | ThreadArchiveDuration) – The duration in minutes before a thread is automatically archived for inactivity. If not provided, the channel’s default auto archive duration is used. Must be one of 60, 1440, 4320, or 10080.
slowmode_delay (int | None) –
Specifies the slowmode rate limit for users in this thread, in seconds. A value of 0 disables slowmode. The maximum value possible is 21600. If set to None or not provided, slowmode is inherited from the parent’s default_thread_slowmode_delay.

New in version 2.3.
reason (str | None) –
The reason for creating the thread. Shows up on the audit log.

New in version 2.5.

Raises:

Forbidden – You do not have permissions to create a thread.
HTTPException – Creating the thread failed.
TypeError – This message does not have guild info attached.

Returns:

The created thread.

Return type:

Thread

await reply(content=None, *, fail_if_not_exists=True, **kwargs)[source]¶

This function is a coroutine.

A shortcut method to abc.Messageable.send() to reply to the Message.

New in version 1.6.

Changed in version 2.3: Added fail_if_not_exists keyword argument. Defaults to True.

Changed in version 2.6: Raises TypeError or ValueError instead of InvalidArgument.

Parameters:

fail_if_not_exists (bool) –

Whether replying using the message reference should raise HTTPException if the message no longer exists or Discord could not fetch the message.

New in version 2.3.

Raises:

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message.
TypeError – You specified both embed and embeds, or file and files, or view and components.
ValueError – The files or embeds list is too large.

Returns:

The message that was sent.

Return type:

Message

await forward(channel)[source]¶

This function is a coroutine.

A shortcut method to abc.Messageable.send() to forward a Message.

New in version 2.10.

Parameters:

Raises:

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message.

Returns:

The message that was sent.

Return type:

Message

to_reference(*, type=MessageReferenceType.default, fail_if_not_exists=True)[source]¶

Creates a MessageReference from the current message.

New in version 1.6.

Parameters:

type (MessageReferenceType) –
The type of the message reference. This is used to control whether to reply to or forward a message. Defaults to replying.

New in version 2.10.
fail_if_not_exists (bool) –
Whether replying using the message reference should raise HTTPException if the message no longer exists or Discord could not fetch the message.

New in version 1.7.

Returns:

The reference to this message.

Return type:

MessageReference

Reaction¶

Attributes

count
emoji
me
message

Methods

asyncclear
defis_custom_emoji
asyncremove
defusers

class disnake.Reaction[source]¶

Represents a reaction to a message.

Depending on the way this object was created, some of the attributes can have a value of None.

x == y: Checks if two reactions are equal. This works by checking if the emoji is the same. So two messages with the same reaction will be considered “equal”.

x != y: Checks if two reactions are not equal.

hash(x): Returns the reaction’s hash.

str(x): Returns the string form of the reaction’s emoji.

emoji¶

The reaction emoji. May be a custom emoji, or a unicode emoji.

Type:: Emoji | PartialEmoji | str

count¶

Number of times this reaction was made

Type:: int

me¶

If the user sent this reaction.

Type:: bool

message¶

The message this reaction belongs to.

Type:: Message

async for ... in users(*, limit=None, after=None)[source]¶

Returns an AsyncIterator representing the users that have reacted to the message.

The after parameter must represent a member and meet the abc.Snowflake abc.

Examples

Usage

# We do not actually recommend doing this.
async for user in reaction.users():
    await channel.send(f'{user} has reacted with {reaction.emoji}!')

Flattening into a list:

users = await reaction.users().flatten()
# users is now a list of User...
winner = random.choice(users)
await channel.send(f'{winner} has won the raffle.')

Parameters:

limit (int | None) – The maximum number of results to return. If not provided, returns all the users who reacted to the message.
after (abc.Snowflake | None) – For pagination, reactions are sorted by member.

Raises:

HTTPException – Getting the users for the reaction failed.

Yields:

User | Member – The member (if retrievable) or the user that has reacted to this message. The case where it can be a Member is in a guild message context. Sometimes it can be a User if the member has left the guild.

is_custom_emoji()[source]¶

Whether the emoji is a custom emoji.

Return type:: bool

await remove(user)[source]¶

This function is a coroutine.

Removes the reaction by the provided User from the message.

If the reaction is not your own (i.e. user parameter is not you) then the manage_messages permission is needed.

The user parameter must represent a user or member and meet the abc.Snowflake abc.

Parameters:

user (abc.Snowflake) – The user or member from which to remove the reaction.

Raises:

HTTPException – Removing the reaction failed.
Forbidden – You do not have the proper permissions to remove the reaction.
NotFound – The user you specified, or the reaction’s message was not found.

await clear()[source]¶

This function is a coroutine.

Clears this reaction from the message.

You need the manage_messages permission to use this.

New in version 1.3.

Changed in version 2.6: Raises TypeError instead of InvalidArgument.

Raises:

HTTPException – Clearing the reaction failed.
Forbidden – You do not have the proper permissions to clear the reaction.
NotFound – The emoji you specified was not found.
TypeError – The emoji parameter is invalid.

Attachment¶

Attributes

content_type
description
duration
ephemeral
filename
flags
height
id
proxy_url
size
title
url
waveform
width

Methods

defis_spoiler
asyncread
asyncsave
asyncto_file

class disnake.Attachment[source]¶

Represents an attachment from Discord.

str(x): Returns the URL of the attachment.

x == y: Checks if the attachment is equal to another attachment.

x != y: Checks if the attachment is not equal to another attachment.

hash(x): Returns the hash of the attachment.

Changed in version 1.7: Attachment can now be casted to str and is hashable.

id¶

The attachment’s ID.

Type:: int

size¶

The attachment’s size in bytes.

Type:: int

height¶

The attachment’s height, in pixels. Only applicable to images and videos.

Type:: int | None

width¶

The attachment’s width, in pixels. Only applicable to images and videos.

Type:: int | None

filename¶

The attachment’s filename.

Type:: str

title¶

The attachment title. If the filename contained special characters, this will be set to the original filename, without filename extension.

New in version 2.10.

Type:: str | None

url¶

The attachment URL. If the message this attachment was attached to is deleted, then this will 404.

Type:: str

proxy_url¶

The proxy URL. This is a cached version of the url in the case of images. When the message is deleted, this URL might be valid for a few minutes or not valid at all.

Type:: str

content_type¶

The attachment’s media type.

New in version 1.7.

Type:: str | None

ephemeral¶

Whether the attachment is ephemeral.

New in version 2.1.

Type:: bool

description¶

The attachment’s description.

New in version 2.3.

Type:: str

duration¶

The duration of the audio attachment in seconds, if this is attached to a voice message (see MessageFlags.is_voice_message).

New in version 2.9.

Type:: float | None

waveform¶

The byte array representing a sampled waveform, if this is attached to a voice message (see MessageFlags.is_voice_message).

New in version 2.9.

Type:: bytes | None

is_spoiler()[source]¶

Whether this attachment contains a spoiler.

Return type:: bool

property flags[source]¶

Returns the attachment’s flags.

New in version 2.10.

Type:: AttachmentFlags

await save(fp, *, seek_begin=True, use_cached=False)[source]¶

This function is a coroutine.

Saves this attachment into a file-like object.

Parameters:

fp (io.BufferedIOBase | os.PathLike) – The file-like object to save this attachment to or the filename to use. If a filename is passed then a file is created with that filename and used instead.
seek_begin (bool) – Whether to seek to the beginning of the file after saving is successfully done.
use_cached (bool) – Whether to use proxy_url rather than url when downloading the attachment. This will allow attachments to be saved after deletion more often, compared to the regular URL which is generally deleted right after the message is deleted. Note that this can still fail to download deleted attachments if too much time has passed and it does not work on some types of attachments.

Raises:

HTTPException – Saving the attachment failed.
NotFound – The attachment was deleted.

Returns:

The number of bytes written.

Return type:

int

await read(*, use_cached=False)[source]¶

This function is a coroutine.

Retrieves the content of this attachment as a bytes object.

New in version 1.1.

Parameters:

use_cached (bool) – Whether to use proxy_url rather than url when downloading the attachment. This will allow attachments to be saved after deletion more often, compared to the regular URL which is generally deleted right after the message is deleted. Note that this can still fail to download deleted attachments if too much time has passed and it does not work on some types of attachments.

Raises:

HTTPException – Downloading the attachment failed.
Forbidden – You do not have permissions to access this attachment
NotFound – The attachment was deleted.

Returns:

The contents of the attachment.

Return type:

bytes

await to_file(*, use_cached=False, spoiler=False, description=...)[source]¶

This function is a coroutine.

Converts the attachment into a File suitable for sending via abc.Messageable.send().

New in version 1.3.

Parameters:

use_cached (bool) –
Whether to use proxy_url rather than url when downloading the attachment. This will allow attachments to be saved after deletion more often, compared to the regular URL which is generally deleted right after the message is deleted. Note that this can still fail to download deleted attachments if too much time has passed and it does not work on some types of attachments.

New in version 1.4.
spoiler (bool) –
Whether the file is a spoiler.

New in version 1.4.
description (str | None) –
The file’s description. Copies this attachment’s description by default, set to None to remove.

New in version 2.3.

Raises:

HTTPException – Downloading the attachment failed.
Forbidden – You do not have permissions to access this attachment
NotFound – The attachment was deleted.

Returns:

The attachment as a file suitable for sending.

Return type:

File

DeletedReferencedMessage¶

Attributes

channel_id
guild_id
id

class disnake.DeletedReferencedMessage[source]¶

A special sentinel type that denotes whether the resolved message referenced message had since been deleted.

The purpose of this class is to separate referenced messages that could not be fetched and those that were previously fetched but have since been deleted.

New in version 1.6.

property id[source]¶

The message ID of the deleted referenced message.

Type:: int

property channel_id[source]¶

The channel ID of the deleted referenced message.

Type:: int

property guild_id[source]¶

The guild ID of the deleted referenced message.

Type:: int | None

InteractionReference¶

Attributes

id
name
type
user

class disnake.InteractionReference[source]¶

Represents an interaction being referenced in a message.

This means responses to message components do not include this property, instead including a message reference object as components always exist on preexisting messages.

New in version 2.1.

Deprecated since version 2.10: Use Message.interaction_metadata instead.

id¶

The ID of the interaction.

Type:: int

type¶

The type of interaction.

Type:: InteractionType

name¶

The name of the application command, including group and subcommand name if applicable (separated by spaces).

Note

For interaction references created before July 18th, 2022, this will not include group or subcommand names.

Type:: str

user¶

The user or member that triggered the referenced interaction.

Changed in version 2.10: This is now a Member when in a guild, if the message was received via a gateway event or the member is cached.

Type:: User | Member

InteractionMetadata¶

Attributes

authorizing_integration_owners
id
interacted_message_id
original_response_message_id
target_message_id
target_user
triggering_interaction_metadata
type
user

class disnake.InteractionMetadata[source]¶

Represents metadata about the interaction that caused a particular message.

New in version 2.10.

id¶

The ID of the interaction.

Type:: int

type¶

The type of the interaction.

Type:: InteractionType

user¶

The user that triggered the interaction.

Type:: User

authorizing_integration_owners¶

Details about the authorizing user/guild for the application installation related to the interaction.

Type:: AuthorizingIntegrationOwners

original_response_message_id¶

The ID of the original response message. Only present on followup messages.

Type:: int | None

target_user¶

The ID of the message the command was run on. Only present on interactions of ApplicationCommandType.message commands.

Type:: User | None

target_message_id¶

The user the command was run on. Only present on interactions of ApplicationCommandType.user commands.

Type:: int | None

interacted_message_id¶

The ID of the message containing the component. Only present on InteractionType.component interactions.

Type:: int | None

triggering_interaction_metadata¶

The metadata of the original interaction that triggered the modal. Only present on InteractionType.modal_submit interactions.

Type:: InteractionMetadata | None

RoleSubscriptionData¶

Attributes

is_renewal
role_subscription_listing_id
tier_name
total_months_subscribed

class disnake.RoleSubscriptionData[source]¶

Represents metadata of the role subscription purchase/renewal in a message of type MessageType.role_subscription_purchase.

New in version 2.9.

role_subscription_listing_id¶

The ID of the subscription listing the user subscribed to.

Type:: int

tier_name¶

The name of the tier the user subscribed to.

Type:: str

total_months_subscribed¶

The cumulative number of months the user has been subscribed for.

Type:: int

is_renewal¶

Whether this message is for a subscription renewal instead of a new subscription.

Type:: bool

MessageCall¶

Attributes

ended_timestamp
participant_ids

class disnake.MessageCall[source]¶

Represents a call in a message.

New in version 2.12.

ended_timestamp¶

The timestamp when the call ended, or None if the call is still ongoing.

Type:: datetime.datetime | None

participant_ids¶

A list of user IDs of the participants in the call.

Due to API limitations, this list is simply the user IDs that were in the call. It is not resolved to the user objects themselves.

Type:: list[int]

RawTypingEvent¶

Attributes

channel_id
guild_id
member
timestamp
user_id

class disnake.RawTypingEvent[source]¶

Represents the event payload for an on_raw_typing() event.

New in version 2.3.

user_id¶

The ID of the user who started typing.

Type:: int

channel_id¶

The ID of the channel where the user started typing.

Type:: int

guild_id¶

The ID of the guild where the user started typing or None if it was in a DM.

Type:: int | None

member¶

The member object of the user who started typing or None if it was in a DM.

Type:: Member | None

timestamp¶

The UTC datetime when the user started typing.

Changed in version 2.9: Changed from naive to aware datetime.

Type:: datetime.datetime

RawMessageDeleteEvent¶

Attributes

cached_message
channel_id
guild_id
message_id

class disnake.RawMessageDeleteEvent[source]¶

Represents the event payload for an on_raw_message_delete() event.

channel_id¶

The channel ID where the deletion took place.

Type:: int

guild_id¶

The guild ID where the deletion took place, if applicable.

Type:: int | None

message_id¶

The message ID that got deleted.

Type:: int

cached_message¶

The cached message, if found in the internal message cache.

Type:: Message | None

RawBulkMessageDeleteEvent¶

Attributes

cached_messages
channel_id
guild_id
message_ids

class disnake.RawBulkMessageDeleteEvent[source]¶

Represents the event payload for an on_raw_bulk_message_delete() event.

message_ids¶

A set of the message IDs that were deleted.

Type:: set[int]

channel_id¶

The channel ID where the deletion took place.

Type:: int

guild_id¶

The guild ID where the deletion took place, if applicable.

Type:: int | None

cached_messages¶

The cached messages, if found in the internal message cache.

Type:: list[Message]

RawMessageUpdateEvent¶

Attributes

cached_message
channel_id
data
guild_id
message_id

class disnake.RawMessageUpdateEvent[source]¶

Represents the event payload for an on_raw_message_edit() event.

message_id¶

The message ID that got updated.

Type:: int

channel_id¶

The channel ID where the update took place.

New in version 1.3.

Type:: int

guild_id¶

The guild ID where the update took place, if applicable.

New in version 1.7.

Type:: int | None

data¶

The raw data given by the gateway.

Type:: dict

cached_message¶

The cached message, if found in the internal message cache. Represents the message before it is modified by the data in RawMessageUpdateEvent.data.

Type:: Message | None

RawPollVoteActionEvent¶

Attributes

answer_id
cached_member
channel_id
event_type
guild_id
message_id
user_id

class disnake.RawPollVoteActionEvent[source]¶

Represents the event payload for on_raw_poll_vote_add() and on_raw_poll_vote_remove() events.

New in version 2.10.

message_id¶

The message ID that got or lost a vote.

Type:: int

user_id¶

The user ID who added the vote or whose vote was removed.

Type:: int

cached_member¶

The member who added the vote. Available only when the guilds and members are cached.

Type:: Member | None

channel_id¶

The channel ID where the vote addition or removal took place.

Type:: int

guild_id¶

The guild ID where the vote addition or removal took place, if applicable.

Type:: int | None

answer_id¶

The ID of the answer that was voted or unvoted.

Type:: int

event_type¶

The event type that triggered this action. Can be POLL_VOTE_ADD for vote addition or POLL_VOTE_REMOVE for vote removal.

Type:: str

RawReactionActionEvent¶

Attributes

channel_id
emoji
event_type
guild_id
member
message_author_id
message_id
user_id

class disnake.RawReactionActionEvent[source]¶

Represents the event payload for on_raw_reaction_add() and on_raw_reaction_remove() events.

message_id¶

The message ID that got or lost a reaction.

Type:: int

user_id¶

The user ID who added the reaction or whose reaction was removed.

Type:: int

channel_id¶

The channel ID where the reaction addition or removal took place.

Type:: int

guild_id¶

The guild ID where the reaction addition or removal took place, if applicable.

Type:: int | None

emoji¶

The custom or unicode emoji being used.

Changed in version 2.9: This now also includes the correct animated value when a reaction was removed.

Type:: PartialEmoji

member¶

The member who added the reaction. Only available if event_type is REACTION_ADD and the reaction is inside a guild.

New in version 1.3.

Type:: Member | None

event_type¶

The event type that triggered this action. Can be REACTION_ADD for reaction addition or REACTION_REMOVE for reaction removal.

New in version 1.3.

Type:: str

message_author_id¶

The ID of the author who created the message that got a reaction. Only available if event_type is REACTION_ADD. May also be None if the message was created by a webhook.

New in version 2.10.

Type:: int | None

RawReactionClearEvent¶

Attributes

channel_id
guild_id
message_id

class disnake.RawReactionClearEvent[source]¶

Represents the event payload for an on_raw_reaction_clear() event.

message_id¶

The message ID that got its reactions cleared.

Type:: int

channel_id¶

The channel ID where the reaction clear took place.

Type:: int

guild_id¶

The guild ID where the reaction clear took place, if applicable.

Type:: int | None

RawReactionClearEmojiEvent¶

Attributes

channel_id
emoji
guild_id
message_id

class disnake.RawReactionClearEmojiEvent[source]¶

Represents the event payload for an on_raw_reaction_clear_emoji() event.

New in version 1.3.

message_id¶

The message ID that got its reactions cleared.

Type:: int

channel_id¶

The channel ID where the reaction clear took place.

Type:: int

guild_id¶

The guild ID where the reaction clear took place, if applicable.

Type:: int | None

emoji¶

The custom or unicode emoji being removed.

Changed in version 2.9: This now also includes the correct animated value.

Type:: PartialEmoji

Data Classes¶

Embed¶

Attributes

author
colour
description
fields
footer
image
provider
thumbnail
timestamp
title
type
url
video

Methods

clsEmbed.from_dict
clsEmbed.get_default_color
clsEmbed.get_default_colour
clsEmbed.set_default_color
clsEmbed.set_default_colour
defadd_field
defcheck_limits
defclear_fields
defcopy
definsert_field_at
defremove_author
defremove_field
defremove_footer
defset_author
defset_field_at
defset_footer
defset_image
defset_thumbnail
defto_dict

class disnake.Embed(*, title=None, type='rich', description=None, url=None, timestamp=None, colour=..., color=...)[source]¶

Represents a Discord embed.

x == y: Checks if two embeds are equal.

New in version 2.6.

x != y: Checks if two embeds are not equal.

New in version 2.6.

len(x): Returns the total size of the embed. Useful for checking if it’s within the 6000 character limit. Check if all aspects of the embed are within the limits with Embed.check_limits().

bool(b): Returns whether the embed has any data set.

New in version 2.0.

Certain properties return an EmbedProxy, a type that acts similar to a regular dict except using dotted access, e.g. embed.author.icon_url.

For ease of use, all parameters that expect a str are implicitly cast to str for you.

title¶

The title of the embed.

Type:: str | None

type¶

The type of embed. Usually “rich”. Possible strings for embed types can be found on Discord’s api-docs.

Type:: str | None

description¶

The description of the embed.

Type:: str | None

url¶

The URL of the embed.

Type:: str | None

timestamp[source]¶

The timestamp of the embed content. This is an aware datetime. If a naive datetime is passed, it is converted to an aware datetime with the local timezone.

Type:: datetime.datetime | None

colour[source]¶

The colour code of the embed. Aliased to color as well. In addition to Colour, int can also be assigned to it, in which case the value will be converted to a Colour object.

Type:: Colour | None

classmethod from_dict(data)[source]¶

Converts a dict to a Embed provided it is in the format that Discord expects it to be in.

You can find out about this format in the official Discord documentation.

Parameters:: data (dict) – The dictionary to convert into an embed.

copy()[source]¶: Returns a shallow copy of the embed.

property footer[source]¶

Returns an EmbedProxy denoting the footer contents.

Possible attributes you can access are:

text
icon_url
proxy_icon_url

If an attribute is not set, it will be None.

set_footer(*, text, icon_url=..., icon_file=...)[source]¶

Sets the footer for the embed content.

This function returns the class instance to allow for fluent-style chaining.

At most one of icon_url or icon_file may be passed.

Warning

Passing a disnake.File object will make the embed not reusable.

Warning

If used with the other set_* methods, you must ensure that the File.filename is unique to avoid duplication.

Parameters:

text (str) –
The footer text.

Changed in version 2.6: No longer optional, must be set to a valid string.
icon_url (str | None) – The URL of the footer icon. Only HTTP(S) is supported.
icon_file (File) –
The file to use as the footer icon.

New in version 2.10.

remove_footer()[source]¶

Clears embed’s footer information.

This function returns the class instance to allow for fluent-style chaining.

New in version 2.0.

property image[source]¶

Returns an EmbedProxy denoting the image contents.

Possible attributes you can access are:

url
proxy_url
width
height

If an attribute is not set, it will be None.

set_image(url=..., *, file=...)[source]¶

Sets the image for the embed content.

This function returns the class instance to allow for fluent-style chaining.

Exactly one of url or file must be passed.

Warning

Passing a disnake.File object will make the embed not reusable.

Warning

If used with the other set_* methods, you must ensure that the File.filename is unique to avoid duplication.

Changed in version 1.4: Passing None removes the image.

Parameters:

url (str | None) – The source URL for the image. Only HTTP(S) is supported.
file (File) –
The file to use as the image.

New in version 2.2.

property thumbnail[source]¶

Returns an EmbedProxy denoting the thumbnail contents.

Possible attributes you can access are:

url
proxy_url
width
height

If an attribute is not set, it will be None.

set_thumbnail(url=..., *, file=...)[source]¶

Sets the thumbnail for the embed content.

This function returns the class instance to allow for fluent-style chaining.

Exactly one of url or file must be passed.

Warning

Passing a disnake.File object will make the embed not reusable.

Warning

If used with the other set_* methods, you must ensure that the File.filename is unique to avoid duplication.

Changed in version 1.4: Passing None removes the thumbnail.

Parameters:

url (str | None) – The source URL for the thumbnail. Only HTTP(S) is supported.
file (File) –
The file to use as the image.

New in version 2.2.

property video[source]¶

Returns an EmbedProxy denoting the video contents.

Possible attributes include:

url for the video URL.
proxy_url for the proxied video URL.
height for the video height.
width for the video width.

If an attribute is not set, it will be None.

property provider[source]¶

Returns an EmbedProxy denoting the provider contents.

The only attributes that might be accessed are name and url.

If an attribute is not set, it will be None.

property author[source]¶

Returns an EmbedProxy denoting the author contents.

See set_author() for possible values you can access.

If an attribute is not set, it will be None.

set_author(*, name, url=None, icon_url=..., icon_file=...)[source]¶

Sets the author for the embed content.

This function returns the class instance to allow for fluent-style chaining.

At most one of icon_url or icon_file may be passed.

Warning

Passing a disnake.File object will make the embed not reusable.

Warning

If used with the other set_* methods, you must ensure that the File.filename is unique to avoid duplication.

Parameters:

name (str) – The name of the author.
url (str | None) – The URL for the author.
icon_url (str | None) – The URL of the author icon. Only HTTP(S) is supported.
icon_file (File) –
The file to use as the author icon.

New in version 2.10.

remove_author()[source]¶

Clears embed’s author information.

This function returns the class instance to allow for fluent-style chaining.

New in version 1.4.

property fields[source]¶

Returns a list of EmbedProxy denoting the field contents.

See add_field() for possible values you can access.

If an attribute is not set, it will be None.

Type:: list[EmbedProxy]

add_field(name, value, *, inline=True)[source]¶

Adds a field to the embed object.

This function returns the class instance to allow for fluent-style chaining.

Parameters:

name (str) – The name of the field.
value (str) – The value of the field.
inline (bool) – Whether the field should be displayed inline. Defaults to True.

insert_field_at(index, name, value, *, inline=True)[source]¶

Inserts a field before a specified index to the embed.

This function returns the class instance to allow for fluent-style chaining.

New in version 1.2.

Parameters:

index (int) – The index of where to insert the field.
name (str) – The name of the field.
value (str) – The value of the field.
inline (bool) – Whether the field should be displayed inline. Defaults to True.

clear_fields()[source]¶: Removes all fields from this embed.

remove_field(index)[source]¶

Removes a field at a specified index.

If the index is invalid or out of bounds then the error is silently swallowed.

Note

When deleting a field by index, the index of the other fields shift to fill the gap just like a regular list.

Parameters:: index (int) – The index of the field to remove.

set_field_at(index, name, value, *, inline=True)[source]¶

Modifies a field to the embed object.

The index must point to a valid pre-existing field.

This function returns the class instance to allow for fluent-style chaining.

Parameters:

index (int) – The index of the field to modify.
name (str) – The name of the field.
value (str) – The value of the field.
inline (bool) – Whether the field should be displayed inline. Defaults to True.

Raises:

IndexError – An invalid index was provided.

to_dict()[source]¶: Converts this embed object into a dict.

classmethod set_default_colour(value)[source]¶

Set the default colour of all new embeds.

New in version 2.4.

Returns:: The colour that was set.
Return type:: Colour | None

classmethod set_default_color(value)[source]¶

Set the default colour of all new embeds.

New in version 2.4.

Returns:: The colour that was set.
Return type:: Colour | None

classmethod get_default_colour()[source]¶

Get the default colour of all new embeds.

New in version 2.4.

Returns:: The default colour.
Return type:: Colour | None

classmethod get_default_color()[source]¶

Get the default colour of all new embeds.

New in version 2.4.

Returns:: The default colour.
Return type:: Colour | None

check_limits()[source]¶

Checks if this embed fits within the limits dictated by Discord. There is also a 6000 character limit across all embeds in a message.

Returns nothing on success, raises ValueError if an attribute exceeds the 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

New in version 2.6.

Raises:: ValueError – One or more of the embed attributes are too long.

File¶

Attributes

bytes_length
closed
description
filename
fp
spoiler

class disnake.File(fp, filename=None, *, spoiler=False, description=None)[source]¶

A parameter object used for sending file objects.

Note

File objects are single use and are not meant to be reused in multiple abc.Messageable.send(), Message.edit(), Interaction.send(), or Interaction.edit_original_response() calls or similar methods.

fp¶

A file-like object opened in binary mode and read mode or a filename representing a file in the hard drive to open.

Note

If the file-like object passed is opened via open then the modes ‘rb’ should be used.

To pass binary data, consider usage of io.BytesIO.

Type:: os.PathLike | io.BufferedIOBase

filename¶

The filename to display when uploading to Discord. If this is not given then it defaults to fp.name or if fp is a string then the filename will default to the string given.

Type:: str | None

spoiler¶

Whether the attachment is a spoiler.

Type:: bool

description¶

The file’s description.

New in version 2.3.

Type:: str | None

property closed[source]¶

Whether the file is closed.

This is a shorthand for File.fp.closed.

New in version 2.8.

Type:: bool

property bytes_length[source]¶

The bytes length of the fp object.

New in version 2.8.

Type:: int

MessageFlags¶

Attributes

crossposted
ephemeral
failed_to_mention_roles_in_thread
has_snapshot
has_thread
is_components_v2
is_crossposted
is_voice_message
loading
source_message_deleted
suppress_embeds
suppress_notifications
urgent
value

class disnake.MessageFlags[source]¶

Wraps up a Discord Message flag value.

See SystemChannelFlags.

x == y: Checks if two MessageFlags instances are equal.

x != y: Checks if two MessageFlags instances are not equal.

x <= y: Checks if a MessageFlags instance is a subset of another MessageFlags instance.

New in version 2.6.

x >= y: Checks if a MessageFlags instance is a superset of another MessageFlags instance.

New in version 2.6.

x < y: Checks if a MessageFlags instance is a strict subset of another MessageFlags instance.

New in version 2.6.

x > y: Checks if a MessageFlags instance is a strict superset of another MessageFlags instance.

New in version 2.6.

x | y, x |= y: Returns a new MessageFlags instance with all enabled flags from both x and y. (Using |= will update in place).

New in version 2.6.

x & y, x &= y: Returns a new MessageFlags instance with only flags enabled on both x and y. (Using &= will update in place).

New in version 2.6.

x ^ y, x ^= y: Returns a new MessageFlags instance with only flags enabled on one of x or y, but not both. (Using ^= will update in place).

New in version 2.6.

~x: Returns a new MessageFlags instance with all flags from x inverted.

New in version 2.6.

hash(x): Return the flag’s hash.

iter(x): Returns an iterator of (name, value) pairs. This allows it to be, for example, constructed as a dict or a list of pairs.

Additionally supported are a few operations on class attributes.

MessageFlags.y | MessageFlags.z, MessageFlags(y=True) | MessageFlags.z: Returns a MessageFlags instance with all provided flags enabled.

New in version 2.6.

~MessageFlags.y: Returns a MessageFlags instance with all flags except y inverted from their default value.

New in version 2.6.

New in version 1.3.

value¶

The raw value. This value is a bit array field of a 53-bit integer representing the currently available flags. You should query flags via the properties rather than using this raw value.

Type:: int

crossposted¶

Returns True if the message is the original crossposted message.

Type:: bool

is_crossposted¶

Returns True if the message was crossposted from another channel.

Type:: bool

suppress_embeds¶

Returns True if the message’s embeds have been suppressed.

Type:: bool

source_message_deleted¶

Returns True if the source message for this crosspost has been deleted.

Type:: bool

urgent¶

Returns True if the message is an urgent message.

An urgent message is one sent by Discord Trust and Safety.

Type:: bool

has_thread¶

Returns True if the message is associated with a thread.

New in version 2.0.

Type:: bool

ephemeral¶

Returns True if the message is ephemeral.

New in version 2.0.

Type:: bool

loading¶

Returns True if the message is a deferred interaction response and shows a “thinking” state.

New in version 2.3.

Type:: bool

failed_to_mention_roles_in_thread¶

Returns True if the message failed to mention some roles and add their members to the thread.

New in version 2.4.

Type:: bool

suppress_notifications¶

Returns True if the message does not trigger push and desktop notifications.

New in version 2.9.

Type:: bool

is_voice_message¶

Returns True if the message is a voice message.

Messages with this flag will have a single audio attachment, and no other content.

New in version 2.9.

Type:: bool

has_snapshot¶

Returns True if the message is a forward message.

Messages with this flag will have only the forward data, and no other content.

New in version 2.10.

Type:: bool

is_components_v2¶

Returns True if the message uses the Components V2 system.

Messages with this flag will use specific components for content layout, instead of content and embeds. Further details, limits, and example images can be found in the API documentation.

Note that once this flag is set on a message, it cannot be reverted.

New in version 2.11.

Type:: bool

AttachmentFlags¶

Attributes

is_remix
value

class disnake.AttachmentFlags[source]¶

Wraps up Discord Attachment flags.

x == y: Checks if two AttachmentFlags instances are equal.

x != y: Checks if two AttachmentFlags instances are not equal.

x <= y: Checks if an AttachmentFlags instance is a subset of another AttachmentFlags instance.

x >= y: Checks if an AttachmentFlags instance is a superset of another AttachmentFlags instance.

x < y: Checks if an AttachmentFlags instance is a strict subset of another AttachmentFlags instance.

x > y: Checks if an AttachmentFlags instance is a strict superset of another AttachmentFlags instance.

x | y, x |= y: Returns a new AttachmentFlags instance with all enabled flags from both x and y. (Using |= will update in place).

x & y, x &= y: Returns a new AttachmentFlags instance with only flags enabled on both x and y. (Using &= will update in place).

x ^ y, x ^= y: Returns a new AttachmentFlags instance with only flags enabled on one of x or y, but not both. (Using ^= will update in place).

~x: Returns a new AttachmentFlags instance with all flags from x inverted.

hash(x): Returns the flag’s hash.

iter(x): Returns an iterator of (name, value) pairs. This allows it to be, for example, constructed as a dict or a list of pairs. Note that aliases are not shown.

Additionally supported are a few operations on class attributes.

AttachmentFlags.y | AttachmentFlags.z, AttachmentFlags(y=True) | AttachmentFlags.z: Returns an AttachmentFlags instance with all provided flags enabled.

~AttachmentFlags.y: Returns an AttachmentFlags instance with all flags except y inverted from their default value.

New in version 2.10.

value¶

The raw value. You should query flags via the properties rather than using this raw value.

Type:: int

is_remix¶

Returns True if the attachment has been edited using the Remix feature.

Type:: bool

AllowedMentions¶

Attributes

everyone
replied_user
roles
users

Methods

clsAllowedMentions.all
clsAllowedMentions.from_message
clsAllowedMentions.none

class disnake.AllowedMentions(*, everyone=True, users=True, roles=True, replied_user=True)[source]¶

A class that represents what mentions are allowed in a message.

This class can be set during Client initialisation to apply to every message sent. It can also be applied on a per message basis via abc.Messageable.send() for more fine-grained control.

everyone¶

Whether to allow everyone and here mentions. Defaults to True.

Type:: bool

users¶

Controls the users being mentioned. If True (the default) then users are mentioned based on the message content. If False then users are not mentioned at all. If a list of abc.Snowflake is given then only the users provided will be mentioned, provided those users are in the message content.

Type:: bool | list[abc.Snowflake]

roles¶

Controls the roles being mentioned. If True (the default) then roles are mentioned based on the message content. If False then roles are not mentioned at all. If a list of abc.Snowflake is given then only the roles provided will be mentioned, provided those roles are in the message content.

Type:: bool | list[abc.Snowflake]

replied_user¶

Whether to mention the author of the message being replied to. Defaults to True.

New in version 1.6.

Type:: bool

classmethod all()[source]¶: A factory method that returns a AllowedMentions with all fields explicitly set to True

New in version 1.5.

classmethod none()[source]¶: A factory method that returns a AllowedMentions with all fields set to False

New in version 1.5.

classmethod from_message(message)[source]¶

A factory method that returns a AllowedMentions derived from the current Message state.

Note that this is not what AllowedMentions the message was sent with, but what the message actually mentioned. For example, a message that successfully mentioned everyone will have everyone set to True.

New in version 2.6.

MessageReference¶

Attributes

cached_message
channel_id
fail_if_not_exists
guild_id
jump_url
message_id
resolved
type

Methods

clsMessageReference.from_message

class disnake.MessageReference(*, type=MessageReferenceType.default, message_id, channel_id, guild_id=None, fail_if_not_exists=True)[source]¶

Represents a reference to a Message.

New in version 1.5.

Changed in version 1.6: This class can now be constructed by users.

type¶

The type of the message reference.

New in version 2.10.

Type:: MessageReferenceType

message_id¶

The ID of the message referenced/forwarded.

Type:: int | None

channel_id¶

The channel ID of the message referenced/forwarded.

Type:: int

guild_id¶

The guild ID of the message referenced/forwarded.

Type:: int | None

fail_if_not_exists¶

Whether replying to the referenced message should raise HTTPException if the message no longer exists or Discord could not fetch the message.

New in version 1.7.

Type:: bool

resolved¶

The message that this reference resolved to. If this is None then the original message was not fetched either due to the Discord API not attempting to resolve it or it not being available at the time of creation. If the message was resolved at a prior point but has since been deleted then this will be of type DeletedReferencedMessage.

Currently, this is mainly the replied to message when a user replies to a message.

New in version 1.6.

Type:: Message | DeletedReferencedMessage | None

classmethod from_message(message, *, type=MessageReferenceType.default, fail_if_not_exists=True)[source]¶

Creates a MessageReference from an existing Message.

New in version 1.6.

Parameters:

message (Message) – The message to be converted into a reference.
type (MessageReferenceType) –
The type of the message reference. This is used to control whether to reply to or forward a message. Defaults to replying.

New in version 2.10.
fail_if_not_exists (bool) –
Whether replying to the referenced message should raise HTTPException if the message no longer exists or Discord could not fetch the message.

New in version 1.7.

Returns:

A reference to the message.

Return type:

MessageReference

property cached_message[source]¶

The cached message, if found in the internal message cache.

Type:: Message | None

property jump_url[source]¶

Returns a URL that allows the client to jump to the referenced message.

New in version 1.7.

Type:: str

PartialMessage¶

Attributes

channel
created_at
guild
id
jump_url

Methods

asyncadd_reaction
asyncclear_reaction
asyncclear_reactions
asyncdelete
asyncedit
asyncfetch
asyncforward
asyncpin
asyncpublish
asyncremove_reaction
asyncreply
defto_reference
asyncunpin

class disnake.PartialMessage(*, channel, id)[source]¶

Represents a partial message to aid with working messages when only a message and channel ID are present.

There are two ways to construct this class. The first one is through the constructor itself, and the second is via the following:

Note that this class is trimmed down and has no rich attributes.

New in version 1.6.

x == y: Checks if two partial messages are equal.

x != y: Checks if two partial messages are not equal.

hash(x): Returns the partial message’s hash.

channel¶

The channel associated with this partial message.

Type:: TextChannel | VoiceChannel | StageChannel | Thread | DMChannel | GroupChannel | PartialMessageable

id¶

The message ID.

Type:: int

property jump_url[source]¶

Returns a URL that allows the client to jump to this message.

Type:: str

await delete(*, delay=None)[source]¶

This function is a coroutine.

Deletes the message.

Your own messages could be deleted without any proper permissions. However to delete other people’s messages, you need the manage_messages permission.

Changed in version 1.1: Added the new delay keyword-only parameter.

Parameters:

delay (float | None) – If provided, the number of seconds to wait in the background before deleting the message. If the deletion fails then it is silently ignored.

Raises:

Forbidden – You do not have proper permissions to delete the message.
NotFound – The message was deleted already
HTTPException – Deleting the message failed.

await publish()[source]¶

This function is a coroutine.

Publishes this message to your announcement channel.

You must have the send_messages permission to do this.

If the message is not your own then the manage_messages permission is also needed.

Raises:

Forbidden – You do not have the proper permissions to publish this message.
HTTPException – Publishing the message failed.

await pin(*, reason=None)[source]¶

This function is a coroutine.

Pins the message.

You must have the pin_messages permission to do this in a non-private channel context.

This does not work with messages sent in a VoiceChannel or StageChannel.

Parameters:

reason (str | None) –

The reason for pinning the message. Shows up on the audit log.

New in version 1.4.

Raises:

Forbidden – You do not have permissions to pin the message.
NotFound – The message or channel was not found or deleted.
HTTPException – Pinning the message failed, probably due to the channel having more than 50 pinned messages or the channel not supporting pins.

await unpin(*, reason=None)[source]¶

This function is a coroutine.

Unpins the message.

You must have the pin_messages permission to do this in a non-private channel context.

Parameters:

reason (str | None) –

The reason for unpinning the message. Shows up on the audit log.

New in version 1.4.

Raises:

Forbidden – You do not have permissions to unpin the message.
NotFound – The message or channel was not found or deleted.
HTTPException – Unpinning the message failed.

await add_reaction(emoji)[source]¶

This function is a coroutine.

Adds a reaction to the message.

The emoji may be a unicode emoji or a custom guild Emoji.

You must have the read_message_history permission to use this. If nobody else has reacted to the message using this emoji, the add_reactions permission is required.

Changed in version 2.6: Raises TypeError instead of InvalidArgument.

Parameters:

emoji (Emoji | Reaction | PartialEmoji | str) – The emoji to react with.

Raises:

HTTPException – Adding the reaction failed.
Forbidden – You do not have the proper permissions to react to the message.
NotFound – The emoji you specified was not found.
TypeError – The emoji parameter is invalid.

await remove_reaction(emoji, member)[source]¶

This function is a coroutine.

Removes a reaction by the member from the message.

The emoji may be a unicode emoji or a custom guild Emoji.

If the reaction is not your own (i.e. member parameter is not you) then the manage_messages permission is needed.

The member parameter must represent a member and meet the abc.Snowflake abc.

Changed in version 2.6: Raises TypeError instead of InvalidArgument.

Parameters:

emoji (Emoji | Reaction | PartialEmoji | str) – The emoji to remove.
member (abc.Snowflake) – The member for which to remove the reaction.

Raises:

HTTPException – Removing the reaction failed.
Forbidden – You do not have the proper permissions to remove the reaction.
NotFound – The member or emoji you specified was not found.
TypeError – The emoji parameter is invalid.

await clear_reaction(emoji)[source]¶

This function is a coroutine.

Clears a specific reaction from the message.

The emoji may be a unicode emoji or a custom guild Emoji.

You need the manage_messages permission to use this.

New in version 1.3.

Changed in version 2.6: Raises TypeError instead of InvalidArgument.

Parameters:

emoji (Emoji | Reaction | PartialEmoji | str) – The emoji to clear.

Raises:

HTTPException – Clearing the reaction failed.
Forbidden – You do not have the proper permissions to clear the reaction.
NotFound – The emoji you specified was not found.
TypeError – The emoji parameter is invalid.

await clear_reactions()[source]¶

This function is a coroutine.

Removes all the reactions from the message.

You need the manage_messages permission to use this.

Raises:

HTTPException – Removing the reactions failed.
Forbidden – You do not have the proper permissions to remove all the reactions.

await reply(content=None, *, fail_if_not_exists=True, **kwargs)[source]¶

This function is a coroutine.

A shortcut method to abc.Messageable.send() to reply to the Message.

New in version 1.6.

Changed in version 2.3: Added fail_if_not_exists keyword argument. Defaults to True.

Changed in version 2.6: Raises TypeError or ValueError instead of InvalidArgument.

Parameters:

fail_if_not_exists (bool) –

Whether replying using the message reference should raise HTTPException if the message no longer exists or Discord could not fetch the message.

New in version 2.3.

Raises:

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message.
TypeError – You specified both embed and embeds, or file and files, or view and components.
ValueError – The files or embeds list is too large.

Returns:

The message that was sent.

Return type:

Message

to_reference(*, type=MessageReferenceType.default, fail_if_not_exists=True)[source]¶

Creates a MessageReference from the current message.

New in version 1.6.

Parameters:

type (MessageReferenceType) –
The type of the message reference. This is used to control whether to reply to or forward a message. Defaults to replying.

New in version 2.10.
fail_if_not_exists (bool) –
Whether replying using the message reference should raise HTTPException if the message no longer exists or Discord could not fetch the message.

New in version 1.7.

Returns:

The reference to this message.

Return type:

MessageReference

await forward(channel)[source]¶

This function is a coroutine.

A shortcut method to abc.Messageable.send() to forward a Message.

New in version 2.10.

Parameters:

Raises:

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message.

Returns:

The message that was sent.

Return type:

Message

property created_at[source]¶

The partial message’s creation time in UTC.

Type:: datetime.datetime

guild¶

The guild that the partial message belongs to, if applicable.

Type:: Guild | None

await fetch()[source]¶

This function is a coroutine.

Fetches the partial message to a full Message.

Raises:

NotFound – The message was not found.
Forbidden – You do not have the permissions required to get a message.
HTTPException – Retrieving the message failed.

Returns:

The full message.

Return type:

Message

This function is a coroutine.

Edits the message.

The content must be able to be transformed into a string via str(content).

Note

Changed in version 2.1: disnake.Message is always returned.

Changed in version 2.5: The suppress keyword-only parameter was deprecated in favor of suppress_embeds.

Changed in version 2.6: Raises TypeError instead of InvalidArgument.

Parameters:

content (str | None) – The new content to replace the message with. Could be None to remove the content.
embed (Embed | None) – The new embed to replace the original with. This cannot be mixed with the embeds parameter. Could be None to remove the embed.
embeds (list[Embed]) –
The new embeds to replace the original with. Must be a maximum of 10. This cannot be mixed with the embed parameter. To remove all embeds [] should be passed.

New in version 2.1.
file (File) –
The file to upload. This cannot be mixed with the files parameter. Files will be appended to the message, see the attachments parameter to remove/replace existing files.

New in version 2.1.
files (list[File]) –
A list of files to upload. This cannot be mixed with the file parameter. Files will be appended to the message, see the attachments parameter to remove/replace existing files.

New in version 2.1.
attachments (list[Attachment] | None) –
A list of attachments to keep in the message. If [] or None is passed then all existing attachments are removed. Keeps existing attachments if not provided.

New in version 2.1.

Changed in version 2.5: Supports passing None to clear attachments.
suppress_embeds (bool) – Whether to suppress embeds for the message. This hides all the embeds from the UI if set to True. If set to False, this brings the embeds back if they were suppressed.
flags (MessageFlags) –
The new flags to set for this message. Overrides existing flags. Only suppress_embeds and is_components_v2 are supported.

If parameter suppress_embeds is provided, that will override the setting of MessageFlags.suppress_embeds.

New in version 2.9.
delete_after (float | None) – If provided, the number of seconds to wait in the background before deleting the message we just edited. If the deletion fails, then it is silently ignored.
allowed_mentions (AllowedMentions | None) –
Controls the mentions being processed in this message. If this is passed, then the object is merged with Client.allowed_mentions. The merging behaviour only overrides attributes that have been explicitly passed to the object, otherwise it uses the attributes set in Client.allowed_mentions.

Note

Unlike Message.edit(), this does not default to Client.allowed_mentions if no object is passed.
view (View | None) –
The updated view to update this message with. This cannot be mixed with components. If None is passed then the view is removed.

New in version 2.0.
components (UIComponent | list[UIComponent | list[WrappedComponent]]) –
The updated components to update this message with. This cannot be mixed with view. If None is passed then the components are removed.

New in version 2.4.

Note

Passing v2 components here automatically sets the is_components_v2 flag. Setting this flag cannot be reverted. Note that this also disables the content and embeds fields. If the message previously had any of these fields set, you must set them to None.

Raises:

NotFound – The message was not found.
HTTPException – Editing the message failed.
Forbidden – Tried to suppress embeds on a message without permissions or edited a message’s content or embed that isn’t yours.
TypeError – You specified both embed and embeds, or file and files, or view and components.
ValueError – You tried to send v2 components together with content or embeds.

Returns:

The message that was edited.

Return type:

Message

Poll¶

Attributes

allow_multiselect
answers
created_at
duration
expires_at
is_finalized
layout_type
message
question
remaining_duration

Methods

asyncexpire
defget_answer

class disnake.Poll(question, *, answers, duration=datetime.timedelta(days=1), allow_multiselect=False, layout_type=PollLayoutType.default)[source]¶

Represents a poll from Discord.

New in version 2.10.

Parameters:

question (str | PollMedia) – The question of the poll. Currently, emojis are not supported in poll questions.
answers (list[str | PollAnswer]) – The answers for this poll, up to 10.
duration (datetime.timedelta) – The total duration of the poll, up to 32 days. Defaults to 1 day. Note that this gets rounded down to the closest hour.
allow_multiselect (bool) – Whether users will be able to pick more than one answer. Defaults to False.
layout_type (PollLayoutType) – The layout type of the poll. Defaults to PollLayoutType.default.

message¶

The message which contains this poll. This will be None only if this object was created manually and did not originate from the API.

Type:: Message | None

question¶

The question of the poll.

Type:: PollMedia

duration¶

The original duration for this poll. None if the poll is a non-expiring poll.

Type:: datetime.timedelta | None

allow_multiselect¶

Whether users are able to pick more than one answer.

Type:: bool

layout_type¶

The type of the layout of the poll.

Type:: PollLayoutType

is_finalized¶

Whether the votes have been precisely counted.

Type:: bool

property answers[source]¶

The list of answers for this poll.

See also get_answer() to get specific answers by ID.

Type:: list[PollAnswer]

property created_at[source]¶

When this poll was created.

None if this poll does not originate from the discord API.

Type:: datetime.datetime | None

property expires_at[source]¶

The date when this poll will expire.

None if this poll does not originate from the discord API or if this poll is non-expiring.

Type:: datetime.datetime | None

property remaining_duration[source]¶

The remaining duration for this poll. If this poll is finalized this property will arbitrarily return a zero valued timedelta.

None if this poll does not originate from the discord API.

Type:: datetime.timedelta | None

get_answer(answer_id, /)[source]¶

Return the requested poll answer.

Parameters:: answer_id (int) – The answer id.
Returns:: The requested answer.
Return type:: PollAnswer | None

await expire()[source]¶

This function is a coroutine.

Immediately ends a poll.

Note

This method works only on Poll(s) objects that originate from the API and not on the ones built manually.

Raises:

HTTPException – Expiring the poll failed.
Forbidden – Tried to expire a poll without the required permissions.
ValueError – You tried to invoke this method on an object that didn’t originate from the API.```

Returns:

The message which contains the expired Poll.

Return type:

Message

PollAnswer¶

Attributes

id
media
poll
self_voted
vote_count

Methods

defvoters

class disnake.PollAnswer(media)[source]¶

Represents a poll answer from discord.

New in version 2.10.

Parameters:: media (PollMedia) – The media object to set the text and/or emoji for this answer.

id¶

The ID of this answer. This will be None only if this object was created manually and did not originate from the API.

Type:: int | None

media¶

The media fields of this answer.

Type:: PollMedia

poll¶

The poll associated with this answer. This will be None only if this object was created manually and did not originate from the API.

Type:: Poll | None

vote_count¶

The number of votes for this answer.

Type:: int

self_voted¶

Whether the current user voted for this answer.

Type:: bool

voters(*, limit=100, after=None)[source]¶

Returns an AsyncIterator representing the users that have voted for this answer.

The after parameter must represent a member and meet the abc.Snowflake abc.

Note

This method works only on PollAnswer(s) objects that originate from the API and not on the ones built manually.

Parameters:

limit (int | None) – The maximum number of results to return. If None, retrieves every user who voted for this answer. Note, however, that this would make it a slow operation. Defaults to 100.
after (abc.Snowflake | None) – For pagination, votes are sorted by member.

Raises:

HTTPException – Getting the voters for this answer failed.
Forbidden – Tried to get the voters for this answer without the required permissions.
ValueError – You tried to invoke this method on an object that didn’t originate from the API.

Yields:

User | Member – The member (if retrievable) or the user that has voted for this answer. The case where it can be a Member is in a guild message context. Sometimes it can be a User if the member has left the guild.

PollMedia¶

Attributes

emoji
text

class disnake.PollMedia(text, *, emoji=None)[source]¶

Represents data of a poll’s question/answers.

New in version 2.10.

Parameters:

text (str) – The text of this media.
emoji (Emoji | PartialEmoji | str | None) – The emoji of this media.

text¶

The text of this media.

Type:: str | None

emoji¶

The emoji of this media.

Type:: PartialEmoji | None

ForwardedMessage¶

Attributes

attachments
channel
channel_id
components
content
created_at
edited_at
embeds
flags
guild
guild_id
mentions
role_mentions
stickers
type

class disnake.ForwardedMessage(*, state, channel_id, guild_id, data)[source]¶

Represents a forwarded Message.

New in version 2.10.

type¶

The type of message.

Type:: MessageType

content¶

The actual contents of the message.

Type:: str

embeds¶

A list of embeds the message has.

Type:: list[Embed]

channel_id¶

The ID of the channel where the message was forwarded from.

Type:: int

attachments¶

A list of attachments given to a message.

Type:: list[Attachment]

flags¶

Extra features of the message.

Type:: MessageFlags

mentions¶

Warning

The order of the mentions list is not in any particular order so you should not rely on it. This is a Discord limitation, not one with the library.

Type:: list[abc.User]

role_mentions¶

A list of Role that were mentioned. If the message is in a private message then the list is always empty.

Type:: list[Role]

stickers¶

A list of sticker items given to the message.

Type:: list[StickerItem]

components¶

A list of components in the message.

Type:: list[Component]

guild_id¶

The guild ID where the message was forwarded from, if applicable.

Type:: int | None

property guild[source]¶

The guild where the message was forwarded from, if applicable. This could be None if the guild is not cached.

Type:: disnake.Guild | None

property channel[source]¶: TextChannel | VoiceChannel | StageChannel | Thread | PartialMessageable | None: The channel that the message was forwarded from. This could be None if the channel is not cached or a disnake.PartialMessageable if the guild is not cached or if the message forwarded is not coming from a guild (e.g DMs).

property created_at[source]¶

The message’s creation time in UTC.

Type:: datetime.datetime

property edited_at[source]¶

An aware UTC datetime object containing the edited time of the message.

Type:: datetime.datetime | None

Enumerations¶

MessageType¶

class disnake.MessageType[source]¶

Specifies the type of Message. This is used to denote if a message is to be interpreted as a system message or a regular message.

default¶: The default message type. This is the same as regular messages.

recipient_add¶: The system message when a user is added to a group private message or a thread.

recipient_remove¶: The system message when a user is removed from a group private message or a thread.

call¶: The system message denoting call state, e.g. missed call, started call, etc.

channel_name_change¶: The system message denoting that a channel’s name has been changed.

channel_icon_change¶: The system message denoting that a channel’s icon has been changed.

pins_add¶: The system message denoting that a pinned message has been added to a channel.

new_member¶: The system message denoting that a new member has joined a Guild.

premium_guild_subscription¶: The system message denoting that a member has “nitro boosted” a guild.

premium_guild_tier_1¶: The system message denoting that a member has “nitro boosted” a guild and it achieved level 1.

premium_guild_tier_2¶: The system message denoting that a member has “nitro boosted” a guild and it achieved level 2.

premium_guild_tier_3¶: The system message denoting that a member has “nitro boosted” a guild and it achieved level 3.

channel_follow_add¶: The system message denoting that an announcement channel has been followed.

New in version 1.3.

guild_stream¶: The system message denoting that a member is streaming in the guild.

New in version 1.7.

guild_discovery_disqualified¶: The system message denoting that the guild is no longer eligible for Server Discovery.

New in version 1.7.

guild_discovery_requalified¶: The system message denoting that the guild has become eligible again for Server Discovery.

New in version 1.7.

guild_discovery_grace_period_initial_warning¶: The system message denoting that the guild has failed to meet the Server Discovery requirements for one week.

New in version 1.7.

guild_discovery_grace_period_final_warning¶: The system message denoting that the guild has failed to meet the Server Discovery requirements for 3 weeks in a row.

New in version 1.7.

thread_created¶: The system message denoting that a thread has been created. This is only sent if the thread has been created from an older message. The period of time required for a message to be considered old cannot be relied upon and is up to Discord.

New in version 2.0.

reply¶: The system message denoting that the author is replying to a message.

New in version 2.0.

application_command¶: The system message denoting that an application (or “slash”) command was executed.

New in version 2.0.

thread_starter_message¶: The system message denoting the message in the thread that is the one that started the thread’s conversation topic.

New in version 2.0.

guild_invite_reminder¶: The system message sent as a reminder to invite people to the guild.

New in version 2.0.

context_menu_command¶: The system message denoting that a context menu command was executed.

New in version 2.3.

auto_moderation_action¶: The system message denoting that an auto moderation action was executed.

New in version 2.5.

role_subscription_purchase¶: The system message denoting that a role subscription was purchased.

New in version 2.9.

interaction_premium_upsell¶: The system message for an application premium subscription upsell.

New in version 2.8.

stage_start¶: The system message denoting the stage has been started.

New in version 2.9.

stage_end¶: The system message denoting the stage has ended.

New in version 2.9.

stage_speaker¶: The system message denoting a user has become a speaker.

New in version 2.9.

stage_topic¶: The system message denoting the stage topic has been changed.

New in version 2.9.

guild_application_premium_subscription¶: The system message denoting that a guild member has subscribed to an application.

New in version 2.8.

guild_incident_alert_mode_enabled¶: The system message denoting that an admin enabled security actions.

New in version 2.10.

guild_incident_alert_mode_disabled¶: The system message denoting that an admin disabled security actions.

New in version 2.10.

guild_incident_report_raid¶: The system message denoting that an admin reported a raid.

New in version 2.10.

guild_incident_report_false_alarm¶: The system message denoting that a raid report was a false alarm.

New in version 2.10.

poll_result¶: The system message denoting that a poll expired, announcing the most voted answer.

New in version 2.10.

emoji_added¶: The system message denoting that an emoji was added to the server.

PollLayoutType¶

class disnake.PollLayoutType[source]¶

Specifies the layout of a Poll.

New in version 2.10.

default¶: The default poll layout type.

MessageReferenceType¶

class disnake.MessageReferenceType[source]¶

Specifies the type of MessageReference. This can be used to determine if a message is e.g. a reply or a forwarded message.

New in version 2.10.

default¶: A standard message reference used in message replies.

forward¶: Reference used to point to a message at a point in time (forward).

Messages¶

Discord Models¶

Message¶

Reaction¶

Attachment¶

DeletedReferencedMessage¶

InteractionReference¶

InteractionMetadata¶

RoleSubscriptionData¶

MessageCall¶

RawTypingEvent¶

RawMessageDeleteEvent¶

RawBulkMessageDeleteEvent¶

RawMessageUpdateEvent¶

RawPollVoteActionEvent¶

RawReactionActionEvent¶

RawReactionClearEvent¶

RawReactionClearEmojiEvent¶

Data Classes¶

Embed¶

File¶

MessageFlags¶

AttachmentFlags¶

AllowedMentions¶

MessageReference¶

PartialMessage¶

Poll¶

PollAnswer¶

PollMedia¶

ForwardedMessage¶

Enumerations¶

MessageType¶

PollLayoutType¶

MessageReferenceType¶

Events¶