Channels

This section documents everything related to channels and threads.

Discord Models

TextChannel

Attributes
Methods
class disnake.TextChannel[source]

This class is a Discord Model.

Represents a Discord guild text channel.

x == y

Checks if two channels are equal.

x != y

Checks if two channels are not equal.

hash(x)

Returns the channel’s hash.

str(x)

Returns the channel’s name.

name

The channel’s name.

Type:

str

guild

The guild the channel belongs to.

Type:

Guild

id

The channel’s ID.

Type:

int

category_id

The category channel ID this channel belongs to, if applicable.

Type:

Optional[int]

topic

The channel’s topic. None if it doesn’t exist.

Type:

Optional[str]

position

The position in the channel list. This is a number that starts at 0. e.g. the top channel is position 0.

Type:

int

last_message_id

The last message ID of the message sent to this channel. It may not point to an existing or valid message.

Type:

Optional[int]

slowmode_delay

The number of seconds a member must wait between sending messages in this channel. A value of 0 denotes that it is disabled. Bots, and users with manage_channels or manage_messages permissions, bypass slowmode.

Type:

int

nsfw

Whether the channel is marked as “not safe for work”.

Note

To check if the channel or the guild of that channel are marked as NSFW, consider is_nsfw() instead.

Type:

bool

default_auto_archive_duration

The default auto archive duration in minutes for threads created in this channel.

New in version 2.0.

Type:

int

last_pin_timestamp

The time the most recent message was pinned, or None if no message is currently pinned.

New in version 2.5.

Type:

Optional[datetime.datetime]

async for ... in history(*, limit=100, before=None, after=None, around=None, oldest_first=None)[source]

Returns an AsyncIterator that enables receiving the destination’s message history.

You must have Permissions.read_message_history permission to use this.

Examples

Usage

counter = 0
async for message in channel.history(limit=200):
    if message.author == client.user:
        counter += 1

Flattening into a list:

messages = await channel.history(limit=123).flatten()
# messages is now a list of Message...

All parameters are optional.

Parameters:

  • limit (Optional[int]) – The number of messages to retrieve. If None, retrieves every message in the channel. Note, however, that this would make it a slow operation.

  • before (Optional[Union[abc.Snowflake, datetime.datetime]]) – Retrieve messages before this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

  • after (Optional[Union[abc.Snowflake, datetime.datetime]]) – Retrieve messages after this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

  • around (Optional[Union[abc.Snowflake, datetime.datetime]]) – Retrieve messages around this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time. When using this argument, the maximum limit is 101. Note that if the limit is an even number then this will return at most limit + 1 messages.

  • oldest_first (Optional[bool]) – If set to True, return messages in oldest->newest order. Defaults to True if after is specified, otherwise False.

Raises:

  • Forbidden – You do not have permissions to get channel message history.

  • HTTPException – The request to get message history failed.

Yields:

Message – The message with the message data parsed.

async with typing()[source]

Returns a context manager that allows you to type for an indefinite period of time.

This is useful for denoting long computations in your bot.

Note

This is both a regular context manager and an async context manager. This means that both with and async with work with this.

Example Usage:

async with channel.typing():
    # simulate something heavy
    await asyncio.sleep(10)

await channel.send('done!')
property type[source]

The channel’s Discord type.

This always returns ChannelType.text or ChannelType.news.

Type:

ChannelType

permissions_for(obj, /, *, ignore_timeout=...)[source]

Handles permission resolution for the Member or Role.

This function takes into consideration the following cases:

  • Guild owner

  • Guild roles

  • Channel overrides

  • Member overrides

  • Timeouts

If a Role is passed, then it checks the permissions someone with that role would have, which is essentially:

  • The default role permissions

  • The permissions of the role used as a parameter

  • The default role permission overwrites

  • The permission overwrites of the role used as a parameter

Changed in version 2.0: The object passed in can now be a role object.

Parameters:

  • obj (Union[Member, Role]) – The object to resolve permissions for. This could be either a member or a role. If it’s a role then member overwrites are not computed.

  • ignore_timeout (bool) –

    Whether or not to ignore the user’s timeout. Defaults to False.

    New in version 2.4.

    Note

    This only applies to Member objects.

    Changed in version 2.6: The default was changed to False.

Raises:

TypeError – ignore_timeout is only supported for Member objects.

Returns:

The resolved permissions for the member or role.

Return type:

Permissions

property members[source]

Returns all members that can see this channel.

Type:

List[Member]

property threads[source]

Returns all the threads that you can see.

New in version 2.0.

Type:

List[Thread]

is_nsfw()[source]

Whether the channel is marked as NSFW.

Return type:

bool

is_news()[source]

Whether the channel is a news channel.

Return type:

bool

property last_message[source]

Gets the last message in this channel from the cache.

The message might not be valid or point to an existing message.

Reliable Fetching

For a slightly more reliable method of fetching the last message, consider using either history() or fetch_message() with the last_message_id attribute.

Returns:

The last message in this channel or None if not found.

Return type:

Optional[Message]

await edit(*, name=..., topic=..., position=..., nsfw=..., sync_permissions=..., category=..., slowmode_delay=..., default_auto_archive_duration=..., type=..., overwrites=..., flags=..., reason=None, **kwargs)[source]

This function is a coroutine.

Edits the channel.

You must have manage_channels permission to do this.

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

Changed in version 1.4: The type keyword-only parameter was added.

Changed in version 2.0: Edits are no longer in-place, the newly edited channel is returned instead.

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

Parameters:

  • name (str) – The new channel’s name.

  • topic (Optional[str]) – The new channel’s topic.

  • position (int) – The new channel’s position.

  • nsfw (bool) – Whether to mark the channel as NSFW.

  • sync_permissions (bool) – Whether to sync permissions with the channel’s new or pre-existing category. Defaults to False.

  • category (Optional[abc.Snowflake]) – The new category for this channel. Can be None to remove the category.

  • slowmode_delay (Optional[int]) – Specifies the slowmode rate limit for users in this channel, in seconds. A value of 0 disables slowmode. The maximum value possible is 21600.

  • type (ChannelType) – The new type of this text channel. Currently, only conversion between ChannelType.text and ChannelType.news is supported. This is only available to guilds that contain NEWS in Guild.features.

  • overwrites (Mapping) – A Mapping of target (either a role or a member) to PermissionOverwrite to apply to the channel.

  • default_auto_archive_duration (Optional[Union[int, ThreadArchiveDuration]]) – The new default auto archive duration in minutes for threads created in this channel. Must be one of 60, 1440, 4320, or 10080.

  • flags (ChannelFlags) –

    The new flags to set for this channel. This will overwrite any existing flags set on this channel.

    New in version 2.6.

  • reason (Optional[str]) – The reason for editing this channel. Shows up on the audit log.

Raises:

  • Forbidden – You do not have permissions to edit the channel.

  • HTTPException – Editing the channel failed.

  • TypeError – The permission overwrite information is not in proper form.

  • ValueError – The position is less than 0.

Returns:

The newly edited text channel. If the edit was only positional then None is returned instead.

Return type:

Optional[TextChannel]

await clone(*, name=None, reason=None)[source]

This function is a coroutine.

Clones this channel. This creates a channel with the same properties as this channel.

You must have Permissions.manage_channels permission to do this.

New in version 1.1.

Parameters:

  • name (Optional[str]) – The name of the new channel. If not provided, defaults to this channel name.

  • reason (Optional[str]) – The reason for cloning this channel. Shows up on the audit log.

Raises:

  • Forbidden – You do not have the proper permissions to create this channel.

  • HTTPException – Creating the channel failed.

Returns:

The channel that was created.

Return type:

abc.GuildChannel

await delete_messages(messages)[source]

This function is a coroutine.

Deletes a list of messages. This is similar to Message.delete() except it bulk deletes multiple messages.

As a special case, if the number of messages is 0, then nothing is done. If the number of messages is 1 then single message delete is done. If it’s more than two, then bulk delete is used.

You cannot bulk delete more than 100 messages or messages that are older than 14 days.

You must have manage_messages permission to do this.

Parameters:

messages (Iterable[abc.Snowflake]) – An iterable of messages denoting which ones to bulk delete.

Raises:

  • ClientException – The number of messages to delete was more than 100.

  • Forbidden – You do not have proper permissions to delete the messages.

  • NotFound – If single delete, then the message was already deleted.

  • HTTPException – Deleting the messages failed.

await purge(*, limit=100, check=..., before=None, after=None, around=None, oldest_first=False, bulk=True)[source]

This function is a coroutine.

Purges a list of messages that meet the criteria given by the predicate check. If a check is not provided then all messages are deleted without discrimination.

You must have manage_messages permission to delete messages even if they are your own. read_message_history permission is also needed to retrieve message history.

Examples

Deleting bot’s messages

def is_me(m):
    return m.author == client.user

deleted = await channel.purge(limit=100, check=is_me)
await channel.send(f'Deleted {len(deleted)} message(s)')
Parameters:
Raises:

  • Forbidden – You do not have proper permissions to do the actions required.

  • HTTPException – Purging the messages failed.

Returns:

A list of messages that were deleted.

Return type:

List[Message]

await webhooks()[source]

This function is a coroutine.

Retrieves the list of webhooks this channel has.

You must have manage_webhooks permission to use this.

Raises:

Forbidden – You don’t have permissions to get the webhooks.

Returns:

The list of webhooks this channel has.

Return type:

List[Webhook]

await create_webhook(*, name, avatar=None, reason=None)[source]

This function is a coroutine.

Creates a webhook for this channel.

You must have manage_webhooks permission to do this.

Changed in version 1.1: The reason keyword-only parameter was added.

Parameters:

  • name (str) – The webhook’s name.

  • avatar (Optional[Union[bytes, Asset, Emoji, PartialEmoji, StickerItem, Sticker]]) –

    The webhook’s default avatar. This operates similarly to edit().

    Changed in version 2.5: Now accepts various resource types in addition to bytes.

  • reason (Optional[str]) – The reason for creating this webhook. Shows up in the audit logs.

Raises:
Returns:

The newly created webhook.

Return type:

Webhook

await follow(*, destination, reason=None)[source]

This function is a coroutine.

Follows a channel using a webhook.

Only news channels can be followed.

Note

The webhook returned will not provide a token to do webhook actions, as Discord does not provide it.

New in version 1.3.

Changed in version 2.6: Raises TypeError instead of InvalidArgument.

Parameters:

  • destination (TextChannel) – The channel you would like to follow from.

  • reason (Optional[str]) –

    The reason for following the channel. Shows up on the destination guild’s audit log.

    New in version 1.4.

Raises:

  • HTTPException – Following the channel failed.

  • Forbidden – You do not have the permissions to create a webhook.

  • TypeError – The current or provided channel is not of the correct type.

Returns:

The newly created webhook.

Return type:

Webhook

get_partial_message(message_id, /)[source]

Creates a PartialMessage from the given message ID.

This is useful if you want to work with a message and only have its ID without doing an unnecessary API call.

New in version 1.6.

Parameters:

message_id (int) – The message ID to create a partial message for.

Returns:

The partial message object.

Return type:

PartialMessage

get_thread(thread_id, /)[source]

Returns a thread with the given ID.

New in version 2.0.

Parameters:

thread_id (int) – The ID to search for.

Returns:

The returned thread or None if not found.

Return type:

Optional[Thread]

await create_thread(*, name, message=None, auto_archive_duration=None, type=None, invitable=None, slowmode_delay=None, reason=None)[source]

This function is a coroutine.

Creates a thread in this text channel.

To create a public thread, you must have create_public_threads permission. For a private thread, create_private_threads permission is needed instead. Additionally, the guild must have PRIVATE_THREADS in Guild.features to create private threads.

New in version 2.0.

Changed in version 2.5:

  • Only one of message and type may be provided.

  • type is now required if message is not provided.

