Messages

This section documents everything related to Discord messages.

Discord Models

Message

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

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

Optional[Union[str, int]]

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:

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

Optional[int]

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, or message replies.

New in version 1.5.

Type:

Optional[MessageReference]

interaction

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.

Type:

Optional[InteractionReference]

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:

Optional[int]

webhook_id

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

Type:

Optional[int]

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:

Optional[dict]

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:

Optional[dict]

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:

Optional[Guild]

poll

The poll contained in this message.

New in version 2.10.

Type:

Optional[Poll]

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:

Optional[datetime.datetime]

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:

Optional[Thread]

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:

Optional[RoleSubscriptionData]

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:

Optional[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 (Optional[float]) – 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 (Optional[str]) – The new content to replace the message with. Could be None to remove the content.

  • embed (Optional[Embed]) – 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 (Optional[List[Attachment]]) –

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

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

    New in version 2.9.

  • delete_after (Optional[float]) – 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 (Optional[AllowedMentions]) –

    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 (Optional[View]) –

    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 (Union[disnake.ui.ActionRow, disnake.ui.WrappedComponent, List[Union[disnake.ui.ActionRow, disnake.ui.WrappedComponent, List[disnake.ui.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.

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.

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 manage_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 (Optional[str]) –

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 manage_messages permission to do this in a non-private channel context.

Parameters:

reason (Optional[str]) –

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 (Union[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:
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 (Union[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 (Union[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 (Optional[int]) –

    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 (Optional[str]) –

    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:

channel (Union[TextChannel, VoiceChannel, StageChannel, Thread, DMChannel, GroupChannel, PartialMessageable]) – The channel where the message should be forwarded to.

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: 0>, 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
Methods
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:

Union[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 (Optional[int]) – The maximum number of results to return. If not provided, returns all the users who reacted to the message.

  • after (Optional[abc.Snowflake]) – For pagination, reactions are sorted by member.

Raises:

HTTPException – Getting the users for the reaction failed.

Yields:

Union[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
Methods
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:

Optional[int]

width

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

Type:

Optional[int]

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:

Optional[str]

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:

Optional[str]

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:

Optional[float]

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:

Optional[bytes]

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 (Union[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:
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 (Optional[str]) –

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

Optional[int]

InteractionReference

Attributes
class disnake.InteractionReference(*, state, guild, data)[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.

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:

Union[User, Member]

RoleSubscriptionData

Attributes
class disnake.RoleSubscriptionData(data)[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.

See also RoleTags.subscription_listing_id.

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

RawTypingEvent

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

Optional[int]

member

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

Type:

Optional[Member]

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

Optional[int]

message_id

The message ID that got deleted.

Type:

int

cached_message

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

Type:

Optional[Message]

RawBulkMessageDeleteEvent

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

Optional[int]

cached_messages

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

Type:

List[Message]

RawMessageUpdateEvent

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

Optional[int]

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:

Optional[Message]

RawPollVoteActionEvent

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

Optional[Member]

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:

Optional[int]

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

Optional[int]

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:

Optional[Member]

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:

Optional[int]

RawReactionClearEvent

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

Optional[int]

RawReactionClearEmojiEvent

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

Optional[int]

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

Optional[str]

type

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

Type:

Optional[str]

description

The description of the embed.

Type:

Optional[str]

url

The URL of the embed.

Type:

Optional[str]

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:

Optional[datetime.datetime]

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:

Optional[Colour]

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.

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 (Optional[str]) – 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.

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 (Optional[str]) – 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 (Optional[str]) – 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 (Optional[str]) – The URL for the author.

  • icon_url (Optional[str]) – 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:

Optional[Colour]

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:

Optional[Colour]

classmethod get_default_colour()[source]

Get the default colour of all new embeds.

New in version 2.4.

Returns:

The default colour.

Return type:

Optional[Colour]

classmethod get_default_color()[source]

Get the default colour of all new embeds.

New in version 2.4.

Returns:

The default colour.

Return type:

Optional[Colour]

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

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

Optional[str]

spoiler

Whether the attachment is a spoiler.

Type:

bool

description

The file’s description.

New in version 2.3.

Type:

Optional[str]

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

AttachmentFlags

Attributes
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 a AttachmentFlags instance with all provided flags enabled.

~AttachmentFlags.y

Returns a 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
Methods
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:

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

Union[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
Methods
class disnake.MessageReference(*, type=<MessageReferenceType.default: 0>, 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:

Optional[int]

channel_id

The channel ID of the message referenced/forwarded.

Type:

int

guild_id

The guild ID of the message referenced/forwarded.

Type:

Optional[int]

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:

Optional[Union[Message, DeletedReferencedMessage]]

classmethod from_message(message, *, type=<MessageReferenceType.default: 0>, 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:

Optional[Message]

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

Union[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 (Optional[float]) – 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 manage_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 (Optional[str]) –

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 manage_messages permission to do this in a non-private channel context.

Parameters:

reason (Optional[str]) –

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 (Union[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:
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 (Union[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: 0>, 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:

channel (Union[TextChannel, VoiceChannel, StageChannel, Thread, DMChannel, GroupChannel, PartialMessageable]) – The channel where the message should be forwarded to.

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:

Optional[Guild]

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

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 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 (Optional[str]) – The new content to replace the message with. Could be None to remove the content.

  • embed (Optional[Embed]) – 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 (Optional[List[Attachment]]) –

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

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

    New in version 2.9.

  • delete_after (Optional[float]) – 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 (Optional[AllowedMentions]) –

    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 (Optional[View]) –

    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 (Union[disnake.ui.ActionRow, disnake.ui.WrappedComponent, List[Union[disnake.ui.ActionRow, disnake.ui.WrappedComponent, List[disnake.ui.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.

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.

Returns:

The message that was edited.

Return type:

Message

Poll

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

Represents a poll from Discord.

New in version 2.10.

Parameters:

  • question (Union[str, PollMedia]) – The question of the poll. Currently, emojis are not supported in poll questions.

  • answers (List[Union[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:

Optional[Message]

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:

Optional[datetime.timedelta]

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:

Optional[datetime.datetime]

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:

Optional[datetime.datetime]

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:

Optional[datetime.timedelta]

get_answer(answer_id, /)[source]

Return the requested poll answer.

Parameters:

answer_id (int) – The answer id.

Returns:

The requested answer.

Return type:

Optional[PollAnswer]

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

Optional[int]

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:

Optional[Poll]

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 (Optional[int]) – 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 (Optional[abc.Snowflake]) – 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:

Union[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
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 (Optional[Union[Emoji, PartialEmoji, str]]) – The emoji of this media.

text

The text of this media.

Type:

Optional[str]

emoji

The emoji of this media.

Type:

Optional[PartialEmoji]

ForwardedMessage

Attributes
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

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

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:

Optional[int]

property guild[source]

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

Type:

Optional[disnake.Guild]

property channel[source]

Optional[Union[TextChannel, VoiceChannel, StageChannel, Thread, PartialMessageable]]: 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:

Optional[datetime.datetime]

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.

x == y

Checks if two messages are equal.

x != y

Checks if two messages are not equal.

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.

guild_invite_reminder

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

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.

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.

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

Events