Parameters:

  • name (str) – The name of the thread.

  • message (abc.Snowflake) –

    A snowflake representing the message to create the thread with.

    Changed in version 2.5: Cannot be provided with type.

  • type (ChannelType) –

    The type of thread to create.

    Changed in version 2.5: Cannot be provided with message. Now required if message is not provided.

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

  • invitable (bool) –

    Whether non-moderators can add other non-moderators to this thread. Only available for private threads. If a message is passed then this parameter is ignored, as a thread created with a message is always a public thread. Defaults to True.

    New in version 2.3.

  • slowmode_delay (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 not provided, slowmode is disabled.

    New in version 2.3.

  • reason (Optional[str]) – The reason for creating the thread. Shows up on the audit log.

Raises:
Returns:

The newly created thread

Return type:

Thread

archived_threads(*, private=False, joined=False, limit=50, before=None)[source]

Returns an AsyncIterator that iterates over all archived threads in the channel.

You must have read_message_history permission to use this. If iterating over private threads then manage_threads permission is also required.

New in version 2.0.

Parameters:

  • limit (Optional[int]) – The number of threads to retrieve. If None, retrieves every archived thread in the channel. Note, however, that this would make it a slow operation.

  • before (Optional[Union[abc.Snowflake, datetime.datetime]]) – Retrieve archived channels before the given date or ID.

  • private (bool) – Whether to retrieve private archived threads.

  • joined (bool) – Whether to retrieve private archived threads that you’ve joined. You cannot set joined to True and private to False.

Raises:

  • Forbidden – You do not have permissions to get archived threads.

  • HTTPException – The request to get the archived threads failed.

Yields:

Thread – The archived threads.

property category[source]

The category this channel belongs to.

If there is no category then this is None.

Type:

Optional[CategoryChannel]

property changed_roles[source]

Returns a list of roles that have been overridden from their default values in the Guild.roles attribute.

Type:

List[Role]

await create_invite(*, reason=None, max_age=0, max_uses=0, temporary=False, unique=True, target_type=None, target_user=None, target_application=None, guild_scheduled_event=None)[source]

This function is a coroutine.

Creates an instant invite from a text or voice channel.

You must have Permissions.create_instant_invite permission to do this.

Parameters:

  • max_age (int) – How long the invite should last in seconds. If it’s 0 then the invite doesn’t expire. Defaults to 0.

  • max_uses (int) – How many uses the invite could be used for. If it’s 0 then there are unlimited uses. Defaults to 0.

  • temporary (bool) – Whether the invite grants temporary membership (i.e. they get kicked after they disconnect). Defaults to False.

  • unique (bool) – Whether a unique invite URL should be created. Defaults to True. If this is set to False then it will return a previously created invite.

  • target_type (Optional[InviteTarget]) –

    The type of target for the voice channel invite, if any.

    New in version 2.0.

  • target_user (Optional[User]) –

    The user whose stream to display for this invite, required if target_type is TargetType.stream. The user must be streaming in the channel.

    New in version 2.0.

  • target_application (Optional[PartyType]) –

    The ID of the embedded application for the invite, required if target_type is TargetType.embedded_application.

    New in version 2.0.

  • guild_scheduled_event (Optional[GuildScheduledEvent]) –

    The guild scheduled event to include with the invite.

    New in version 2.3.

  • reason (Optional[str]) – The reason for creating this invite. Shows up on the audit log.

Raises:

  • HTTPException – Invite creation failed.

  • NotFound – The channel that was passed is a category or an invalid channel.

Returns:

The newly created invite.

Return type:

Invite

property created_at[source]

Returns the channel’s creation time in UTC.

Type:

datetime.datetime

await delete(*, reason=None)[source]

This function is a coroutine.

Deletes the channel.

You must have Permissions.manage_channels permission to do this.

Parameters:

reason (Optional[str]) – The reason for deleting this channel. Shows up on the audit log.

Raises:

  • Forbidden – You do not have proper permissions to delete the channel.

  • NotFound – The channel was not found or was already deleted.

  • HTTPException – Deleting the channel failed.

await fetch_message(id, /)[source]

This function is a coroutine.

Retrieves a single Message from the destination.

Parameters:

id (int) – The message ID to look for.

Raises:

  • NotFound – The specified message was not found.

  • Forbidden – You do not have the permissions required to get a message.

  • HTTPException – Retrieving the message failed.

Returns:

The message asked for.

Return type:

Message

property flags[source]

The channel flags for this channel.

New in version 2.6.

Type:

ChannelFlags

await invites()[source]

This function is a coroutine.

Returns a list of all active instant invites from this channel.

You must have Permissions.manage_channels permission to use this.

Raises:

  • Forbidden – You do not have proper permissions to get the information.

  • HTTPException – An error occurred while fetching the information.

Returns:

The list of invites that are currently active.

Return type:

List[Invite]

property jump_url[source]

A URL that can be used to jump to this channel.

New in version 2.4.

Note

This exists for all guild channels but may not be usable by the client for all guild channel types.

property mention[source]

The string that allows you to mention the channel.

Type:

str

await move(**kwargs)[source]

This function is a coroutine.

A rich interface to help move a channel relative to other channels.

If exact position movement is required, edit should be used instead.

You must have Permissions.manage_channels permission to do this.

Note

Voice channels will always be sorted below text channels. This is a Discord limitation.

New in version 1.7.

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

Parameters:

  • beginning (bool) – Whether to move the channel to the beginning of the channel list (or category if given). This is mutually exclusive with end, before, and after.

  • end (bool) – Whether to move the channel to the end of the channel list (or category if given). This is mutually exclusive with beginning, before, and after.

  • before (abc.Snowflake) – The channel that should be before our current channel. This is mutually exclusive with beginning, end, and after.

  • after (abc.Snowflake) – The channel that should be after our current channel. This is mutually exclusive with beginning, end, and before.

  • offset (int) – The number of channels to offset the move by. For example, an offset of 2 with beginning=True would move it 2 after the beginning. A positive number moves it below while a negative number moves it above. Note that this number is relative and computed after the beginning, end, before, and after parameters.

  • category (Optional[abc.Snowflake]) – The category to move this channel under. If None is given then it moves it out of the category. This parameter is ignored if moving a category channel.

  • sync_permissions (bool) – Whether to sync the permissions with the category (if given).

  • reason (Optional[str]) – The reason for moving this channel. Shows up on the audit log.

Raises:

  • Forbidden – You do not have permissions to move the channel.

  • HTTPException – Moving the channel failed.

  • TypeError – A bad mix of arguments were passed.

  • ValueError – An invalid position was given.

property overwrites[source]

Returns all of the channel’s overwrites.

This is returned as a dictionary where the key contains the target which can be either a Role or a Member and the value is the overwrite as a PermissionOverwrite.

Returns:

The channel’s permission overwrites.

Return type:

Dict[Union[Role, Member], PermissionOverwrite]

overwrites_for(obj)[source]

Returns the channel-specific overwrites for a member or a role.

Parameters:

obj (Union[Role, abc.User]) – The role or user denoting whose overwrite to get.

Returns:

The permission overwrites for this object.

Return type:

PermissionOverwrite

property permissions_synced[source]

Whether or not the permissions for this channel are synced with the category it belongs to.

If there is no category then this is False.

New in version 1.3.

Type:

bool

await pins()[source]

This function is a coroutine.

Retrieves all messages that are currently pinned in the channel.

Note

Due to a limitation with the Discord API, the Message objects returned by this method do not contain complete Message.reactions data.

Raises:

HTTPException – Retrieving the pinned messages failed.

Returns:

The messages that are currently pinned.

Return type:

List[Message]

await send(content=None, *, tts=False, embed=None, embeds=None, file=None, files=None, stickers=None, delete_after=None, nonce=None, suppress_embeds=False, allowed_mentions=None, reference=None, mention_author=None, view=None, components=None)[source]

This function is a coroutine.

Sends a message to the destination with the content given.

The content must be a type that can convert to a string through str(content).

At least one of content, embed/embeds, file/files, stickers, components, or view must be provided.

To upload a single file, the file parameter should be used with a single File object. To upload multiple files, the files parameter should be used with a list of File objects. Specifying both parameters will lead to an exception.

To upload a single embed, the embed parameter should be used with a single Embed object. To upload multiple embeds, the embeds parameter should be used with a list of Embed objects. Specifying both parameters will lead to an exception.

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

Parameters:

  • content (Optional[str]) – The content of the message to send.

  • tts (bool) – Whether the message should be sent using text-to-speech.

  • embed (Embed) – The rich embed for the content to send. This cannot be mixed with the embeds parameter.

  • embeds (List[Embed]) –

    A list of embeds to send with the content. Must be a maximum of 10. This cannot be mixed with the embed parameter.

    New in version 2.0.

  • file (File) – The file to upload. This cannot be mixed with the files parameter.

  • files (List[File]) – A list of files to upload. Must be a maximum of 10. This cannot be mixed with the file parameter.

  • stickers (Sequence[Union[GuildSticker, StickerItem]]) –

    A list of stickers to upload. Must be a maximum of 3.

    New in version 2.0.

  • nonce (Union[str, int]) – The nonce to use for sending this message. If the message was successfully sent, then the message will have a nonce with this value.

  • delete_after (float) – If provided, the number of seconds to wait in the background before deleting the message we just sent. If the deletion fails, then it is silently ignored.

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

  • reference (Union[Message, MessageReference, PartialMessage]) –

    A reference to the Message to which you are replying, this can be created using Message.to_reference() or passed directly as a Message. You can control whether this mentions the author of the referenced message using the AllowedMentions.replied_user attribute of allowed_mentions or by setting mention_author.

    New in version 1.6.

  • mention_author (Optional[bool]) –

    If set, overrides the AllowedMentions.replied_user attribute of allowed_mentions.

    New in version 1.6.

  • view (ui.View) –

    A Discord UI View to add to the message. This cannot be mixed with components.

    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]]]]) –

    A list of components to include in the message. This cannot be mixed with view.

    New in version 2.4.

  • suppress_embeds (bool) –

    Whether to suppress embeds for the message. This hides all embeds from the UI if set to True.

    New in version 2.5.

Raises:
Returns:

The message that was sent.

Return type:

Message

await set_permissions(target, *, overwrite=..., reason=None, **permissions)[source]

This function is a coroutine.

Sets the channel specific permission overwrites for a target in the channel.

The target parameter should either be a Member or a Role that belongs to guild.

The overwrite parameter, if given, must either be None or PermissionOverwrite. For convenience, you can pass in keyword arguments denoting Permissions attributes. If this is done, then you cannot mix the keyword arguments with the overwrite parameter.

If the overwrite parameter is None, then the permission overwrites are deleted.

You must have Permissions.manage_roles permission to do this.

Note

This method replaces the old overwrites with the ones given.

Changed in version 2.6: Raises TypeError instead of InvalidArgument.

Examples

Setting allow and deny:

await message.channel.set_permissions(message.author, view_channel=True,
                                                      send_messages=False)

Deleting overwrites

await channel.set_permissions(member, overwrite=None)

Using PermissionOverwrite

overwrite = disnake.PermissionOverwrite()
overwrite.send_messages = False
overwrite.view_channel = True
await channel.set_permissions(member, overwrite=overwrite)
Parameters:

  • target (Union[Member, Role]) – The member or role to overwrite permissions for.

  • overwrite (Optional[PermissionOverwrite]) – The permissions to allow and deny to the target, or None to delete the overwrite.

  • **permissions – A keyword argument list of permissions to set for ease of use. Cannot be mixed with overwrite.

  • reason (Optional[str]) – The reason for doing this action. Shows up on the audit log.

Raises:

  • Forbidden – You do not have permissions to edit channel specific permissions.

  • HTTPException – Editing channel specific permissions failed.

  • NotFound – The role or member being edited is not part of the guild.

  • TypeError – overwrite is invalid, the target type was not Role or Member, both keyword arguments and overwrite were provided, or invalid permissions were provided as keyword arguments.

await trigger_typing()[source]

This function is a coroutine.

Triggers a typing indicator to the destination.

Typing indicator will go away after 10 seconds, or after a message is sent.

VoiceChannel

Attributes
Methods
class disnake.VoiceChannel[source]

This class is a Discord Model.

Represents a Discord guild voice channel.

x == y

Checks if two channels are equal.

x != y

Checks if two channels are not equal.

hash(x)

Returns the channel’s hash.

str(x)

Returns the channel’s name.

name

The channel’s name.

Type:

str

guild

The guild the channel belongs to.

Type:

Guild

id

The channel’s ID.

Type:

int

category_id

The category channel ID this channel belongs to, if applicable.

Type:

Optional[int]

position

The position in the channel list. This is a number that starts at 0. e.g. the top channel is position 0.

Type:

int

bitrate

The channel’s preferred audio bitrate in bits per second.

Type:

int

user_limit

The channel’s limit for number of members that can be in a voice channel.

Type:

int

rtc_region

The region for the voice channel’s voice communication. A value of None indicates automatic voice region detection.

New in version 1.7.

Changed in version 2.5: No longer a VoiceRegion instance.

Type:

Optional[str]

video_quality_mode

The camera video quality for the voice channel’s participants.

Type:

VideoQualityMode

nsfw

Whether the channel is marked as “not safe for work”.

Note

To check if the channel or the guild of that channel are marked as NSFW, consider is_nsfw() instead.

New in version 2.3.

Type:

bool

slowmode_delay

The number of seconds a member must wait between sending messages in this channel. A value of 0 denotes that it is disabled. Bots, and users with manage_channels or manage_messages, bypass slowmode.

New in version 2.3.

Type:

int

last_message_id

The last message ID of the message sent to this channel. It may not point to an existing or valid message.

New in version 2.3.

Type:

Optional[int]

property type[source]

The channel’s Discord type.

This always returns ChannelType.voice.

Type:

ChannelType

await clone(*, name=None, reason=None)[source]

This function is a coroutine.

Clones this channel. This creates a channel with the same properties as this channel.

You must have Permissions.manage_channels permission to do this.

New in version 1.1.

Parameters:

  • name (Optional[str]) – The name of the new channel. If not provided, defaults to this channel name.

  • reason (Optional[str]) – The reason for cloning this channel. Shows up on the audit log.

Raises:

  • Forbidden – You do not have the proper permissions to create this channel.

  • HTTPException – Creating the channel failed.

Returns:

The channel that was created.

Return type:

abc.GuildChannel

is_nsfw()[source]

Whether the channel is marked as NSFW.

New in version 2.3.

Return type:

bool

property last_message[source]

Gets the last message in this channel from the cache.

The message might not be valid or point to an existing message.

Reliable Fetching

For a slightly more reliable method of fetching the last message, consider using either history() or fetch_message() with the last_message_id attribute.

New in version 2.3.

Returns:

The last message in this channel or None if not found.

Return type:

Optional[Message]

get_partial_message(message_id, /)[source]

Creates a PartialMessage from the given message ID.

This is useful if you want to work with a message and only have its ID without doing an unnecessary API call.

New in version 2.3.

Parameters:

message_id (int) – The message ID to create a partial message for.

Returns:

The partial message object.

Return type:

PartialMessage

permissions_for(obj, /, *, ignore_timeout=...)[source]

Handles permission resolution for the Member or Role.

This function takes into consideration the following cases:

  • Guild owner

  • Guild roles

  • Channel overrides

  • Member overrides

  • Timeouts

If a Role is passed, then it checks the permissions someone with that role would have, which is essentially:

  • The default role permissions

  • The permissions of the role used as a parameter

  • The default role permission overwrites

  • The permission overwrites of the role used as a parameter

Changed in version 2.0: The object passed in can now be a role object.

Parameters:

  • obj (Union[Member, Role]) – The object to resolve permissions for. This could be either a member or a role. If it’s a role then member overwrites are not computed.

  • ignore_timeout (bool) –

    Whether or not to ignore the user’s timeout. Defaults to False.

    New in version 2.4.

    Note

    This only applies to Member objects.

    Changed in version 2.6: The default was changed to False.

Raises:

TypeError – ignore_timeout is only supported for Member objects.

Returns:

The resolved permissions for the member or role.

Return type:

Permissions

await edit(*, name=..., bitrate=..., user_limit=..., position=..., sync_permissions=..., category=..., overwrites=..., rtc_region=..., video_quality_mode=..., nsfw=..., slowmode_delay=..., flags=..., reason=None, **kwargs)[source]

This function is a coroutine.

Edits the channel.

You must have manage_channels permission to do this.

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

Changed in version 2.0: Edits are no longer in-place, the newly edited channel is returned instead.

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

Parameters:

  • name (str) – The new channel’s name.

  • bitrate (int) – The new channel’s bitrate.

  • user_limit (int) – The new channel’s user limit.

  • position (int) – The new channel’s position.

  • sync_permissions (bool) – Whether to sync permissions with the channel’s new or pre-existing category. Defaults to False.

  • category (Optional[abc.Snowflake]) – The new category for this channel. Can be None to remove the category.

  • reason (Optional[str]) – The reason for editing this channel. Shows up on the audit log.

  • overwrites (Mapping) – A Mapping of target (either a role or a member) to PermissionOverwrite to apply to the channel.

  • rtc_region (Optional[Union[str, VoiceRegion]]) –

    The new region for the voice channel’s voice communication. A value of None indicates automatic voice region detection.

    New in version 1.7.

  • video_quality_mode (VideoQualityMode) –

    The camera video quality for the voice channel’s participants.

    New in version 2.0.

  • nsfw (bool) –

    Whether to mark the channel as NSFW.

    New in version 2.3.

  • slowmode_delay (Optional[int]) –

    Specifies the slowmode rate limit for users in this channel, in seconds. A value of 0 disables slowmode. The maximum value possible is 21600.

    New in version 2.3.

  • flags (ChannelFlags) –

    The new flags to set for this channel. This will overwrite any existing flags set on this channel.

    New in version 2.6.

Raises:

  • Forbidden – You do not have permissions to edit the channel.

  • HTTPException – Editing the channel failed.

  • TypeError – The permission overwrite information is not in proper form.

  • ValueError – The position is less than 0.

Returns:

The newly edited voice channel. If the edit was only positional then None is returned instead.

Return type:

Optional[VoiceChannel]

await delete_messages(messages)[source]

This function is a coroutine.

Deletes a list of messages. This is similar to Message.delete() except it bulk deletes multiple messages.

As a special case, if the number of messages is 0, then nothing is done. If the number of messages is 1 then single message delete is done. If it’s more than two, then bulk delete is used.

You cannot bulk delete more than 100 messages or messages that are older than 14 days.

You must have manage_messages permission to do this.

New in version 2.5.

Parameters:

messages (Iterable[abc.Snowflake]) – An iterable of messages denoting which ones to bulk delete.

Raises:

  • ClientException – The number of messages to delete was more than 100.

  • Forbidden – You do not have proper permissions to delete the messages.

  • NotFound – If single delete, then the message was already deleted.

  • HTTPException – Deleting the messages failed.

await purge(*, limit=100, check=..., before=None, after=None, around=None, oldest_first=False, bulk=True)[source]

This function is a coroutine.

Purges a list of messages that meet the criteria given by the predicate check. If a check is not provided then all messages are deleted without discrimination.

You must have manage_messages permission to delete messages even if they are your own. read_message_history permission is also needed to retrieve message history.

New in version 2.5.

Note

See TextChannel.purge() for examples.

Parameters:
Raises:

  • Forbidden – You do not have proper permissions to do the actions required.

  • HTTPException – Purging the messages failed.

Returns:

A list of messages that were deleted.

Return type:

List[Message]

await webhooks()[source]

This function is a coroutine.

Retrieves the list of webhooks this channel has.

You must have manage_webhooks permission to use this.

New in version 2.5.

Raises:

Forbidden – You don’t have permissions to get the webhooks.

Returns:

The list of webhooks this channel has.

Return type:

List[Webhook]

await create_webhook(*, name, avatar=None, reason=None)[source]

This function is a coroutine.

Creates a webhook for this channel.

You must have manage_webhooks permission to do this.

New in version 2.5.

Parameters:

  • name (str) – The webhook’s name.

  • avatar (Optional[bytes]) – The webhook’s default avatar. This operates similarly to edit().

  • reason (Optional[str]) – The reason for creating this webhook. Shows up in the audit logs.

Raises:
Returns:

The newly created webhook.

Return type:

Webhook

property category[source]

The category this channel belongs to.

If there is no category then this is None.

Type:

Optional[CategoryChannel]

property changed_roles[source]

Returns a list of roles that have been overridden from their default values in the Guild.roles attribute.

Type:

List[Role]

await connect(*, timeout=60.0, reconnect=True, cls=<class 'disnake.voice_client.VoiceClient'>)[source]

This function is a coroutine.

Connects to voice and creates a VoiceClient to establish your connection to the voice server.

This requires Intents.voice_states.

Parameters:

  • timeout (float) – The timeout in seconds to wait for the voice endpoint.

  • reconnect (bool) – Whether the bot should automatically attempt a reconnect if a part of the handshake fails or the gateway goes down.

  • cls (Type[VoiceProtocol]) – A type that subclasses VoiceProtocol to connect with. Defaults to VoiceClient.

Raises:
Returns:

A voice client that is fully connected to the voice server.

Return type:

VoiceProtocol

await create_invite(*, reason=None, max_age=0, max_uses=0, temporary=False, unique=True, target_type=None, target_user=None, target_application=None, guild_scheduled_event=None)[source]

This function is a coroutine.

Creates an instant invite from a text or voice channel.

You must have Permissions.create_instant_invite permission to do this.

Parameters:

  • max_age (int) – How long the invite should last in seconds. If it’s 0 then the invite doesn’t expire. Defaults to 0.

  • max_uses (int) – How many uses the invite could be used for. If it’s 0 then there are unlimited uses. Defaults to 0.

  • temporary (bool) – Whether the invite grants temporary membership (i.e. they get kicked after they disconnect). Defaults to False.

  • unique (bool) – Whether a unique invite URL should be created. Defaults to True. If this is set to False then it will return a previously created invite.

  • target_type (Optional[InviteTarget]) –

    The type of target for the voice channel invite, if any.

    New in version 2.0.

  • target_user (Optional[User]) –

    The user whose stream to display for this invite, required if target_type is TargetType.stream. The user must be streaming in the channel.

    New in version 2.0.

  • target_application (Optional[PartyType]) –

    The ID of the embedded application for the invite, required if target_type is TargetType.embedded_application.

    New in version 2.0.

  • guild_scheduled_event (Optional[GuildScheduledEvent]) –

    The guild scheduled event to include with the invite.

    New in version 2.3.

  • reason (Optional[str]) – The reason for creating this invite. Shows up on the audit log.

Raises:

  • HTTPException – Invite creation failed.

  • NotFound – The channel that was passed is a category or an invalid channel.

Returns:

The newly created invite.

Return type:

Invite

property created_at[source]

Returns the channel’s creation time in UTC.

Type:

datetime.datetime

await delete(*, reason=None)[source]

This function is a coroutine.

Deletes the channel.

You must have Permissions.manage_channels permission to do this.

Parameters:

reason (Optional[str]) – The reason for deleting this channel. Shows up on the audit log.

Raises:

  • Forbidden – You do not have proper permissions to delete the channel.

  • NotFound – The channel was not found or was already deleted.

  • HTTPException – Deleting the channel failed.

await fetch_message(id, /)[source]

This function is a coroutine.

Retrieves a single Message from the destination.

Parameters:

id (int) – The message ID to look for.

Raises:

  • NotFound – The specified message was not found.

  • Forbidden – You do not have the permissions required to get a message.

  • HTTPException – Retrieving the message failed.

Returns:

The message asked for.

Return type:

Message

property flags[source]

The channel flags for this channel.

New in version 2.6.

Type:

ChannelFlags

history(*, limit=100, before=None, after=None, around=None, oldest_first=None)[source]

Returns an AsyncIterator that enables receiving the destination’s message history.

You must have Permissions.read_message_history permission to use this.

Examples

Usage

counter = 0
async for message in channel.history(limit=200):
    if message.author == client.user:
        counter += 1

Flattening into a list:

messages = await channel.history(limit=123).flatten()
# messages is now a list of Message...

All parameters are optional.

Parameters:

  • limit (Optional[int]) – The number of messages to retrieve. If None, retrieves every message in the channel. Note, however, that this would make it a slow operation.

  • before (Optional[Union[abc.Snowflake, datetime.datetime]]) – Retrieve messages before this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

  • after (Optional[Union[abc.Snowflake, datetime.datetime]]) – Retrieve messages after this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

  • around (Optional[Union[abc.Snowflake, datetime.datetime]]) – Retrieve messages around this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time. When using this argument, the maximum limit is 101. Note that if the limit is an even number then this will return at most limit + 1 messages.

  • oldest_first (Optional[bool]) – If set to True, return messages in oldest->newest order. Defaults to True if after is specified, otherwise False.

Raises:

  • Forbidden – You do not have permissions to get channel message history.

  • HTTPException – The request to get message history failed.

Yields:

Message – The message with the message data parsed.

await invites()[source]

This function is a coroutine.

Returns a list of all active instant invites from this channel.

You must have Permissions.manage_channels permission to use this.

Raises:

  • Forbidden – You do not have proper permissions to get the information.

  • HTTPException – An error occurred while fetching the information.

Returns:

The list of invites that are currently active.

Return type:

List[Invite]

property jump_url[source]

A URL that can be used to jump to this channel.

New in version 2.4.

Note

This exists for all guild channels but may not be usable by the client for all guild channel types.

property members[source]

Returns all members that are currently inside this voice channel.

Type:

List[Member]

property mention[source]

The string that allows you to mention the channel.

Type:

str

await move(**kwargs)[source]

This function is a coroutine.

A rich interface to help move a channel relative to other channels.

If exact position movement is required, edit should be used instead.

You must have Permissions.manage_channels permission to do this.

Note

Voice channels will always be sorted below text channels. This is a Discord limitation.

New in version 1.7.

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

Parameters:

  • beginning (bool) – Whether to move the channel to the beginning of the channel list (or category if given). This is mutually exclusive with end, before, and after.

  • end (bool) – Whether to move the channel to the end of the channel list (or category if given). This is mutually exclusive with beginning, before, and after.

  • before (abc.Snowflake) – The channel that should be before our current channel. This is mutually exclusive with beginning, end, and after.

  • after (abc.Snowflake) – The channel that should be after our current channel. This is mutually exclusive with beginning, end, and before.

  • offset (int) – The number of channels to offset the move by. For example, an offset of 2 with beginning=True would move it 2 after the beginning. A positive number moves it below while a negative number moves it above. Note that this number is relative and computed after the beginning, end, before, and after parameters.

  • category (Optional[abc.Snowflake]) – The category to move this channel under. If None is given then it moves it out of the category. This parameter is ignored if moving a category channel.

  • sync_permissions (bool) – Whether to sync the permissions with the category (if given).

  • reason (Optional[str]) – The reason for moving this channel. Shows up on the audit log.

Raises:

  • Forbidden – You do not have permissions to move the channel.

  • HTTPException – Moving the channel failed.

  • TypeError – A bad mix of arguments were passed.

  • ValueError – An invalid position was given.

property overwrites[source]

Returns all of the channel’s overwrites.

This is returned as a dictionary where the key contains the target which can be either a Role or a Member and the value is the overwrite as a PermissionOverwrite.

Returns:

The channel’s permission overwrites.

Return type:

Dict[Union[Role, Member], PermissionOverwrite]

overwrites_for(obj)[source]

Returns the channel-specific overwrites for a member or a role.

Parameters:

obj (Union[Role, abc.User]) – The role or user denoting whose overwrite to get.

Returns:

The permission overwrites for this object.

Return type:

PermissionOverwrite

property permissions_synced[source]

Whether or not the permissions for this channel are synced with the category it belongs to.

If there is no category then this is False.

New in version 1.3.

Type:

bool

await pins()[source]

This function is a coroutine.

Retrieves all messages that are currently pinned in the channel.

Note

Due to a limitation with the Discord API, the Message objects returned by this method do not contain complete Message.reactions data.

Raises:

HTTPException – Retrieving the pinned messages failed.

Returns:

The messages that are currently pinned.

Return type:

List[Message]

await send(content=None, *, tts=False, embed=None, embeds=None, file=None, files=None, stickers=None, delete_after=None, nonce=None, suppress_embeds=False, allowed_mentions=None, reference=None, mention_author=None, view=None, components=None)[source]

This function is a coroutine.

Sends a message to the destination with the content given.

The content must be a type that can convert to a string through str(content).

At least one of content, embed/embeds, file/files, stickers, components, or view must be provided.

To upload a single file, the file parameter should be used with a single File object. To upload multiple files, the files parameter should be used with a list of File objects. Specifying both parameters will lead to an exception.

To upload a single embed, the embed parameter should be used with a single Embed object. To upload multiple embeds, the embeds parameter should be used with a list of Embed objects. Specifying both parameters will lead to an exception.

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

Parameters:

  • content (Optional[str]) – The content of the message to send.

  • tts (bool) – Whether the message should be sent using text-to-speech.

  • embed (Embed) – The rich embed for the content to send. This cannot be mixed with the embeds parameter.

  • embeds (List[Embed]) –

    A list of embeds to send with the content. Must be a maximum of 10. This cannot be mixed with the embed parameter.

    New in version 2.0.

  • file (File) – The file to upload. This cannot be mixed with the files parameter.

  • files (List[File]) – A list of files to upload. Must be a maximum of 10. This cannot be mixed with the file parameter.

  • stickers (Sequence[Union[GuildSticker, StickerItem]]) –

    A list of stickers to upload. Must be a maximum of 3.

    New in version 2.0.

  • nonce (Union[str, int]) – The nonce to use for sending this message. If the message was successfully sent, then the message will have a nonce with this value.

  • delete_after (float) – If provided, the number of seconds to wait in the background before deleting the message we just sent. If the deletion fails, then it is silently ignored.

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

  • reference (Union[Message, MessageReference, PartialMessage]) –

    A reference to the Message to which you are replying, this can be created using Message.to_reference() or passed directly as a Message. You can control whether this mentions the author of the referenced message using the AllowedMentions.replied_user attribute of allowed_mentions or by setting mention_author.

    New in version 1.6.

  • mention_author (Optional[bool]) –

    If set, overrides the AllowedMentions.replied_user attribute of allowed_mentions.

    New in version 1.6.

  • view (ui.View) –

    A Discord UI View to add to the message. This cannot be mixed with components.

    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]]]]) –

    A list of components to include in the message. This cannot be mixed with view.

    New in version 2.4.

  • suppress_embeds (bool) –

    Whether to suppress embeds for the message. This hides all embeds from the UI if set to True.

    New in version 2.5.

Raises:
Returns:

The message that was sent.

Return type:

Message

await set_permissions(target, *, overwrite=..., reason=None, **permissions)[source]

This function is a coroutine.

Sets the channel specific permission overwrites for a target in the channel.

The target parameter should either be a Member or a Role that belongs to guild.

The overwrite parameter, if given, must either be None or PermissionOverwrite. For convenience, you can pass in keyword arguments denoting Permissions attributes. If this is done, then you cannot mix the keyword arguments with the overwrite parameter.

If the overwrite parameter is None, then the permission overwrites are deleted.

You must have Permissions.manage_roles permission to do this.

Note

This method replaces the old overwrites with the ones given.

Changed in version 2.6: Raises TypeError instead of InvalidArgument.

Examples

Setting allow and deny:

await message.channel.set_permissions(message.author, view_channel=True,
                                                      send_messages=False)

Deleting overwrites

await channel.set_permissions(member, overwrite=None)

Using PermissionOverwrite

overwrite = disnake.PermissionOverwrite()
overwrite.send_messages = False
overwrite.view_channel = True
await channel.set_permissions(member, overwrite=overwrite)
Parameters:

  • target (Union[Member, Role]) – The member or role to overwrite permissions for.

  • overwrite (Optional[PermissionOverwrite]) – The permissions to allow and deny to the target, or None to delete the overwrite.

  • **permissions – A keyword argument list of permissions to set for ease of use. Cannot be mixed with overwrite.

  • reason (Optional[str]) – The reason for doing this action. Shows up on the audit log.

Raises:

  • Forbidden – You do not have permissions to edit channel specific permissions.

  • HTTPException – Editing channel specific permissions failed.

  • NotFound – The role or member being edited is not part of the guild.

  • TypeError – overwrite is invalid, the target type was not Role or Member, both keyword arguments and overwrite were provided, or invalid permissions were provided as keyword arguments.

await trigger_typing()[source]

This function is a coroutine.

Triggers a typing indicator to the destination.

Typing indicator will go away after 10 seconds, or after a message is sent.

typing()[source]

Returns a context manager that allows you to type for an indefinite period of time.

This is useful for denoting long computations in your bot.

Note

This is both a regular context manager and an async context manager. This means that both with and async with work with this.

Example Usage:

async with channel.typing():
    # simulate something heavy
    await asyncio.sleep(10)

await channel.send('done!')
property voice_states[source]

Returns a mapping of member IDs who have voice states in this channel.

New in version 1.3.

Note

This function is intentionally low level to replace members when the member cache is unavailable.

Returns:

The mapping of member ID to a voice state.

Return type:

Mapping[int, VoiceState]

CategoryChannel

Attributes
Methods
class disnake.CategoryChannel[source]

This class is a Discord Model.

Represents a Discord channel category.

These are useful to group channels to logical compartments.

x == y

Checks if two channels are equal.

x != y

Checks if two channels are not equal.

hash(x)

Returns the category’s hash.

str(x)

Returns the category’s name.

name

The category name.

Type:

str

guild

The guild the category belongs to.

Type:

Guild

id

The category channel ID.

Type:

int

position

The position in the category list. This is a number that starts at 0. e.g. the top category is position 0.

Type:

int

nsfw

If the channel is marked as “not safe for work”.

Note

To check if the channel or the guild of that channel are marked as NSFW, consider is_nsfw() instead.

Type:

bool

property type[source]

The channel’s Discord type.

This always returns ChannelType.category.

Type:

ChannelType

is_nsfw()[source]

Whether the category is marked as NSFW.

Return type:

bool

await clone(*, name=None, reason=None)[source]

This function is a coroutine.

Clones this channel. This creates a channel with the same properties as this channel.

You must have Permissions.manage_channels permission to do this.

New in version 1.1.

Parameters:

  • name (Optional[str]) – The name of the new channel. If not provided, defaults to this channel name.

  • reason (Optional[str]) – The reason for cloning this channel. Shows up on the audit log.

Raises:

  • Forbidden – You do not have the proper permissions to create this channel.

  • HTTPException – Creating the channel failed.

Returns:

The channel that was created.

Return type:

abc.GuildChannel

await edit(*, name=..., position=..., nsfw=..., overwrites=..., flags=..., reason=None, **kwargs)[source]

This function is a coroutine.

Edits the category.

You must have manage_channels permission to do this.

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

Changed in version 2.0: Edits are no longer in-place, the newly edited channel is returned instead.

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

Parameters:

  • name (str) – The new category’s name.

  • position (int) – The new category’s position.

  • nsfw (bool) – Whether to mark the category as NSFW.

  • overwrites (Mapping) – A Mapping of target (either a role or a member) to PermissionOverwrite to apply to the category.

  • flags (ChannelFlags) –

    The new flags to set for this channel. This will overwrite any existing flags set on this channel.

    New in version 2.6.

  • reason (Optional[str]) – The reason for editing this category. Shows up on the audit log.

Raises:

  • Forbidden – You do not have permissions to edit the category.

  • HTTPException – Editing the category failed.

  • TypeError – The permission overwrite information is not in proper form.

  • ValueError – The position is less than 0.

Returns:

The newly edited category channel. If the edit was only positional then None is returned instead.

Return type:

Optional[CategoryChannel]

await move(**kwargs)[source]

This function is a coroutine.

A rich interface to help move a channel relative to other channels.

If exact position movement is required, edit should be used instead.

You must have Permissions.manage_channels permission to do this.

Note

Voice channels will always be sorted below text channels. This is a Discord limitation.

New in version 1.7.

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

Parameters:

  • beginning (bool) – Whether to move the channel to the beginning of the channel list (or category if given). This is mutually exclusive with end, before, and after.

  • end (bool) – Whether to move the channel to the end of the channel list (or category if given). This is mutually exclusive with beginning, before, and after.

  • before (abc.Snowflake) – The channel that should be before our current channel. This is mutually exclusive with beginning, end, and after.

  • after (abc.Snowflake) – The channel that should be after our current channel. This is mutually exclusive with beginning, end, and before.

  • offset (int) – The number of channels to offset the move by. For example, an offset of 2 with beginning=True would move it 2 after the beginning. A positive number moves it below while a negative number moves it above. Note that this number is relative and computed after the beginning, end, before, and after parameters.

  • category (Optional[abc.Snowflake]) – The category to move this channel under. If None is given then it moves it out of the category. This parameter is ignored if moving a category channel.

  • sync_permissions (bool) – Whether to sync the permissions with the category (if given).

  • reason (Optional[str]) – The reason for moving this channel. Shows up on the audit log.

Raises:

  • Forbidden – You do not have permissions to move the channel.

  • HTTPException – Moving the channel failed.

  • TypeError – A bad mix of arguments were passed.

  • ValueError – An invalid position was given.

property channels[source]

Returns the channels that are under this category.

These are sorted by the official Discord UI, which places voice channels below the text channels.

Type:

List[abc.GuildChannel]

property text_channels[source]

Returns the text channels that are under this category.

Type:

List[TextChannel]

property voice_channels[source]

Returns the voice channels that are under this category.

Type:

List[VoiceChannel]

property stage_channels[source]

Returns the stage channels that are under this category.

New in version 1.7.

Type:

List[StageChannel]

property forum_channels[source]

Returns the forum channels that are under this category.

New in version 2.5.

Type:

List[ForumChannel]

await create_text_channel(name, **options)[source]

This function is a coroutine.

A shortcut method to Guild.create_text_channel() to create a TextChannel in the category.

Returns:

The newly created text channel.

Return type:

TextChannel

await create_voice_channel(name, **options)[source]

This function is a coroutine.

A shortcut method to Guild.create_voice_channel() to create a VoiceChannel in the category.

Returns:

The newly created voice channel.

Return type:

VoiceChannel

await create_stage_channel(name, **options)[source]

This function is a coroutine.

A shortcut method to Guild.create_stage_channel() to create a StageChannel in the category.

New in version 1.7.

Returns:

The newly created stage channel.

Return type:

StageChannel

await create_forum_channel(name, **options)[source]

This function is a coroutine.

A shortcut method to Guild.create_forum_channel() to create a ForumChannel in the category.

New in version 2.5.

Returns:

The newly created forum channel.

Return type:

ForumChannel

property category[source]

The category this channel belongs to.

If there is no category then this is None.

Type:

Optional[CategoryChannel]

property changed_roles[source]

Returns a list of roles that have been overridden from their default values in the Guild.roles attribute.

Type:

List[Role]

await create_invite(*, reason=None, max_age=0, max_uses=0, temporary=False, unique=True, target_type=None, target_user=None, target_application=None, guild_scheduled_event=None)[source]

This function is a coroutine.

Creates an instant invite from a text or voice channel.

You must have Permissions.create_instant_invite permission to do this.

Parameters:

  • max_age (int) – How long the invite should last in seconds. If it’s 0 then the invite doesn’t expire. Defaults to 0.

  • max_uses (int) – How many uses the invite could be used for. If it’s 0 then there are unlimited uses. Defaults to 0.

  • temporary (bool) – Whether the invite grants temporary membership (i.e. they get kicked after they disconnect). Defaults to False.

  • unique (bool) – Whether a unique invite URL should be created. Defaults to True. If this is set to False then it will return a previously created invite.

  • target_type (Optional[InviteTarget]) –

    The type of target for the voice channel invite, if any.

    New in version 2.0.

  • target_user (Optional[User]) –

    The user whose stream to display for this invite, required if target_type is TargetType.stream. The user must be streaming in the channel.

    New in version 2.0.

  • target_application (Optional[PartyType]) –

    The ID of the embedded application for the invite, required if target_type is TargetType.embedded_application.

    New in version 2.0.

  • guild_scheduled_event (Optional[GuildScheduledEvent]) –

    The guild scheduled event to include with the invite.

    New in version 2.3.

  • reason (Optional[str]) – The reason for creating this invite. Shows up on the audit log.

Raises:

  • HTTPException – Invite creation failed.

  • NotFound – The channel that was passed is a category or an invalid channel.

Returns:

The newly created invite.

Return type:

Invite

property created_at[source]

Returns the channel’s creation time in UTC.

Type:

datetime.datetime

await delete(*, reason=None)[source]

This function is a coroutine.

Deletes the channel.

You must have Permissions.manage_channels permission to do this.

Parameters:

reason (Optional[str]) – The reason for deleting this channel. Shows up on the audit log.

Raises:

  • Forbidden – You do not have proper permissions to delete the channel.

  • NotFound – The channel was not found or was already deleted.

  • HTTPException – Deleting the channel failed.

property flags[source]

The channel flags for this channel.

New in version 2.6.

Type:

ChannelFlags

await invites()[source]

This function is a coroutine.

Returns a list of all active instant invites from this channel.

You must have Permissions.manage_channels permission to use this.

Raises:

  • Forbidden – You do not have proper permissions to get the information.

  • HTTPException – An error occurred while fetching the information.

Returns:

The list of invites that are currently active.

Return type:

List[Invite]

property jump_url[source]

A URL that can be used to jump to this channel.

New in version 2.4.

Note

This exists for all guild channels but may not be usable by the client for all guild channel types.

property mention[source]

The string that allows you to mention the channel.

Type:

str

property overwrites[source]

Returns all of the channel’s overwrites.

This is returned as a dictionary where the key contains the target which can be either a Role or a Member and the value is the overwrite as a PermissionOverwrite.

Returns:

The channel’s permission overwrites.

Return type:

Dict[Union[Role, Member], PermissionOverwrite]

overwrites_for(obj)[source]

Returns the channel-specific overwrites for a member or a role.

Parameters:

obj (Union[Role, abc.User]) – The role or user denoting whose overwrite to get.

Returns:

The permission overwrites for this object.

Return type:

PermissionOverwrite

permissions_for(obj, /, *, ignore_timeout=...)[source]

Handles permission resolution for the Member or Role.

This function takes into consideration the following cases:

  • Guild owner

  • Guild roles

  • Channel overrides

  • Member overrides

  • Timeouts

If a Role is passed, then it checks the permissions someone with that role would have, which is essentially:

  • The default role permissions

  • The permissions of the role used as a parameter

  • The default role permission overwrites

  • The permission overwrites of the role used as a parameter

Changed in version 2.0: The object passed in can now be a role object.

Parameters:

  • obj (Union[Member, Role]) – The object to resolve permissions for. This could be either a member or a role. If it’s a role then member overwrites are not computed.

  • ignore_timeout (bool) –

    Whether or not to ignore the user’s timeout. Defaults to False.

    New in version 2.4.

    Note

    This only applies to Member objects.

    Changed in version 2.6: The default was changed to False.

Raises:

TypeError – ignore_timeout is only supported for Member objects.

Returns:

The resolved permissions for the member or role.

Return type:

Permissions

property permissions_synced[source]

Whether or not the permissions for this channel are synced with the category it belongs to.

If there is no category then this is False.

New in version 1.3.

Type:

bool

await set_permissions(target, *, overwrite=..., reason=None, **permissions)[source]

This function is a coroutine.

Sets the channel specific permission overwrites for a target in the channel.

The target parameter should either be a Member or a Role that belongs to guild.

The overwrite parameter, if given, must either be None or PermissionOverwrite. For convenience, you can pass in keyword arguments denoting Permissions attributes. If this is done, then you cannot mix the keyword arguments with the overwrite parameter.

If the overwrite parameter is None, then the permission overwrites are deleted.

You must have Permissions.manage_roles permission to do this.

Note

This method replaces the old overwrites with the ones given.

Changed in version 2.6: Raises TypeError instead of InvalidArgument.

Examples

Setting allow and deny:

await message.channel.set_permissions(message.author, view_channel=True,
                                                      send_messages=False)

Deleting overwrites

await channel.set_permissions(member, overwrite=None)

Using PermissionOverwrite

overwrite = disnake.PermissionOverwrite()
overwrite.send_messages = False
overwrite.view_channel = True
await channel.set_permissions(member, overwrite=overwrite)
Parameters:

  • target (Union[Member, Role]) – The member or role to overwrite permissions for.

  • overwrite (Optional[PermissionOverwrite]) – The permissions to allow and deny to the target, or None to delete the overwrite.

  • **permissions – A keyword argument list of permissions to set for ease of use. Cannot be mixed with overwrite.

  • reason (Optional[str]) – The reason for doing this action. Shows up on the audit log.

Raises:

  • Forbidden – You do not have permissions to edit channel specific permissions.

  • HTTPException – Editing channel specific permissions failed.

  • NotFound – The role or member being edited is not part of the guild.

  • TypeError – overwrite is invalid, the target type was not Role or Member, both keyword arguments and overwrite were provided, or invalid permissions were provided as keyword arguments.

Thread

Attributes
Methods
class disnake.Thread[source]

This class is a Discord Model.

Represents a Discord thread.

x == y

Checks if two threads are equal.

x != y

Checks if two threads are not equal.

hash(x)

Returns the thread’s hash.

str(x)

Returns the thread’s name.

New in version 2.0.

name

The thread name.

Type:

str

guild

The guild the thread belongs to.

Type:

Guild

id

The thread ID.

Type:

int

parent_id

The parent TextChannel or ForumChannel ID this thread belongs to.

Type:

int

owner_id

The user’s ID that created this thread.

Type:

Optional[int]

last_message_id

The last message ID of the message sent to this thread. It may not point to an existing or valid message.

Type:

Optional[int]

slowmode_delay

The number of seconds a member must wait between sending messages in this thread. A value of 0 denotes that it is disabled. Bots, and users with manage_channels or manage_messages, bypass slowmode.

Type:

int

message_count

An approximate number of messages in this thread.

Note

If the thread was created before July 1, 2022, this could be inaccurate.

Type:

Optional[int]

member_count

An approximate number of members in this thread. This caps at 50.

Type:

Optional[int]

total_message_sent

The total number of messages sent in the thread, including deleted messages.

New in version 2.6.

Note

If the thread was created before July 1, 2022, this could be inaccurate.

Type:

Optional[int]

me

A thread member representing yourself, if you’ve joined the thread. This could not be available.

Type:

Optional[ThreadMember]

archived

Whether the thread is archived.

Type:

bool

locked

Whether the thread is locked.

Type:

bool

invitable

Whether non-moderators can add other non-moderators to this thread. This is always True for public threads.

Type:

bool

auto_archive_duration

The duration in minutes until the thread is automatically archived due to inactivity. Usually a value of 60, 1440, 4320 and 10080.

Type:

int

archive_timestamp

An aware timestamp of when the thread’s archived status was last updated in UTC.

Type:

datetime.datetime

create_timestamp

An aware timestamp of when the thread was created in UTC. This is only available for threads created after 2022-01-09.

New in version 2.4.

Type:

Optional[datetime.datetime]

last_pin_timestamp

The time the most recent message was pinned, or None if no message is currently pinned.

New in version 2.5.

Type:

Optional[datetime.datetime]

async for ... in history(*, limit=100, before=None, after=None, around=None, oldest_first=None)[source]

Returns an AsyncIterator that enables receiving the destination’s message history.

You must have Permissions.read_message_history permission to use this.

Examples

Usage

counter = 0
async for message in channel.history(limit=200):
    if message.author == client.user:
        counter += 1

Flattening into a list:

messages = await channel.history(limit=123).flatten()
# messages is now a list of Message...

All parameters are optional.

Parameters:

  • limit (Optional[int]) – The number of messages to retrieve. If None, retrieves every message in the channel. Note, however, that this would make it a slow operation.

  • before (Optional[Union[abc.Snowflake, datetime.datetime]]) – Retrieve messages before this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

  • after (Optional[Union[abc.Snowflake, datetime.datetime]]) – Retrieve messages after this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

  • around (Optional[Union[abc.Snowflake, datetime.datetime]]) – Retrieve messages around this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time. When using this argument, the maximum limit is 101. Note that if the limit is an even number then this will return at most limit + 1 messages.

  • oldest_first (Optional[bool]) – If set to True, return messages in oldest->newest order. Defaults to True if after is specified, otherwise False.

Raises:

  • Forbidden – You do not have permissions to get channel message history.

  • HTTPException – The request to get message history failed.

Yields:

Message – The message with the message data parsed.

async with typing()[source]

Returns a context manager that allows you to type for an indefinite period of time.

This is useful for denoting long computations in your bot.

Note

This is both a regular context manager and an async context manager. This means that both with and async with work with this.

Example Usage:

async with channel.typing():
    # simulate something heavy
    await asyncio.sleep(10)

await channel.send('done!')
property type[source]

The channel’s Discord type.

This always returns ChannelType.public_thread, ChannelType.private_thread, or ChannelType.news_thread.

Type:

ChannelType

property parent[source]

The parent channel this thread belongs to.

Type:

Optional[Union[TextChannel, ForumChannel]]

property owner[source]

The member this thread belongs to.

Type:

Optional[Member]

property mention[source]

The string that allows you to mention the thread.

Type:

str

property members[source]

A list of thread members in this thread.

This requires Intents.members to be properly filled. Most of the time however, this data is not provided by the gateway and a call to fetch_members() is needed.

Type:

List[ThreadMember]

property last_message[source]

Gets the last message in this channel from the cache.

The message might not be valid or point to an existing message.

Reliable Fetching

For a slightly more reliable method of fetching the last message, consider using either history() or fetch_message() with the last_message_id attribute.

Returns:

The last message in this channel or None if not found.

Return type:

Optional[Message]

property category[source]

The category channel the parent channel belongs to, if applicable.

Raises:

ClientException – The parent channel was not cached and returned None.

Returns:

The parent channel’s category.

Return type:

Optional[CategoryChannel]

property category_id[source]

The category channel ID the parent channel belongs to, if applicable.

Raises:

ClientException – The parent channel was not cached and returned None.

Returns:

The parent channel’s category ID.

Return type:

Optional[int]

property created_at[source]

Returns the thread’s creation time in UTC.

Changed in version 2.4: If create_timestamp is provided by discord, that will be used instead of the time in the ID.

Type:

datetime.datetime

property flags[source]

The channel flags for this thread.

New in version 2.5.

Type:

ChannelFlags

property jump_url[source]

A URL that can be used to jump to this thread.

New in version 2.4.

is_private()[source]

Whether the thread is a private thread.

A private thread is only viewable by those that have been explicitly invited or have manage_threads.

Return type:

bool

is_news()[source]

Whether the thread is a news thread.

A news thread is a thread that has a parent that is a news channel, i.e. TextChannel.is_news() is True.

Return type:

bool

is_nsfw()[source]

Whether the thread is NSFW or not.

An NSFW thread is a thread that has a parent that is an NSFW channel, i.e. TextChannel.is_nsfw() is True.

Return type:

bool

is_pinned()[source]

Whether the thread is pinned in a ForumChannel

Pinned threads are not affected by the auto archive duration.

This is a shortcut to self.flags.pinned.

New in version 2.5.

Return type:

bool

property applied_tags[source]

The tags currently applied to this thread. Only applicable to threads in ForumChannels.

New in version 2.6.

Type:

List[ForumTag]

permissions_for(obj, /, *, ignore_timeout=...)[source]

Handles permission resolution for the Member or Role.

Since threads do not have their own permissions, they inherit them from the parent channel. This is a convenience method for calling permissions_for() on the parent channel.

Parameters:

  • obj (Union[Member, Role]) – The object to resolve permissions for. This could be either a member or a role. If it’s a role then member overwrites are not computed.

  • ignore_timeout (bool) –

    Whether or not to ignore the user’s timeout. Defaults to False.

    New in version 2.4.

    Note

    This only applies to Member objects.

    Changed in version 2.6: The default was changed to False.

Raises:

ClientException – The parent channel was not cached and returned None

Returns:

The resolved permissions for the member or role.

Return type:

Permissions

await delete_messages(messages)[source]

This function is a coroutine.

Deletes a list of messages. This is similar to Message.delete() except it bulk deletes multiple messages.

As a special case, if the number of messages is 0, then nothing is done. If the number of messages is 1 then single message delete is done. If it’s more than two, then bulk delete is used.

You cannot bulk delete more than 100 messages or messages that are older than 14 days old.

You must have the manage_messages permission to use this.

Usable only by bot accounts.

Parameters:

messages (Iterable[abc.Snowflake]) – An iterable of messages denoting which ones to bulk delete.

Raises:

  • ClientException – The number of messages to delete was more than 100.

  • Forbidden – You do not have proper permissions to delete the messages or you’re not using a bot account.

  • NotFound – If single delete, then the message was already deleted.

  • HTTPException – Deleting the messages failed.

await purge(*, limit=100, check=..., before=None, after=None, around=None, oldest_first=False, bulk=True)[source]

This function is a coroutine.

Purges a list of messages that meet the criteria given by the predicate check. If a check is not provided then all messages are deleted without discrimination.

You must have the manage_messages permission to delete messages even if they are your own (unless you are a user account). The read_message_history permission is also needed to retrieve message history.

Examples

Deleting bot’s messages

def is_me(m):
    return m.author == client.user

deleted = await thread.purge(limit=100, check=is_me)
await thread.send(f'Deleted {len(deleted)} message(s)')
Parameters:
Raises:

  • Forbidden – You do not have proper permissions to do the actions required.

  • HTTPException – Purging the messages failed.

Returns:

The list of messages that were deleted.

Return type:

List[Message]

await edit(*, name=..., archived=..., locked=..., invitable=..., slowmode_delay=..., auto_archive_duration=..., pinned=..., flags=..., applied_tags=..., reason=None)[source]

This function is a coroutine.

Edits the thread.

Editing the thread requires Permissions.manage_threads. The thread creator can also edit name, archived, auto_archive_duration and applied_tags. Note that if the thread is locked then only those with Permissions.manage_threads can unarchive a thread.

The thread must be unarchived to be edited.

Parameters:

  • name (str) – The new name of the thread.

  • archived (bool) – Whether to archive the thread or not.

  • locked (bool) – Whether to lock the thread or not.

  • invitable (bool) – Whether non-moderators can add other non-moderators to this thread. Only available for private threads.

  • auto_archive_duration (Union[int, ThreadArchiveDuration]) – The new duration in minutes before a thread is automatically archived for inactivity. Must be one of 60, 1440, 4320, or 10080.

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

  • pinned (bool) –

    Whether to pin the thread or not. This is only available for threads created in a ForumChannel.

    New in version 2.5.

  • flags (ChannelFlags) –

    The new channel flags to set for this thread. This will overwrite any existing flags set on this channel. If parameter pinned is provided, that will override the setting of ChannelFlags.pinned.

    New in version 2.6.

  • applied_tags (Sequence[abc.Snowflake]) –

    The new tags of the thread. Maximum of 5. Can also be used to reorder existing tags.

    This is only available for threads in a ForumChannel.

    If moderated tags are edited, Permissions.manage_threads permissions are required.

    See also add_tags() and remove_tags().

    New in version 2.6.

  • reason (Optional[str]) –

    The reason for editing this thread. Shows up on the audit log.

    New in version 2.5.

Raises:
Returns:

The newly edited thread.

Return type:

Thread

await join()[source]

This function is a coroutine.

Joins this thread.

You must have send_messages_in_threads to join a thread. If the thread is private, manage_threads is also needed.

Raises:
await leave()[source]

This function is a coroutine.

Leaves this thread.

Raises:

HTTPException – Leaving the thread failed.

await add_user(user)[source]

This function is a coroutine.

Adds a user to this thread.

You must have send_messages permission to add a user to a public thread. If the thread is private then send_messages and either create_private_threads or manage_messages permissions is required to add a user to the thread.

Parameters:

user (abc.Snowflake) – The user to add to the thread.

Raises:

  • Forbidden – You do not have permissions to add the user to the thread.

  • HTTPException – Adding the user to the thread failed.

await remove_user(user)[source]

This function is a coroutine.

Removes a user from this thread.

You must have manage_threads or be the creator of the thread to remove a user.

Parameters:

user (abc.Snowflake) – The user to add to the thread.

Raises:

  • Forbidden – You do not have permissions to remove the user from the thread.

  • HTTPException – Removing the user from the thread failed.

await fetch_member(member_id, /)[source]

This function is a coroutine.

Retrieves a single ThreadMember from this thread.

Parameters:

member_id (int) – The ID of the member to fetch.

Raises:
Returns:

The thread member asked for.

Return type:

ThreadMember

await fetch_members()[source]

This function is a coroutine.

Retrieves all ThreadMember that are in this thread.

This requires Intents.members to get information about members other than yourself.

Raises:

HTTPException – Retrieving the members failed.

Returns:

All thread members in the thread.

Return type:

List[ThreadMember]

await delete(*, reason=None)[source]

This function is a coroutine.

Deletes this thread.

You must have manage_threads to delete threads. Alternatively, you may delete a thread if it’s in a ForumChannel, you are the thread creator, and there are no messages other than the initial message.

Parameters:

reason (Optional[str]) –

The reason for deleting this thread. Shows up on the audit log.

New in version 2.5.

Raises:

  • Forbidden – You do not have permissions to delete this thread.

  • HTTPException – Deleting the thread failed.

await add_tags(*tags, reason=None)[source]

This function is a coroutine.

Adds the given tags to this thread, up to 5 in total.

The thread must be in a ForumChannel.

Adding tags requires you to have Permissions.manage_threads permissions, or be the owner of the thread. However, adding moderated tags always requires Permissions.manage_threads permissions.

New in version 2.6.

Parameters:

  • *tags (abc.Snowflake) – An argument list of abc.Snowflake representing the ForumTags to add to the thread.

  • reason (Optional[str]) – The reason for editing this thread. Shows up on the audit log.

Raises:
await remove_tags(*tags, reason=None)[source]

This function is a coroutine.

Removes the given tags from this thread.

The thread must be in a ForumChannel.

Removing tags requires you to have Permissions.manage_threads permissions, or be the owner of the thread. However, removing moderated tags always requires Permissions.manage_threads permissions.

New in version 2.6.

Parameters:

  • *tags (abc.Snowflake) – An argument list of abc.Snowflake representing the ForumTags to remove from the thread.

  • reason (Optional[str]) – The reason for editing this thread. Shows up on the audit log.

Raises:
get_partial_message(message_id, /)[source]

Creates a PartialMessage from the message ID.

This is useful if you want to work with a message and only have its ID without doing an unnecessary API call.

New in version 2.0.

Parameters:

message_id (int) – The message ID to create a partial message for.

Returns:

The partial message.

Return type:

PartialMessage

await fetch_message(id, /)[source]

This function is a coroutine.

Retrieves a single Message from the destination.

Parameters:

id (int) – The message ID to look for.

Raises:

  • NotFound – The specified message was not found.

  • Forbidden – You do not have the permissions required to get a message.

  • HTTPException – Retrieving the message failed.

Returns:

The message asked for.

Return type:

Message

await pins()[source]

This function is a coroutine.

Retrieves all messages that are currently pinned in the channel.

Note

Due to a limitation with the Discord API, the Message objects returned by this method do not contain complete Message.reactions data.

Raises:

HTTPException – Retrieving the pinned messages failed.

Returns:

The messages that are currently pinned.

Return type:

List[Message]

await send(content=None, *, tts=False, embed=None, embeds=None, file=None, files=None, stickers=None, delete_after=None, nonce=None, suppress_embeds=False, allowed_mentions=None, reference=None, mention_author=None, view=None, components=None)[source]

This function is a coroutine.

Sends a message to the destination with the content given.

The content must be a type that can convert to a string through str(content).

At least one of content, embed/embeds, file/files, stickers, components, or view must be provided.

To upload a single file, the file parameter should be used with a single File object. To upload multiple files, the files parameter should be used with a list of File objects. Specifying both parameters will lead to an exception.

To upload a single embed, the embed parameter should be used with a single Embed object. To upload multiple embeds, the embeds parameter should be used with a list of Embed objects. Specifying both parameters will lead to an exception.

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

Parameters:

  • content (Optional[str]) – The content of the message to send.

  • tts (bool) – Whether the message should be sent using text-to-speech.

  • embed (Embed) – The rich embed for the content to send. This cannot be mixed with the embeds parameter.

  • embeds (List[Embed]) –

    A list of embeds to send with the content. Must be a maximum of 10. This cannot be mixed with the embed parameter.

    New in version 2.0.

  • file (File) – The file to upload. This cannot be mixed with the files parameter.

  • files (List[File]) – A list of files to upload. Must be a maximum of 10. This cannot be mixed with the file parameter.

  • stickers (Sequence[Union[GuildSticker, StickerItem]]) –

    A list of stickers to upload. Must be a maximum of 3.

    New in version 2.0.

  • nonce (Union[str, int]) – The nonce to use for sending this message. If the message was successfully sent, then the message will have a nonce with this value.

  • delete_after (float) – If provided, the number of seconds to wait in the background before deleting the message we just sent. If the deletion fails, then it is silently ignored.

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

  • reference (Union[Message, MessageReference, PartialMessage]) –

    A reference to the Message to which you are replying, this can be created using Message.to_reference() or passed directly as a Message. You can control whether this mentions the author of the referenced message using the AllowedMentions.replied_user attribute of allowed_mentions or by setting mention_author.

    New in version 1.6.

  • mention_author (Optional[bool]) –

    If set, overrides the AllowedMentions.replied_user attribute of allowed_mentions.

    New in version 1.6.

  • view (ui.View) –

    A Discord UI View to add to the message. This cannot be mixed with components.

    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]]]]) –

    A list of components to include in the message. This cannot be mixed with view.

    New in version 2.4.

  • suppress_embeds (bool) –

    Whether to suppress embeds for the message. This hides all embeds from the UI if set to True.

    New in version 2.5.

Raises:
Returns:

The message that was sent.

Return type:

Message

await trigger_typing()[source]

This function is a coroutine.

Triggers a typing indicator to the destination.

Typing indicator will go away after 10 seconds, or after a message is sent.

ThreadMember

Attributes
class disnake.ThreadMember[source]

This class is a Discord Model.

Represents a Discord thread member.

x == y

Checks if two thread members are equal.

x != y

Checks if two thread members are not equal.

hash(x)

Returns the thread member’s hash.

str(x)

Returns the thread member’s name.

New in version 2.0.

id

The thread member’s ID.

Type:

int

thread_id

The thread’s ID.

Type:

int

joined_at

The time the member joined the thread in UTC.

Type:

datetime.datetime

property thread[source]

The thread this member belongs to.

Type:

Thread

ForumTag

Attributes
Methods
class disnake.ForumTag[source]

Represents a tag for threads in forum channels.

x == y

Checks if two tags are equal.

x != y

Checks if two tags are not equal.

hash(x)

Returns the tag’s hash.

str(x)

Returns the tag’s name.

New in version 2.6.

Examples

Creating a new tag:

tags = forum.available_tags
tags.append(ForumTag(name="cool new tag", moderated=True))
await forum.edit(available_tags=tags)

Editing an existing tag:

tags = []
for tag in forum.available_tags:
    if tag.id == 1234:
        tag = tag.with_changes(name="whoa new name")
    tags.append(tag)
await forum.edit(available_tags=tags)
id

The tag’s ID. Note that if this tag was manually constructed, this will be 0.

Type:

int

name

The tag’s name.

Type:

str

moderated

Whether only moderators can add this tag to threads or remove it. Defaults to False.

Type:

bool

emoji

The emoji associated with this tag, if any. Due to a Discord limitation, this will have an empty name if it is a custom PartialEmoji.

Type:

Optional[Union[Emoji, PartialEmoji]]

with_changes(*, name=..., emoji=..., moderated=...)[source]

Returns a new instance with the given changes applied, for easy use with ForumChannel.edit(). All other fields will be kept intact.

Returns:

The new tag instance.

Return type:

ForumTag

StageChannel

Attributes
Methods
class disnake.StageChannel[source]

This class is a Discord Model.

Represents a Discord guild stage channel.

New in version 1.7.

x == y

Checks if two channels are equal.

x != y

Checks if two channels are not equal.

hash(x)

Returns the channel’s hash.

str(x)

Returns the channel’s name.

name

The channel’s name.

Type:

str

guild

The guild the channel belongs to.

Type:

Guild

id

The channel’s ID.

Type:

int

topic

The channel’s topic. None if it isn’t set.

Type:

Optional[str]

category_id

The category channel ID this channel belongs to, if applicable.

Type:

Optional[int]

position

The position in the channel list. This is a number that starts at 0. e.g. the top channel is position 0.

Type:

int

bitrate

The channel’s preferred audio bitrate in bits per second.

Type:

int

user_limit

The channel’s limit for number of members that can be in a stage channel.

Type:

int

rtc_region

The region for the stage channel’s voice communication. A value of None indicates automatic voice region detection.

Changed in version 2.5: No longer a VoiceRegion instance.

Type:

Optional[str]

video_quality_mode

The camera video quality for the stage channel’s participants.

New in version 2.0.

Type:

VideoQualityMode

property requesting_to_speak[source]

A list of members who are requesting to speak in the stage channel.

Type:

List[Member]

property speakers[source]

A list of members who have been permitted to speak in the stage channel.

New in version 2.0.

Type:

List[Member]

property listeners[source]

A list of members who are listening in the stage channel.

New in version 2.0.

Type:

List[Member]

property moderators[source]

A list of members who are moderating the stage channel.

New in version 2.0.

Type:

List[Member]

property type[source]

The channel’s Discord type.

This always returns ChannelType.stage_voice.

Type:

ChannelType

await clone(*, name=None, reason=None)[source]

This function is a coroutine.

Clones this channel. This creates a channel with the same properties as this channel.

You must have Permissions.manage_channels permission to do this.

New in version 1.1.

Parameters:

  • name (Optional[str]) – The name of the new channel. If not provided, defaults to this channel name.

  • reason (Optional[str]) – The reason for cloning this channel. Shows up on the audit log.

Raises:

  • Forbidden – You do not have the proper permissions to create this channel.

  • HTTPException – Creating the channel failed.

Returns:

The channel that was created.

Return type:

abc.GuildChannel

property instance[source]

The running stage instance of the stage channel.

New in version 2.0.

Type:

Optional[StageInstance]

permissions_for(obj, /, *, ignore_timeout=...)[source]

Handles permission resolution for the Member or Role.

This function takes into consideration the following cases:

  • Guild owner

  • Guild roles

  • Channel overrides

  • Member overrides

  • Timeouts

If a Role is passed, then it checks the permissions someone with that role would have, which is essentially:

  • The default role permissions

  • The permissions of the role used as a parameter

  • The default role permission overwrites

  • The permission overwrites of the role used as a parameter

Changed in version 2.0: The object passed in can now be a role object.

Parameters:

  • obj (Union[Member, Role]) – The object to resolve permissions for. This could be either a member or a role. If it’s a role then member overwrites are not computed.

  • ignore_timeout (bool) –

    Whether or not to ignore the user’s timeout. Defaults to False.

    New in version 2.4.

    Note

    This only applies to Member objects.

    Changed in version 2.6: The default was changed to False.

Raises:

TypeError – ignore_timeout is only supported for Member objects.

Returns:

The resolved permissions for the member or role.

Return type:

Permissions

await create_instance(*, topic, privacy_level=..., notify_everyone=False, reason=None)[source]

This function is a coroutine.

Creates a stage instance.

You must have manage_channels permission to do this.

New in version 2.0.

Changed in version 2.6: Raises TypeError instead of InvalidArgument.

Parameters:

  • topic (str) – The stage instance’s topic.

  • privacy_level (StagePrivacyLevel) – The stage instance’s privacy level. Defaults to StagePrivacyLevel.guild_only.

  • reason (Optional[str]) – The reason the stage instance was created. Shows up on the audit log.

  • notify_everyone (bool) –

    Whether to notify @everyone that the stage instance has started. Requires the mention_everyone permission on the stage channel. Defaults to False.

    New in version 2.5.

Raises:

  • Forbidden – You do not have permissions to create a stage instance.

  • HTTPException – Creating a stage instance failed.

  • TypeError – If the privacy_level parameter is not the proper type.

Returns:

The newly created stage instance.

Return type:

StageInstance

await fetch_instance()[source]

This function is a coroutine.

Retrieves the running StageInstance.

New in version 2.0.

Raises:

  • NotFound – The stage instance or channel could not be found.

  • HTTPException – Retrieving the stage instance failed.

Returns:

The stage instance.

Return type:

StageInstance

await edit(*, name=..., position=..., sync_permissions=..., category=..., overwrites=..., rtc_region=..., video_quality_mode=..., bitrate=..., flags=..., reason=None, **kwargs)[source]

This function is a coroutine.

Edits the channel.

You must have manage_channels permission to do this.

Changed in version 2.0: The topic parameter must now be set via create_instance.

Changed in version 2.0: Edits are no longer in-place, the newly edited channel is returned instead.

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

Parameters:

  • name (str) – The new channel’s name.

  • position (int) – The new channel’s position.

  • sync_permissions (bool) – Whether to sync permissions with the channel’s new or pre-existing category. Defaults to False.

  • category (Optional[abc.Snowflake]) – The new category for this channel. Can be None to remove the category.

  • overwrites (Mapping) – A Mapping of target (either a role or a member) to PermissionOverwrite to apply to the channel.

  • rtc_region (Optional[Union[str, VoiceRegion]]) – The new region for the stage channel’s voice communication. A value of None indicates automatic voice region detection.

  • video_quality_mode (VideoQualityMode) –

    The camera video quality for the stage channel’s participants.

    New in version 2.0.

  • bitrate (int) –

    The new channel’s bitrate.

    New in version 2.6.

  • flags (ChannelFlags) –

    The new flags to set for this channel. This will overwrite any existing flags set on this channel.

    New in version 2.6.

  • reason (Optional[str]) – The reason for editing this channel. Shows up on the audit log.

Raises:

  • Forbidden – You do not have permissions to edit the channel.

  • HTTPException – Editing the channel failed.

  • TypeError – The permission overwrite information is not in proper form.

  • ValueError – The position is less than 0.

Returns:

The newly edited stage channel. If the edit was only positional then None is returned instead.

Return type:

Optional[StageChannel]

property category[source]

The category this channel belongs to.

If there is no category then this is None.

Type:

Optional[CategoryChannel]

property changed_roles[source]

Returns a list of roles that have been overridden from their default values in the Guild.roles attribute.

Type:

List[Role]

await connect(*, timeout=60.0, reconnect=True, cls=<class 'disnake.voice_client.VoiceClient'>)[source]

This function is a coroutine.

Connects to voice and creates a VoiceClient to establish your connection to the voice server.

This requires Intents.voice_states.

Parameters:

  • timeout (float) – The timeout in seconds to wait for the voice endpoint.

  • reconnect (bool) – Whether the bot should automatically attempt a reconnect if a part of the handshake fails or the gateway goes down.

  • cls (Type[VoiceProtocol]) – A type that subclasses VoiceProtocol to connect with. Defaults to VoiceClient.

Raises:
Returns:

A voice client that is fully connected to the voice server.

Return type:

VoiceProtocol

await create_invite(*, reason=None, max_age=0, max_uses=0, temporary=False, unique=True, target_type=None, target_user=None, target_application=None, guild_scheduled_event=None)[source]

This function is a coroutine.

Creates an instant invite from a text or voice channel.

You must have Permissions.create_instant_invite permission to do this.

Parameters:

  • max_age (int) – How long the invite should last in seconds. If it’s 0 then the invite doesn’t expire. Defaults to 0.

  • max_uses (int) – How many uses the invite could be used for. If it’s 0 then there are unlimited uses. Defaults to 0.

  • temporary (bool) – Whether the invite grants temporary membership (i.e. they get kicked after they disconnect). Defaults to False.

  • unique (bool) – Whether a unique invite URL should be created. Defaults to True. If this is set to False then it will return a previously created invite.

  • target_type (Optional[InviteTarget]) –

    The type of target for the voice channel invite, if any.

    New in version 2.0.

  • target_user (Optional[User]) –

    The user whose stream to display for this invite, required if target_type is TargetType.stream. The user must be streaming in the channel.

    New in version 2.0.

  • target_application (Optional[PartyType]) –

    The ID of the embedded application for the invite, required if target_type is TargetType.embedded_application.

    New in version 2.0.

  • guild_scheduled_event (Optional[GuildScheduledEvent]) –

    The guild scheduled event to include with the invite.

    New in version 2.3.

  • reason (Optional[str]) – The reason for creating this invite. Shows up on the audit log.

Raises:

  • HTTPException – Invite creation failed.

  • NotFound – The channel that was passed is a category or an invalid channel.

Returns:

The newly created invite.

Return type:

Invite

property created_at[source]

Returns the channel’s creation time in UTC.

Type:

datetime.datetime

await delete(*, reason=None)[source]

This function is a coroutine.

Deletes the channel.

You must have Permissions.manage_channels permission to do this.

Parameters:

reason (Optional[str]) – The reason for deleting this channel. Shows up on the audit log.

Raises:

  • Forbidden – You do not have proper permissions to delete the channel.

  • NotFound – The channel was not found or was already deleted.

  • HTTPException – Deleting the channel failed.

property flags[source]

The channel flags for this channel.

New in version 2.6.

Type:

ChannelFlags

await invites()[source]

This function is a coroutine.

Returns a list of all active instant invites from this channel.

You must have Permissions.manage_channels permission to use this.

Raises:

  • Forbidden – You do not have proper permissions to get the information.

  • HTTPException – An error occurred while fetching the information.

Returns:

The list of invites that are currently active.

Return type:

List[Invite]

property jump_url[source]

A URL that can be used to jump to this channel.

New in version 2.4.

Note

This exists for all guild channels but may not be usable by the client for all guild channel types.

property members[source]

Returns all members that are currently inside this voice channel.

Type:

List[Member]

property mention[source]

The string that allows you to mention the channel.

Type:

str

await move(**kwargs)[source]

This function is a coroutine.

A rich interface to help move a channel relative to other channels.

If exact position movement is required, edit should be used instead.

You must have Permissions.manage_channels permission to do this.

Note

Voice channels will always be sorted below text channels. This is a Discord limitation.

New in version 1.7.

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

Parameters:

  • beginning (bool) – Whether to move the channel to the beginning of the channel list (or category if given). This is mutually exclusive with end, before, and after.

  • end (bool) – Whether to move the channel to the end of the channel list (or category if given). This is mutually exclusive with beginning, before, and after.

  • before (abc.Snowflake) – The channel that should be before our current channel. This is mutually exclusive with beginning, end, and after.

  • after (abc.Snowflake) – The channel that should be after our current channel. This is mutually exclusive with beginning, end, and before.

  • offset (int) – The number of channels to offset the move by. For example, an offset of 2 with beginning=True would move it 2 after the beginning. A positive number moves it below while a negative number moves it above. Note that this number is relative and computed after the beginning, end, before, and after parameters.

  • category (Optional[abc.Snowflake]) – The category to move this channel under. If None is given then it moves it out of the category. This parameter is ignored if moving a category channel.

  • sync_permissions (bool) – Whether to sync the permissions with the category (if given).

  • reason (Optional[str]) – The reason for moving this channel. Shows up on the audit log.

Raises:

  • Forbidden – You do not have permissions to move the channel.

  • HTTPException – Moving the channel failed.

  • TypeError – A bad mix of arguments were passed.

  • ValueError – An invalid position was given.

property overwrites[source]

Returns all of the channel’s overwrites.

This is returned as a dictionary where the key contains the target which can be either a Role or a Member and the value is the overwrite as a PermissionOverwrite.

Returns:

The channel’s permission overwrites.

Return type:

Dict[Union[Role, Member], PermissionOverwrite]

overwrites_for(obj)[source]

Returns the channel-specific overwrites for a member or a role.

Parameters:

obj (Union[Role, abc.User]) – The role or user denoting whose overwrite to get.

Returns:

The permission overwrites for this object.

Return type:

PermissionOverwrite

property permissions_synced[source]

Whether or not the permissions for this channel are synced with the category it belongs to.

If there is no category then this is False.

New in version 1.3.

Type:

bool

await set_permissions(target, *, overwrite=..., reason=None, **permissions)[source]

This function is a coroutine.

Sets the channel specific permission overwrites for a target in the channel.

The target parameter should either be a Member or a Role that belongs to guild.

The overwrite parameter, if given, must either be None or PermissionOverwrite. For convenience, you can pass in keyword arguments denoting Permissions attributes. If this is done, then you cannot mix the keyword arguments with the overwrite parameter.

If the overwrite parameter is None, then the permission overwrites are deleted.

You must have Permissions.manage_roles permission to do this.

Note

This method replaces the old overwrites with the ones given.

Changed in version 2.6: Raises TypeError instead of InvalidArgument.

Examples

Setting allow and deny:

await message.channel.set_permissions(message.author, view_channel=True,
                                                      send_messages=False)

Deleting overwrites

await channel.set_permissions(member, overwrite=None)

Using PermissionOverwrite

overwrite = disnake.PermissionOverwrite()
overwrite.send_messages = False
overwrite.view_channel = True
await channel.set_permissions(member, overwrite=overwrite)
Parameters:

  • target (Union[Member, Role]) – The member or role to overwrite permissions for.

  • overwrite (Optional[PermissionOverwrite]) – The permissions to allow and deny to the target, or None to delete the overwrite.

  • **permissions – A keyword argument list of permissions to set for ease of use. Cannot be mixed with overwrite.

  • reason (Optional[str]) – The reason for doing this action. Shows up on the audit log.

Raises:

  • Forbidden – You do not have permissions to edit channel specific permissions.

  • HTTPException – Editing channel specific permissions failed.

  • NotFound – The role or member being edited is not part of the guild.

  • TypeError – overwrite is invalid, the target type was not Role or Member, both keyword arguments and overwrite were provided, or invalid permissions were provided as keyword arguments.

property voice_states[source]

Returns a mapping of member IDs who have voice states in this channel.

New in version 1.3.

Note

This function is intentionally low level to replace members when the member cache is unavailable.

Returns:

The mapping of member ID to a voice state.

Return type:

Mapping[int, VoiceState]

ForumChannel

Attributes
Methods
class disnake.ForumChannel[source]

This class is a Discord Model.

Represents a Discord Forum channel.

New in version 2.5.

x == y

Checks if two channels are equal.

x != y

Checks if two channels are not equal.

hash(x)

Returns the channel’s hash.

str(x)

Returns the channel’s name.

id

The channel’s ID.

Type:

int

name

The channel’s name.

Type:

str

guild

The guild the channel belongs to.

Type:

Guild

topic

The channel’s topic. None if it isn’t set.

Type:

Optional[str]

category_id

The category channel ID this channel belongs to, if applicable.

Type:

Optional[int]

position

The position in the channel list. This is a number that starts at 0. e.g. the top channel is position 0.

Type:

int

nsfw

Whether the channel is marked as “not safe for work”.

Note

To check if the channel or the guild of that channel are marked as NSFW, consider is_nsfw() instead.

Type:

bool

last_thread_id

The ID of the last created thread in this channel. It may not point to an existing or valid thread.

Type:

Optional[int]

default_auto_archive_duration

The default auto archive duration in minutes for threads created in this channel.

Type:

int

slowmode_delay

The number of seconds a member must wait between creating threads in this channel.

A value of 0 denotes that it is disabled. Bots, and users with manage_channels or manage_messages, bypass slowmode.

See also default_thread_slowmode_delay.

Type:

int

default_thread_slowmode_delay

The default number of seconds a member must wait between sending messages in newly created threads in this channel.

A value of 0 denotes that it is disabled. Bots, and users with manage_channels or manage_messages, bypass slowmode.

New in version 2.6.

Type:

int

default_sort_order

The default sort order of threads in this channel. Members will still be able to change this locally.

New in version 2.6.

Type:

Optional[ThreadSortOrder]

async with typing()[source]

Returns a context manager that allows you to type for an indefinite period of time.

This is useful for denoting long computations in your bot.

Note

This is both a regular context manager and an async context manager. This means that both with and async with work with this.

Example Usage:

async with channel.typing():
    # simulate something heavy
    await asyncio.sleep(10)

await channel.send('done!')
property type[source]

The channel’s Discord type.

This always returns ChannelType.forum.

Type:

ChannelType

permissions_for(obj, /, *, ignore_timeout=...)[source]

Handles permission resolution for the Member or Role.

This function takes into consideration the following cases:

  • Guild owner

  • Guild roles

  • Channel overrides

  • Member overrides

  • Timeouts

If a Role is passed, then it checks the permissions someone with that role would have, which is essentially:

  • The default role permissions

  • The permissions of the role used as a parameter

  • The default role permission overwrites

  • The permission overwrites of the role used as a parameter

Changed in version 2.0: The object passed in can now be a role object.

Parameters:

  • obj (Union[Member, Role]) – The object to resolve permissions for. This could be either a member or a role. If it’s a role then member overwrites are not computed.

  • ignore_timeout (bool) –

    Whether or not to ignore the user’s timeout. Defaults to False.

    New in version 2.4.

    Note

    This only applies to Member objects.

    Changed in version 2.6: The default was changed to False.

Raises:

TypeError – ignore_timeout is only supported for Member objects.

Returns:

The resolved permissions for the member or role.

Return type:

Permissions

property members[source]

Returns all members that can see this channel.

Type:

List[Member]

property threads[source]

Returns all the threads that you can see.

Type:

List[Thread]

is_nsfw()[source]

Whether the channel is marked as NSFW.

Return type:

bool

requires_tag()[source]

Whether all newly created threads in this channel are required to have a tag.

This is a shortcut to self.flags.require_tag.

New in version 2.6.

Return type:

bool

property default_reaction[source]

Optional[Union[Emoji, PartialEmoji]]: The default emoji shown for reacting to threads.

Due to a Discord limitation, this will have an empty name if it is a custom PartialEmoji.

New in version 2.6.

property last_thread[source]

Gets the last created thread in this channel from the cache.

The thread might not be valid or point to an existing thread.

Reliable Fetching

For a slightly more reliable method of fetching the last thread, use Guild.fetch_channel() with the last_thread_id attribute.

Returns:

The last created thread in this channel or None if not found.

Return type:

Optional[Thread]

property available_tags[source]

The available tags for threads in this forum channel.

To create/edit/delete tags, use edit().

New in version 2.6.

Type:

List[ForumTag]

await trigger_typing()[source]

This function is a coroutine.

Triggers a typing indicator to the desination.

Typing indicator will go away after 10 seconds.

await edit(*, name=..., topic=..., position=..., nsfw=..., sync_permissions=..., category=..., slowmode_delay=..., default_thread_slowmode_delay=..., default_auto_archive_duration=..., overwrites=..., flags=..., require_tag=..., available_tags=..., default_reaction=..., default_sort_order=..., reason=None, **kwargs)[source]

This function is a coroutine.

Edits the channel.

You must have manage_channels permission to do this.

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

Parameters:

  • name (str) – The channel’s new name.

  • topic (Optional[str]) – The channel’s new topic.

  • position (int) – The channel’s new position.

  • nsfw (bool) – Whether to mark the channel as NSFW.

  • sync_permissions (bool) – Whether to sync permissions with the channel’s new or pre-existing category. Defaults to False.

  • category (Optional[abc.Snowflake]) – The new category for this channel. Can be None to remove the category.

  • slowmode_delay (Optional[int]) – Specifies the slowmode rate limit at which users can create threads in this channel, in seconds. A value of 0 or None disables slowmode. The maximum value possible is 21600.

  • default_thread_slowmode_delay (Optional[int]) –

    Specifies the slowmode rate limit at which users can send messages in newly created threads in this channel, in seconds. This does not apply retroactively to existing threads. A value of 0 or None disables slowmode. The maximum value possible is 21600.

    New in version 2.6.

  • overwrites (Mapping) – A Mapping of target (either a role or a member) to PermissionOverwrite to apply to the channel.

  • default_auto_archive_duration (Optional[Union[int, ThreadArchiveDuration]]) – The new default auto archive duration in minutes for threads created in this channel. Must be one of 60, 1440, 4320, or 10080.

  • flags (ChannelFlags) –

    The new flags to set for this channel. This will overwrite any existing flags set on this channel. If parameter require_tag is provided, that will override the setting of ChannelFlags.require_tag.

    New in version 2.6.

  • require_tag (bool) –

    Whether all newly created threads are required to have a tag.

    New in version 2.6.

  • available_tags (Sequence[ForumTag]) –

    The new ForumTags available for threads in this channel. Can be used to create new tags and edit/reorder/delete existing tags. Maximum of 20.

    Note that this overwrites all tags, removing existing tags unless they’re passed as well.

    See ForumTag for examples regarding creating/editing tags.

    New in version 2.6.

  • default_reaction (Optional[Union[str, Emoji, PartialEmoji]]) –

    The new default emoji shown for reacting to threads.

    New in version 2.6.

  • default_sort_order (Optional[ThreadSortOrder]) –

    The new default sort order of threads in this channel.

    New in version 2.6.

  • reason (Optional[str]) – The reason for editing this channel. Shows up on the audit log.

Raises:

  • Forbidden – You do not have permissions to edit the channel.

  • HTTPException – Editing the channel failed.

  • TypeError – The permission overwrite information is not in proper form.

  • ValueError – The position is less than 0.

Returns:

The newly edited forum channel. If the edit was only positional then None is returned instead.

Return type:

Optional[ForumChannel]

await clone(*, name=None, reason=None)[source]

This function is a coroutine.

Clones this channel. This creates a channel with the same properties as this channel.

You must have Permissions.manage_channels permission to do this.

New in version 1.1.

Parameters:

  • name (Optional[str]) – The name of the new channel. If not provided, defaults to this channel name.

  • reason (Optional[str]) – The reason for cloning this channel. Shows up on the audit log.

Raises:

  • Forbidden – You do not have the proper permissions to create this channel.

  • HTTPException – Creating the channel failed.

Returns:

The channel that was created.

Return type:

abc.GuildChannel

get_thread(thread_id, /)[source]

Returns a thread with the given ID.

Parameters:

thread_id (int) – The ID to search for.

Returns:

The returned thread of None if not found.

Return type:

Optional[Thread]

await create_thread(*, name, auto_archive_duration=..., slowmode_delay=..., applied_tags=..., content=..., embed=..., embeds=..., file=..., files=..., suppress_embeds=..., stickers=..., allowed_mentions=..., view=..., components=..., reason=None)[source]

This function is a coroutine.

Creates a thread in this forum channel.

You must have the create_forum_threads permission to do this.

At least one of content, embed/embeds, file/files, stickers, components, or view must be provided.

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

Changed in version 2.6: The content parameter is no longer required.

Parameters:

  • name (str) – The name of the thread.

  • auto_archive_duration (Union[int, ThreadArchiveDuration]) – The duration in minutes before the 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) – 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 not provided, slowmode is inherited from the parent’s default_thread_slowmode_delay.

  • applied_tags (Sequence[abc.Snowflake]) –

    The tags to apply to the new thread. Maximum of 5.

    New in version 2.6.

  • content (str) – The content of the message to send.

  • embed (Embed) – The rich embed for the content to send. This cannot be mixed with the embeds parameter.

  • embeds (List[Embed]) – A list of embeds to send with the content. Must be a maximum of 10. This cannot be mixed with the embed parameter.

  • suppress_embeds (bool) – Whether to suppress embeds for the message. This hides all embeds from the UI if set to True.

  • file (File) – The file to upload. This cannot be mixed with the files parameter.

  • files (List[File]) – A list of files to upload. Must be a maximum of 10. This cannot be mixed with the file parameter.

  • stickers (Sequence[Union[GuildSticker, StickerItem]]) – A list of stickers to upload. Must be a maximum of 3.

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

  • view (ui.View) – A Discord UI View to add to the message. This cannot be mixed with components.

  • components (Union[disnake.ui.ActionRow, disnake.ui.WrappedComponent, List[Union[disnake.ui.ActionRow, disnake.ui.WrappedComponent, List[disnake.ui.WrappedComponent]]]]) – A list of components to include in the message. This cannot be mixed with view.

  • reason (Optional[str]) – The reason for creating the thread. Shows up on the audit log.

Raises:

  • Forbidden – You do not have permissions to create a thread.

  • HTTPException – Starting the thread failed.

  • TypeError – Specified both file and files, or you specified both embed and embeds, or you specified both view and components. or you have passed an object that is not File to file or files.

  • ValueError – Specified more than 10 embeds, or more than 10 files.

Returns:

A NamedTuple with the newly created thread and the message sent in it.

These values can also be accessed through the thread and message fields.

Return type:

Tuple[Thread, Message]

archived_threads(*, limit=50, before=None)[source]

Returns an AsyncIterator that iterates over all archived threads in the channel.

You must have read_message_history permission to use this.

Parameters:

  • limit (Optional[int]) – The number of threads to retrieve. If None, retrieves every archived thread in the channel. Note, however, that this would make it a slow operation.

  • before (Optional[Union[abc.Snowflake, datetime.datetime]]) – Retrieve archived channels before the given date or ID.

Raises:

  • Forbidden – You do not have permissions to get archived threads.

  • HTTPException – The request to get the archived threads failed.

Yields:

Thread – The archived threads.

await webhooks()[source]

This function is a coroutine.

Retrieves the list of webhooks this channel has.

You must have manage_webhooks permission to use this.

New in version 2.6.

Raises:

Forbidden – You don’t have permissions to get the webhooks.

Returns:

The list of webhooks this channel has.

Return type:

List[Webhook]

await create_webhook(*, name, avatar=None, reason=None)[source]

This function is a coroutine.

Creates a webhook for this channel.

You must have manage_webhooks permission to do this.

New in version 2.6.

Parameters:

  • name (str) – The webhook’s name.

  • avatar (Optional[bytes]) – The webhook’s default avatar. This operates similarly to edit().

  • reason (Optional[str]) – The reason for creating this webhook. Shows up in the audit logs.

Raises:
Returns:

The newly created webhook.

Return type:

Webhook

get_tag(tag_id, /)[source]

Returns a thread tag with the given ID.

New in version 2.6.

Parameters:

tag_id (int) – The ID to search for.

Returns:

The tag with the given ID, or None if not found.

Return type:

Optional[ForumTag]

get_tag_by_name(name, /)[source]

Returns a thread tag with the given name.

Tags can be uniquely identified based on the name, as tag names in a forum channel must be unique.

New in version 2.6.

Parameters:

name (str) – The name to search for.

Returns:

The tag with the given name, or None if not found.

Return type:

Optional[ForumTag]

property category[source]

The category this channel belongs to.

If there is no category then this is None.

Type:

Optional[CategoryChannel]

property changed_roles[source]

Returns a list of roles that have been overridden from their default values in the Guild.roles attribute.

Type:

List[Role]

await create_invite(*, reason=None, max_age=0, max_uses=0, temporary=False, unique=True, target_type=None, target_user=None, target_application=None, guild_scheduled_event=None)[source]

This function is a coroutine.

Creates an instant invite from a text or voice channel.

You must have Permissions.create_instant_invite permission to do this.

Parameters:

  • max_age (int) – How long the invite should last in seconds. If it’s 0 then the invite doesn’t expire. Defaults to 0.

  • max_uses (int) – How many uses the invite could be used for. If it’s 0 then there are unlimited uses. Defaults to 0.

  • temporary (bool) – Whether the invite grants temporary membership (i.e. they get kicked after they disconnect). Defaults to False.

  • unique (bool) – Whether a unique invite URL should be created. Defaults to True. If this is set to False then it will return a previously created invite.

  • target_type (Optional[InviteTarget]) –

    The type of target for the voice channel invite, if any.

    New in version 2.0.

  • target_user (Optional[User]) –

    The user whose stream to display for this invite, required if target_type is TargetType.stream. The user must be streaming in the channel.

    New in version 2.0.

  • target_application (Optional[PartyType]) –

    The ID of the embedded application for the invite, required if target_type is TargetType.embedded_application.

    New in version 2.0.

  • guild_scheduled_event (Optional[GuildScheduledEvent]) –

    The guild scheduled event to include with the invite.

    New in version 2.3.

  • reason (Optional[str]) – The reason for creating this invite. Shows up on the audit log.

Raises:

  • HTTPException – Invite creation failed.

  • NotFound – The channel that was passed is a category or an invalid channel.

Returns:

The newly created invite.

Return type:

Invite

property created_at[source]

Returns the channel’s creation time in UTC.

Type:

datetime.datetime

await delete(*, reason=None)[source]

This function is a coroutine.

Deletes the channel.

You must have Permissions.manage_channels permission to do this.

Parameters:

reason (Optional[str]) – The reason for deleting this channel. Shows up on the audit log.

Raises:

  • Forbidden – You do not have proper permissions to delete the channel.

  • NotFound – The channel was not found or was already deleted.

  • HTTPException – Deleting the channel failed.

property flags[source]

The channel flags for this channel.

New in version 2.6.

Type:

ChannelFlags

await invites()[source]

This function is a coroutine.

Returns a list of all active instant invites from this channel.

You must have Permissions.manage_channels permission to use this.

Raises:

  • Forbidden – You do not have proper permissions to get the information.

  • HTTPException – An error occurred while fetching the information.

Returns:

The list of invites that are currently active.

Return type:

List[Invite]

property jump_url[source]

A URL that can be used to jump to this channel.

New in version 2.4.

Note

This exists for all guild channels but may not be usable by the client for all guild channel types.

property mention[source]

The string that allows you to mention the channel.

Type:

str

await move(**kwargs)[source]

This function is a coroutine.

A rich interface to help move a channel relative to other channels.

If exact position movement is required, edit should be used instead.

You must have Permissions.manage_channels permission to do this.

Note

Voice channels will always be sorted below text channels. This is a Discord limitation.

New in version 1.7.

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

Parameters:

  • beginning (bool) – Whether to move the channel to the beginning of the channel list (or category if given). This is mutually exclusive with end, before, and after.

  • end (bool) – Whether to move the channel to the end of the channel list (or category if given). This is mutually exclusive with beginning, before, and after.

  • before (abc.Snowflake) – The channel that should be before our current channel. This is mutually exclusive with beginning, end, and after.

  • after (abc.Snowflake) – The channel that should be after our current channel. This is mutually exclusive with beginning, end, and before.

  • offset (int) – The number of channels to offset the move by. For example, an offset of 2 with beginning=True would move it 2 after the beginning. A positive number moves it below while a negative number moves it above. Note that this number is relative and computed after the beginning, end, before, and after parameters.

  • category (Optional[abc.Snowflake]) – The category to move this channel under. If None is given then it moves it out of the category. This parameter is ignored if moving a category channel.

  • sync_permissions (bool) – Whether to sync the permissions with the category (if given).

  • reason (Optional[str]) – The reason for moving this channel. Shows up on the audit log.

Raises:

  • Forbidden – You do not have permissions to move the channel.

  • HTTPException – Moving the channel failed.

  • TypeError – A bad mix of arguments were passed.

  • ValueError – An invalid position was given.

property overwrites[source]

Returns all of the channel’s overwrites.

This is returned as a dictionary where the key contains the target which can be either a Role or a Member and the value is the overwrite as a PermissionOverwrite.

Returns:

The channel’s permission overwrites.

Return type:

Dict[Union[Role, Member], PermissionOverwrite]

overwrites_for(obj)[source]

Returns the channel-specific overwrites for a member or a role.

Parameters:

obj (Union[Role, abc.User]) – The role or user denoting whose overwrite to get.

Returns:

The permission overwrites for this object.

Return type:

PermissionOverwrite

property permissions_synced[source]

Whether or not the permissions for this channel are synced with the category it belongs to.

If there is no category then this is False.

New in version 1.3.

Type:

bool

await set_permissions(target, *, overwrite=..., reason=None, **permissions)[source]

This function is a coroutine.

Sets the channel specific permission overwrites for a target in the channel.

The target parameter should either be a Member or a Role that belongs to guild.

The overwrite parameter, if given, must either be None or PermissionOverwrite. For convenience, you can pass in keyword arguments denoting Permissions attributes. If this is done, then you cannot mix the keyword arguments with the overwrite parameter.

If the overwrite parameter is None, then the permission overwrites are deleted.

You must have Permissions.manage_roles permission to do this.

Note

This method replaces the old overwrites with the ones given.

Changed in version 2.6: Raises TypeError instead of InvalidArgument.

Examples

Setting allow and deny:

await message.channel.set_permissions(message.author, view_channel=True,
                                                      send_messages=False)

Deleting overwrites

await channel.set_permissions(member, overwrite=None)

Using PermissionOverwrite

overwrite = disnake.PermissionOverwrite()
overwrite.send_messages = False
overwrite.view_channel = True
await channel.set_permissions(member, overwrite=overwrite)
Parameters:

  • target (Union[Member, Role]) – The member or role to overwrite permissions for.

  • overwrite (Optional[PermissionOverwrite]) – The permissions to allow and deny to the target, or None to delete the overwrite.

  • **permissions – A keyword argument list of permissions to set for ease of use. Cannot be mixed with overwrite.

  • reason (Optional[str]) – The reason for doing this action. Shows up on the audit log.

Raises:

  • Forbidden – You do not have permissions to edit channel specific permissions.

  • HTTPException – Editing channel specific permissions failed.

  • NotFound – The role or member being edited is not part of the guild.

  • TypeError – overwrite is invalid, the target type was not Role or Member, both keyword arguments and overwrite were provided, or invalid permissions were provided as keyword arguments.

DMChannel

Attributes
Methods
class disnake.DMChannel[source]

This class is a Discord Model.

Represents a Discord direct message channel.

x == y

Checks if two channels are equal.

x != y

Checks if two channels are not equal.

hash(x)

Returns the channel’s hash.

str(x)

Returns a string representation of the channel

recipient

The user you are participating with in the direct message channel. If this channel is received through the gateway, the recipient information may not be always available.

Type:

Optional[User]

me

The user presenting yourself.

Type:

ClientUser

id

The direct message channel ID.

Type:

int

last_pin_timestamp

The time the most recent message was pinned, or None if no message is currently pinned.

New in version 2.5.

Type:

Optional[datetime.datetime]

async for ... in history(*, limit=100, before=None, after=None, around=None, oldest_first=None)[source]

Returns an AsyncIterator that enables receiving the destination’s message history.

You must have Permissions.read_message_history permission to use this.

Examples

Usage

counter = 0
async for message in channel.history(limit=200):
    if message.author == client.user:
        counter += 1

Flattening into a list:

messages = await channel.history(limit=123).flatten()
# messages is now a list of Message...

All parameters are optional.

Parameters:

  • limit (Optional[int]) – The number of messages to retrieve. If None, retrieves every message in the channel. Note, however, that this would make it a slow operation.

  • before (Optional[Union[abc.Snowflake, datetime.datetime]]) – Retrieve messages before this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

  • after (Optional[Union[abc.Snowflake, datetime.datetime]]) – Retrieve messages after this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

  • around (Optional[Union[abc.Snowflake, datetime.datetime]]) – Retrieve messages around this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time. When using this argument, the maximum limit is 101. Note that if the limit is an even number then this will return at most limit + 1 messages.

  • oldest_first (Optional[bool]) – If set to True, return messages in oldest->newest order. Defaults to True if after is specified, otherwise False.

Raises:

  • Forbidden – You do not have permissions to get channel message history.

  • HTTPException – The request to get message history failed.

Yields:

Message – The message with the message data parsed.

async with typing()[source]

Returns a context manager that allows you to type for an indefinite period of time.

This is useful for denoting long computations in your bot.

Note

This is both a regular context manager and an async context manager. This means that both with and async with work with this.

Example Usage:

async with channel.typing():
    # simulate something heavy
    await asyncio.sleep(10)

await channel.send('done!')
property type[source]

The channel’s Discord type.

This always returns ChannelType.private.

Type:

ChannelType

property created_at[source]

Returns the direct message channel’s creation time in UTC.

Type:

datetime.datetime

property jump_url[source]

A URL that can be used to jump to this channel.

New in version 2.4.

property flags[source]

The channel flags for this channel.

New in version 2.6.

Type:

ChannelFlags

permissions_for(obj=None, /, *, ignore_timeout=...)[source]

Handles permission resolution for a User.

This function is there for compatibility with other channel types.

Actual direct messages do not really have the concept of permissions.

This returns all the Permissions.private_channel() permissions set to True.

Parameters:

  • obj (User) – The user to check permissions for. This parameter is ignored but kept for compatibility with other permissions_for methods.

  • ignore_timeout (bool) – Whether to ignore the guild timeout when checking permsisions. This parameter is ignored but kept for compatibility with other permissions_for methods.

Returns:

The resolved permissions.

Return type:

Permissions

get_partial_message(message_id, /)[source]

Creates a PartialMessage from the given message ID.

This is useful if you want to work with a message and only have its ID without doing an unnecessary API call.

New in version 1.6.

Parameters:

message_id (int) – The message ID to create a partial message for.

Returns:

The partial message object.

Return type:

PartialMessage

await fetch_message(id, /)[source]

This function is a coroutine.

Retrieves a single Message from the destination.

Parameters:

id (int) – The message ID to look for.

Raises:

  • NotFound – The specified message was not found.

  • Forbidden – You do not have the permissions required to get a message.

  • HTTPException – Retrieving the message failed.

Returns:

The message asked for.

Return type:

Message

await pins()[source]

This function is a coroutine.

Retrieves all messages that are currently pinned in the channel.

Note

Due to a limitation with the Discord API, the Message objects returned by this method do not contain complete Message.reactions data.

Raises:

HTTPException – Retrieving the pinned messages failed.

Returns:

The messages that are currently pinned.

Return type:

List[Message]

await send(content=None, *, tts=False, embed=None, embeds=None, file=None, files=None, stickers=None, delete_after=None, nonce=None, suppress_embeds=False, allowed_mentions=None, reference=None, mention_author=None, view=None, components=None)[source]

This function is a coroutine.

Sends a message to the destination with the content given.

The content must be a type that can convert to a string through str(content).

At least one of content, embed/embeds, file/files, stickers, components, or view must be provided.

To upload a single file, the file parameter should be used with a single File object. To upload multiple files, the files parameter should be used with a list of File objects. Specifying both parameters will lead to an exception.

To upload a single embed, the embed parameter should be used with a single Embed object. To upload multiple embeds, the embeds parameter should be used with a list of Embed objects. Specifying both parameters will lead to an exception.

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

Parameters:

  • content (Optional[str]) – The content of the message to send.

  • tts (bool) – Whether the message should be sent using text-to-speech.

  • embed (Embed) – The rich embed for the content to send. This cannot be mixed with the embeds parameter.

  • embeds (List[Embed]) –

    A list of embeds to send with the content. Must be a maximum of 10. This cannot be mixed with the embed parameter.

    New in version 2.0.

  • file (File) – The file to upload. This cannot be mixed with the files parameter.

  • files (List[File]) – A list of files to upload. Must be a maximum of 10. This cannot be mixed with the file parameter.

  • stickers (Sequence[Union[GuildSticker, StickerItem]]) –

    A list of stickers to upload. Must be a maximum of 3.

    New in version 2.0.

  • nonce (Union[str, int]) – The nonce to use for sending this message. If the message was successfully sent, then the message will have a nonce with this value.

  • delete_after (float) – If provided, the number of seconds to wait in the background before deleting the message we just sent. If the deletion fails, then it is silently ignored.

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

  • reference (Union[Message, MessageReference, PartialMessage]) –

    A reference to the Message to which you are replying, this can be created using Message.to_reference() or passed directly as a Message. You can control whether this mentions the author of the referenced message using the AllowedMentions.replied_user attribute of allowed_mentions or by setting mention_author.

    New in version 1.6.

  • mention_author (Optional[bool]) –

    If set, overrides the AllowedMentions.replied_user attribute of allowed_mentions.

    New in version 1.6.

  • view (ui.View) –

    A Discord UI View to add to the message. This cannot be mixed with components.

    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]]]]) –

    A list of components to include in the message. This cannot be mixed with view.

    New in version 2.4.

  • suppress_embeds (bool) –

    Whether to suppress embeds for the message. This hides all embeds from the UI if set to True.

    New in version 2.5.

Raises:
Returns:

The message that was sent.

Return type:

Message

await trigger_typing()[source]

This function is a coroutine.

Triggers a typing indicator to the destination.

Typing indicator will go away after 10 seconds, or after a message is sent.

GroupChannel

Attributes
Methods
class disnake.GroupChannel[source]

This class is a Discord Model.

Represents a Discord group channel.

x == y

Checks if two channels are equal.

x != y

Checks if two channels are not equal.

hash(x)

Returns the channel’s hash.

str(x)

Returns a string representation of the channel

recipients

The users you are participating with in the group channel.

Type:

List[User]

me

The user presenting yourself.

Type:

ClientUser

id

The group channel ID.

Type:

int

owner

The user that owns the group channel.

Type:

Optional[User]

owner_id

The owner ID that owns the group channel.

New in version 2.0.

Type:

int

name

The group channel’s name if provided.

Type:

Optional[str]

async for ... in history(*, limit=100, before=None, after=None, around=None, oldest_first=None)[source]

Returns an AsyncIterator that enables receiving the destination’s message history.

You must have Permissions.read_message_history permission to use this.

Examples

Usage

counter = 0
async for message in channel.history(limit=200):
    if message.author == client.user:
        counter += 1

Flattening into a list:

messages = await channel.history(limit=123).flatten()
# messages is now a list of Message...

All parameters are optional.

Parameters:

  • limit (Optional[int]) – The number of messages to retrieve. If None, retrieves every message in the channel. Note, however, that this would make it a slow operation.

  • before (Optional[Union[abc.Snowflake, datetime.datetime]]) – Retrieve messages before this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

  • after (Optional[Union[abc.Snowflake, datetime.datetime]]) – Retrieve messages after this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

  • around (Optional[Union[abc.Snowflake, datetime.datetime]]) – Retrieve messages around this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time. When using this argument, the maximum limit is 101. Note that if the limit is an even number then this will return at most limit + 1 messages.

  • oldest_first (Optional[bool]) – If set to True, return messages in oldest->newest order. Defaults to True if after is specified, otherwise False.

Raises:

  • Forbidden – You do not have permissions to get channel message history.

  • HTTPException – The request to get message history failed.

Yields:

Message – The message with the message data parsed.

async with typing()[source]

Returns a context manager that allows you to type for an indefinite period of time.

This is useful for denoting long computations in your bot.

Note

This is both a regular context manager and an async context manager. This means that both with and async with work with this.

Example Usage:

async with channel.typing():
    # simulate something heavy
    await asyncio.sleep(10)

await channel.send('done!')
await fetch_message(id, /)[source]

This function is a coroutine.

Retrieves a single Message from the destination.

Parameters:

id (int) – The message ID to look for.

Raises:

  • NotFound – The specified message was not found.

  • Forbidden – You do not have the permissions required to get a message.

  • HTTPException – Retrieving the message failed.

Returns:

The message asked for.

Return type:

Message

await pins()[source]

This function is a coroutine.

Retrieves all messages that are currently pinned in the channel.

Note

Due to a limitation with the Discord API, the Message objects returned by this method do not contain complete Message.reactions data.

Raises:

HTTPException – Retrieving the pinned messages failed.

Returns:

The messages that are currently pinned.

Return type:

List[Message]

await send(content=None, *, tts=False, embed=None, embeds=None, file=None, files=None, stickers=None, delete_after=None, nonce=None, suppress_embeds=False, allowed_mentions=None, reference=None, mention_author=None, view=None, components=None)[source]

This function is a coroutine.

Sends a message to the destination with the content given.

The content must be a type that can convert to a string through str(content).

At least one of content, embed/embeds, file/files, stickers, components, or view must be provided.

To upload a single file, the file parameter should be used with a single File object. To upload multiple files, the files parameter should be used with a list of File objects. Specifying both parameters will lead to an exception.

To upload a single embed, the embed parameter should be used with a single Embed object. To upload multiple embeds, the embeds parameter should be used with a list of Embed objects. Specifying both parameters will lead to an exception.

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

Parameters:

  • content (Optional[str]) – The content of the message to send.

  • tts (bool) – Whether the message should be sent using text-to-speech.

  • embed (Embed) – The rich embed for the content to send. This cannot be mixed with the embeds parameter.

  • embeds (List[Embed]) –

    A list of embeds to send with the content. Must be a maximum of 10. This cannot be mixed with the embed parameter.

    New in version 2.0.

  • file (File) – The file to upload. This cannot be mixed with the files parameter.

  • files (List[File]) – A list of files to upload. Must be a maximum of 10. This cannot be mixed with the file parameter.

  • stickers (Sequence[Union[GuildSticker, StickerItem]]) –

    A list of stickers to upload. Must be a maximum of 3.

    New in version 2.0.

  • nonce (Union[str, int]) – The nonce to use for sending this message. If the message was successfully sent, then the message will have a nonce with this value.

  • delete_after (float) – If provided, the number of seconds to wait in the background before deleting the message we just sent. If the deletion fails, then it is silently ignored.

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

  • reference (Union[Message, MessageReference, PartialMessage]) –

    A reference to the Message to which you are replying, this can be created using Message.to_reference() or passed directly as a Message. You can control whether this mentions the author of the referenced message using the AllowedMentions.replied_user attribute of allowed_mentions or by setting mention_author.

    New in version 1.6.

  • mention_author (Optional[bool]) –

    If set, overrides the AllowedMentions.replied_user attribute of allowed_mentions.

    New in version 1.6.

  • view (ui.View) –

    A Discord UI View to add to the message. This cannot be mixed with components.

    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]]]]) –

    A list of components to include in the message. This cannot be mixed with view.

    New in version 2.4.

  • suppress_embeds (bool) –

    Whether to suppress embeds for the message. This hides all embeds from the UI if set to True.

    New in version 2.5.

Raises:
Returns:

The message that was sent.

Return type:

Message

await trigger_typing()[source]

This function is a coroutine.

Triggers a typing indicator to the destination.

Typing indicator will go away after 10 seconds, or after a message is sent.

property type[source]

The channel’s Discord type.

This always returns ChannelType.group.

Type:

ChannelType

property icon[source]

Returns the channel’s icon asset if available.

Type:

Optional[Asset]

property created_at[source]

Returns the channel’s creation time in UTC.

Type:

datetime.datetime

permissions_for(obj, /, *, ignore_timeout=...)[source]

Handles permission resolution for a User.

This function is there for compatibility with other channel types.

Actual direct messages do not really have the concept of permissions.

This returns all the Permissions.private_channel() permissions set to True.

This also checks the kick_members permission if the user is the owner.

Parameters:

  • obj (Snowflake) – The user to check permissions for.

  • ignore_timeout (bool) – Whether to ignore the guild timeout when checking permsisions. This parameter is ignored but kept for compatibility with other permissions_for methods.

Returns:

The resolved permissions for the user.

Return type:

Permissions

await leave()[source]

This function is a coroutine.

Leaves the group.

If you are the only one in the group, this deletes it as well.

Raises:

HTTPException – Leaving the group failed.

PartialMessageable

Attributes
Methods
class disnake.PartialMessageable[source]

This class is a Discord Model.

Represents a partial messageable to aid with working messageable channels when only a channel ID is present.

The only way to construct this class is through Client.get_partial_messageable().

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

New in version 2.0.

x == y

Checks if two partial messageables are equal.

x != y

Checks if two partial messageables are not equal.

hash(x)

Returns the partial messageable’s hash.

id

The channel ID associated with this partial messageable.

Type:

int

type

The channel type associated with this partial messageable, if given.

Type:

Optional[ChannelType]

await fetch_message(id, /)[source]

This function is a coroutine.

Retrieves a single Message from the destination.

Parameters:

id (int) – The message ID to look for.

Raises:

  • NotFound – The specified message was not found.

  • Forbidden – You do not have the permissions required to get a message.

  • HTTPException – Retrieving the message failed.

Returns:

The message asked for.

Return type:

Message

history(*, limit=100, before=None, after=None, around=None, oldest_first=None)[source]

Returns an AsyncIterator that enables receiving the destination’s message history.

You must have Permissions.read_message_history permission to use this.

Examples

Usage

counter = 0
async for message in channel.history(limit=200):
    if message.author == client.user:
        counter += 1

Flattening into a list:

messages = await channel.history(limit=123).flatten()
# messages is now a list of Message...

All parameters are optional.

Parameters:

  • limit (Optional[int]) – The number of messages to retrieve. If None, retrieves every message in the channel. Note, however, that this would make it a slow operation.

  • before (Optional[Union[abc.Snowflake, datetime.datetime]]) – Retrieve messages before this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

  • after (Optional[Union[abc.Snowflake, datetime.datetime]]) – Retrieve messages after this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

  • around (Optional[Union[abc.Snowflake, datetime.datetime]]) – Retrieve messages around this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time. When using this argument, the maximum limit is 101. Note that if the limit is an even number then this will return at most limit + 1 messages.

  • oldest_first (Optional[bool]) – If set to True, return messages in oldest->newest order. Defaults to True if after is specified, otherwise False.

Raises:

  • Forbidden – You do not have permissions to get channel message history.

  • HTTPException – The request to get message history failed.

Yields:

Message – The message with the message data parsed.

await pins()[source]

This function is a coroutine.

Retrieves all messages that are currently pinned in the channel.

Note

Due to a limitation with the Discord API, the Message objects returned by this method do not contain complete Message.reactions data.

Raises:

HTTPException – Retrieving the pinned messages failed.

Returns:

The messages that are currently pinned.

Return type:

List[Message]

await send(content=None, *, tts=False, embed=None, embeds=None, file=None, files=None, stickers=None, delete_after=None, nonce=None, suppress_embeds=False, allowed_mentions=None, reference=None, mention_author=None, view=None, components=None)[source]

This function is a coroutine.

Sends a message to the destination with the content given.

The content must be a type that can convert to a string through str(content).

At least one of content, embed/embeds, file/files, stickers, components, or view must be provided.

To upload a single file, the file parameter should be used with a single File object. To upload multiple files, the files parameter should be used with a list of File objects. Specifying both parameters will lead to an exception.

To upload a single embed, the embed parameter should be used with a single Embed object. To upload multiple embeds, the embeds parameter should be used with a list of Embed objects. Specifying both parameters will lead to an exception.

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

Parameters:

  • content (Optional[str]) – The content of the message to send.

  • tts (bool) – Whether the message should be sent using text-to-speech.

  • embed (Embed) – The rich embed for the content to send. This cannot be mixed with the embeds parameter.

  • embeds (List[Embed]) –

    A list of embeds to send with the content. Must be a maximum of 10. This cannot be mixed with the embed parameter.

    New in version 2.0.

  • file (File) – The file to upload. This cannot be mixed with the files parameter.

  • files (List[File]) – A list of files to upload. Must be a maximum of 10. This cannot be mixed with the file parameter.

  • stickers (Sequence[Union[GuildSticker, StickerItem]]) –

    A list of stickers to upload. Must be a maximum of 3.

    New in version 2.0.

  • nonce (Union[str, int]) – The nonce to use for sending this message. If the message was successfully sent, then the message will have a nonce with this value.

  • delete_after (float) – If provided, the number of seconds to wait in the background before deleting the message we just sent. If the deletion fails, then it is silently ignored.

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

  • reference (Union[Message, MessageReference, PartialMessage]) –

    A reference to the Message to which you are replying, this can be created using Message.to_reference() or passed directly as a Message. You can control whether this mentions the author of the referenced message using the AllowedMentions.replied_user attribute of allowed_mentions or by setting mention_author.

    New in version 1.6.

  • mention_author (Optional[bool]) –

    If set, overrides the AllowedMentions.replied_user attribute of allowed_mentions.

    New in version 1.6.

  • view (ui.View) –

    A Discord UI View to add to the message. This cannot be mixed with components.

    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]]]]) –

    A list of components to include in the message. This cannot be mixed with view.

    New in version 2.4.

  • suppress_embeds (bool) –

    Whether to suppress embeds for the message. This hides all embeds from the UI if set to True.

    New in version 2.5.

Raises:
Returns:

The message that was sent.

Return type:

Message

await trigger_typing()[source]

This function is a coroutine.

Triggers a typing indicator to the destination.

Typing indicator will go away after 10 seconds, or after a message is sent.

typing()[source]

Returns a context manager that allows you to type for an indefinite period of time.

This is useful for denoting long computations in your bot.

Note

This is both a regular context manager and an async context manager. This means that both with and async with work with this.

Example Usage:

async with channel.typing():
    # simulate something heavy
    await asyncio.sleep(10)

await channel.send('done!')
get_partial_message(message_id, /)[source]

Creates a PartialMessage from the given message ID.

This is useful if you want to work with a message and only have its ID without doing an unnecessary API call.

Parameters:

message_id (int) – The message ID to create a partial message for.

Returns:

The partial message object.

Return type:

PartialMessage

Data Classes

ChannelFlags

Attributes
class disnake.ChannelFlags(**kwargs)[source]

This class is a Data Class.

Wraps up the Discord Channel flags.

x == y

Checks if two ChannelFlags instances are equal.

x != y

Checks if two ChannelFlags instances are not equal.

x <= y

Checks if a ChannelFlags instance is a subset of another ChannelFlags instance.

New in version 2.6.

x >= y

Checks if a ChannelFlags instance is a superset of another ChannelFlags instance.

New in version 2.6.

x < y

Checks if a ChannelFlags instance is a strict subset of another ChannelFlags instance.

New in version 2.6.

x > y

Checks if a ChannelFlags instance is a strict superset of another ChannelFlags instance.

New in version 2.6.

x | y, x |= y

Returns a new ChannelFlags 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 ChannelFlags 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 ChannelFlags 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 ChannelFlags 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. Note that aliases are not shown.

Additionally supported are a few operations on class attributes.

ChannelFlags.y | ChannelFlags.z, ChannelFlags(y=True) | ChannelFlags.z

Returns a ChannelFlags instance with all provided flags enabled.

New in version 2.6.

~ChannelFlags.y

Returns a ChannelFlags instance with all flags except y inverted from their default value.

New in version 2.6.

New in version 2.5.

value

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

Type:

int

pinned

Returns True if the thread is pinned.

This only applies to channels of type Thread.

Type:

bool

require_tag

Returns True if the channel requires all newly created threads to have a tag.

This only applies to channels of type ForumChannel.

New in version 2.6.

Type:

bool

RawThreadDeleteEvent

Attributes
class disnake.RawThreadDeleteEvent[source]

This class is a Data Class.

Represents the payload for a on_raw_thread_delete() event.

New in version 2.5.

thread_id

The ID of the thread that was deleted.

Type:

int

guild_id

The ID of the guild the thread was deleted in.

Type:

int

thread_type

The type of the deleted thread.

Type:

ChannelType

parent_id

The ID of the channel the thread belonged to.

Type:

int

thread

The thread, if it could be found in the internal cache.

Type:

Optional[Thread]

RawThreadMemberRemoveEvent

Attributes
class disnake.RawThreadMemberRemoveEvent[source]

This class is a Data Class.

Represents the event payload for an on_raw_thread_member_remove() event.

New in version 2.5.

thread

The Thread that the member was removed from

Type:

Thread

member_id

The ID of the removed member.

Type:

int

cached_member

The member, if they could be found in the internal cache.

Type:

Optional[ThreadMember]

Enumerations

ChannelType

class disnake.ChannelType[source]

This class is an Enumeration.

Specifies the type of channel.

text

A text channel.

voice

A voice channel.

private

A private text channel. Also called a direct message.

group

A private group text channel.

category

A category channel.

news

A guild news channel.

stage_voice

A guild stage voice channel.

New in version 1.7.

news_thread

A news thread.

New in version 2.0.

public_thread

A public thread.

New in version 2.0.

private_thread

A private thread.

New in version 2.0.

guild_directory

A student hub channel.

New in version 2.1.

forum

A channel of only threads.

New in version 2.5.

ThreadArchiveDuration

class disnake.ThreadArchiveDuration[source]

This class is an Enumeration.

Represents the automatic archive duration of a thread in minutes.

New in version 2.3.

hour

The thread will archive after an hour of inactivity.

day

The thread will archive after a day of inactivity.

three_days

The thread will archive after three days of inactivity.

week

The thread will archive after a week of inactivity.

VideoQualityMode

class disnake.VideoQualityMode[source]

This class is an Enumeration.

Represents the camera video quality mode for voice channel participants.

New in version 2.0.

auto

Represents auto camera video quality.

full

Represents full camera video quality.

ThreadSortOrder

class disnake.ThreadSortOrder[source]

Represents the sort order of threads in ForumChannels.

New in version 2.6.

latest_activity

Sort forum threads by activity.

creation_date

Sort forum threads by creation date/time (from newest to oldest).

Events

See all related events!