Webhooks

This section documents all objects related to webhooks, a low-effort way of sending messages in channels without a user/bot account.

Discord Models

Webhook

Attributes
Methods
class disnake.Webhook[source]

Represents an asynchronous Discord webhook.

Webhooks are a form to send messages to channels in Discord without a bot user or authentication.

There are two main ways to use Webhooks. The first is through the ones received by the library such as Guild.webhooks(), TextChannel.webhooks(), VoiceChannel.webhooks(), ForumChannel.webhooks(), MediaChannel.webhooks() and StageChannel.webhooks(). The ones received by the library will automatically be bound using the library’s internal HTTP session.

The second form involves creating a webhook object manually using the from_url() or partial() classmethods.

For example, creating a webhook from a URL and using aiohttp:

from disnake import Webhook
import aiohttp

async def foo():
    async with aiohttp.ClientSession() as session:
        webhook = Webhook.from_url('url-here', session=session)
        await webhook.send('Hello World', username='Foo')

For a synchronous counterpart, see SyncWebhook.

x == y

Checks if two webhooks are equal.

x != y

Checks if two webhooks are not equal.

hash(x)

Returns the webhooks’s hash.

Changed in version 1.4: Webhooks are now comparable and hashable.

id

The webhook’s ID

Type:

int

type

The webhook’s type.

New in version 1.3.

Type:

WebhookType

token

The authentication token of the webhook. If this is None then the webhook cannot be used to make requests.

Type:

str | None

guild_id

The guild ID this webhook belongs to.

Type:

int | None

channel_id

The channel ID this webhook belongs to.

Type:

int | None

user

The user this webhook was created by. If the webhook was received without authentication then this will be None.

Type:

abc.User | None

name

The default name of the webhook.

Type:

str | None

source_guild

The guild of the channel that this webhook is following. Only given if type is WebhookType.channel_follower.

New in version 2.0.

Type:

PartialWebhookGuild | None

source_channel

The channel that this webhook is following. Only given if type is WebhookType.channel_follower.

New in version 2.0.

Type:

PartialWebhookChannel | None

application_id

The ID of the application associated with this webhook, if it was created by an application.

New in version 2.6.

Type:

int | None

property url[source]

Returns the webhook’s url.

Type:

str

classmethod partial(id, token, *, session, bot_token=None)[source]

Creates a partial Webhook.

Parameters:

  • id (int) – The webhook’s ID.

  • token (str) – The webhook’s authentication token.

  • session (aiohttp.ClientSession) –

    The session to use to send requests with. Note that the library does not manage the session and will not close it.

    New in version 2.0.

  • bot_token (str | None) –

    The bot authentication token for authenticated requests involving the webhook.

    New in version 2.0.

Returns:

A partial Webhook. A partial webhook is just a webhook object with an ID and a token.

Return type:

Webhook

classmethod from_url(url, *, session, bot_token=None)[source]

Creates a partial Webhook from a webhook URL.

Changed in version 2.6: Raises ValueError instead of InvalidArgument.

Parameters:

  • url (str) – The webhook’s URL.

  • session (aiohttp.ClientSession) –

    The session to use to send requests with. Note that the library does not manage the session and will not close it.

    New in version 2.0.

  • bot_token (str | None) –

    The bot authentication token for authenticated requests involving the webhook.

    New in version 2.0.

Raises:

ValueError – The URL is invalid.

Returns:

A partial Webhook. A partial webhook is just a webhook object with an ID and a token.

Return type:

Webhook

await fetch(*, prefer_auth=True)[source]

This function is a coroutine.

Fetches the current webhook.

This could be used to get a full webhook from a partial webhook.

New in version 2.0.

Note

When fetching with an unauthenticated webhook, i.e. is_authenticated() returns False, then the returned webhook does not contain any user information.

Changed in version 2.6: Raises WebhookTokenMissing instead of InvalidArgument.

Parameters:

prefer_auth (bool) – Whether to use the bot token over the webhook token, if available. Defaults to True.

Raises:
Returns:

The fetched webhook.

Return type:

Webhook

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

This function is a coroutine.

Deletes this Webhook.

Changed in version 2.6: Raises WebhookTokenMissing instead of InvalidArgument.

Parameters:

  • reason (str | None) –

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

    New in version 1.4.

  • prefer_auth (bool) –

    Whether to use the bot token over the webhook token, if available. Defaults to True.

    New in version 2.0.

Raises:
await edit(*, reason=None, name=..., avatar=..., channel=None, prefer_auth=True)[source]

This function is a coroutine.

Edits this Webhook.

Changed in version 2.6: Raises WebhookTokenMissing instead of InvalidArgument.

Parameters:

  • name (str | None) – The webhook’s new default name.

  • avatar (bytes | Asset | Emoji | PartialEmoji | StickerItem | Sticker | None) –

    The webhook’s new default avatar.

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

  • channel (abc.Snowflake | None) –

    The webhook’s new channel. This requires an authenticated webhook.

    New in version 2.0.

  • prefer_auth (bool) –

    Whether to use the bot token over the webhook token if available. Defaults to True.

    New in version 2.0.

  • reason (str | None) –

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

    New in version 1.4.

Raises:

  • HTTPException – Editing the webhook failed.

  • NotFound – This webhook does not exist or the avatar asset couldn’t be found.

  • TypeError – The avatar asset is a lottie sticker (see Sticker.read()).

  • WebhookTokenMissing – This webhook does not have a token associated with it or it tried editing a channel without authentication.

Returns:

The newly edited webhook.

Return type:

Webhook

property avatar[source]

Returns an Asset for the avatar the webhook has.

If the webhook does not have a traditional avatar, an asset for the default avatar is returned instead.

Type:

Asset

property channel[source]

The channel this webhook belongs to.

If this is a partial webhook, then this will always return None.

Webhooks in a ForumChannel or MediaChannel can not send messages directly. They can only create new threads (see thread_name for Webhook.send) and interact with existing threads.

Type:

TextChannel | VoiceChannel | StageChannel | ForumChannel | MediaChannel | None

property created_at[source]

Returns the webhook’s creation time in UTC.

Type:

datetime.datetime

property guild[source]

The guild this webhook belongs to.

If this is a partial webhook, then this will always return None.

Type:

Guild | None

is_authenticated()[source]

Whether the webhook is authenticated with a bot token.

New in version 2.0.

Return type:

bool

is_partial()[source]

Whether the webhook is a “partial” webhook.

New in version 2.0.

Return type:

bool

await send(content=..., *, username=..., avatar_url=..., tts=False, ephemeral=..., suppress_embeds=..., flags=..., file=..., files=..., embed=..., embeds=..., allowed_mentions=..., view=..., components=..., thread=..., thread_name=..., applied_tags=..., wait=False, delete_after=..., poll=...)[source]

This function is a coroutine.

Sends a message using the webhook.

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

To upload a single file, the file parameter should be used with a single File object.

If the embed parameter is provided, it must be of type Embed and it must be a rich embed type. You cannot mix the embed parameter with the embeds parameter, which must be a list of Embed objects to send.

To send a message in a thread, provide the thread parameter. If this webhook is in a ForumChannel/MediaChannel, the thread_name parameter can be used to create a new thread instead (optionally with applied_tags).

Changed in version 2.6: Raises WebhookTokenMissing instead of InvalidArgument.

Parameters:

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

  • username (str) – The username to send with this message. If no username is provided then the default username for the webhook is used.

  • avatar_url (str) – The avatar URL to send with this message. If no avatar URL is provided then the default avatar for the webhook is used. If this is not a string then it is explicitly cast using str.

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

  • ephemeral (bool) –

    Whether the message should only be visible to the user. This is only available to WebhookType.application webhooks. If a view is sent with an ephemeral message and it has no timeout set then the timeout is set to 15 minutes.

    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.

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

  • allowed_mentions (AllowedMentions) –

    Controls the mentions being processed in this message. If this is passed, then the object is merged with Client.allowed_mentions, if applicable. The merging behaviour only overrides attributes that have been explicitly passed to the object, otherwise it uses the attributes set in Client.allowed_mentions. If no object is passed at all then the defaults given by Client.allowed_mentions are used instead.

    New in version 1.4.

  • view (disnake.ui.View) –

    The view to send with the message. You can only send a view if this webhook is not partial and has state attached. A webhook has state attached if the webhook is managed by the library. This cannot be mixed with components.

    New in version 2.0.

  • components (UIComponent | list[UIComponent | list[WrappedComponent]]) –

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

    New in version 2.4.

    Note

    Passing v2 components here automatically sets the is_components_v2 flag. Setting this flag cannot be reverted. Note that this also disables the content, embeds, and poll fields.

    Note

    Non-application-owned webhooks can only send non-interactive components, e.g. link buttons or v2 layout components.

  • thread (Snowflake) –

    The thread to send this message to.

    New in version 2.0.

  • thread_name (str) –

    If in a forum/media channel, and thread is not specified, the name of the newly created thread.

    Note

    If this is set, the returned message’s channel (assuming wait=True), representing the created thread, may be a PartialMessageable.

    New in version 2.6.

  • applied_tags (Sequence[abc.Snowflake]) –

    If in a forum/media channel and creating a new thread (see thread_name above), the tags to apply to the new thread. Maximum of 5.

    New in version 2.10.

  • wait (bool) – Whether the server should wait before sending a response. This essentially means that the return type of this function changes from None to a WebhookMessage if set to True. If the type of webhook is WebhookType.application then this is always set to True.

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

    New in version 2.1.

    Changed in version 2.7: Added support for ephemeral interaction responses.

  • suppress_embeds (bool) –

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

    New in version 2.5.

  • flags (MessageFlags) –

    The flags to set for this message. Only suppress_embeds, ephemeral, suppress_notifications, and is_components_v2 are supported.

    If parameters suppress_embeds or ephemeral are provided, they will override the corresponding setting of this flags parameter.

    New in version 2.9.

  • poll (Poll) –

    The poll to send with the message.

    New in version 2.10.

Raises:

  • HTTPException – Sending the message failed.

  • NotFound – This webhook was not found.

  • Forbidden – The authorization token for the webhook is incorrect.

  • TypeError – Raised by any of the following: You specified both embed and embeds or file and files. ephemeral was passed with the improper webhook type. There was no state attached with this webhook when giving it a view. Both thread and thread_name/applied_tags were provided.

  • WebhookTokenMissing – There was no token associated with this webhook.

  • ValueError – The length of embeds was invalid, or you tried to send v2 components together with content, embeds, or poll.

Returns:

If wait is True then the message that was sent, otherwise None.

Return type:

WebhookMessage | None

await fetch_message(id, *, thread=None)[source]

This function is a coroutine.

Retrieves a single WebhookMessage owned by this webhook.

New in version 2.0.

Changed in version 2.6: Raises WebhookTokenMissing instead of InvalidArgument.

Parameters:

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

  • thread (Snowflake | None) –

    The thread the message is in, if any.

    New in version 2.10.

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.

  • WebhookTokenMissing – There was no token associated with this webhook.

Returns:

The message asked for.

Return type:

WebhookMessage

await edit_message(message_id, *, content=..., embed=..., embeds=..., file=..., files=..., attachments=..., view=..., components=..., flags=..., allowed_mentions=None, thread=None)[source]

This function is a coroutine.

Edits a message owned by this webhook.

This is a lower level interface to WebhookMessage.edit() in case you only have an ID.

Note

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

New in version 1.6.

Changed in version 2.0: The edit is no longer in-place, instead the newly edited message is returned.

Changed in version 2.6: Raises WebhookTokenMissing instead of InvalidArgument.

Parameters:

  • message_id (int) – The ID of the message to edit.

  • content (str | None) – The content to edit the message with, or None to clear it.

  • embed (Embed | None) – The new embed to replace the original with. This cannot be mixed with the embeds parameter. Could be None to remove the embed.

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

  • file (File) –

    The file to upload. This cannot be mixed with the files parameter. Files will be appended to the message, see the attachments parameter to remove/replace existing files.

    New in version 2.0.

  • files (list[File]) –

    A list of files to upload. This cannot be mixed with the file parameter. Files will be appended to the message, see the attachments parameter to remove/replace existing files.

    New in version 2.0.

  • attachments (list[Attachment] | None) –

    A list of attachments to keep in the message. If [] or None is passed then all existing attachments are removed. Keeps existing attachments if not provided.

    New in version 2.2.

    Changed in version 2.5: Supports passing None to clear attachments.

  • view (View | None) –

    The updated view to update this message with. If None is passed then the view is removed. The webhook must have state attached, similar to send(). This cannot be mixed with components.

    New in version 2.0.

  • components (UIComponent | list[UIComponent | list[WrappedComponent]] | None) –

    A list of components to update this message with. This cannot be mixed with view. If None is passed then the components are removed.

    New in version 2.4.

    Note

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

  • flags (MessageFlags) –

    The new flags to set for this message. Overrides existing flags. Only suppress_embeds and is_components_v2 are supported.

    New in version 2.11.

  • allowed_mentions (AllowedMentions) – Controls the mentions being processed in this message. See abc.Messageable.send() for more information.

  • thread (Snowflake | None) –

    The thread the message is in, if any.

    New in version 2.10.

Raises:

  • HTTPException – Editing the message failed.

  • Forbidden – Edited a message that is not yours.

  • TypeError – You specified both embed and embeds or file and files or there is no associated state when sending a view.

  • WebhookTokenMissing – There was no token associated with this webhook.

  • ValueError – The length of embeds was invalid, or you tried to send v2 components together with content or embeds.

Returns:

The newly edited webhook message.

Return type:

WebhookMessage

await delete_message(message_id, /, *, thread=None)[source]

This function is a coroutine.

Deletes a message owned by this webhook.

This is a lower level interface to WebhookMessage.delete() in case you only have an ID.

New in version 1.6.

Changed in version 2.6: Raises WebhookTokenMissing instead of InvalidArgument.

Parameters:

  • message_id (int) – The ID of the message to delete.

  • thread (Snowflake | None) –

    The thread the message is in, if any.

    New in version 2.10.

Raises:

WebhookMessage

Methods
class disnake.WebhookMessage[source]

Represents a message sent from your webhook.

This allows you to edit or delete a message sent by your webhook.

This inherits from disnake.Message with changes to edit() and delete() to work.

New in version 1.6.

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

This function is a coroutine.

Edits the message.

New in version 1.6.

Changed in version 2.0: The edit is no longer in-place, instead the newly edited message is returned.

Note

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

Parameters:

  • content (str | None) – The content to edit the message with, or None to clear it.

  • embed (Embed | None) – The new embed to replace the original with. This cannot be mixed with the embeds parameter. Could be None to remove the embed.

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

  • file (File) –

    The file to upload. This cannot be mixed with the files parameter. Files will be appended to the message, see the attachments parameter to remove/replace existing files.

    New in version 2.0.

  • files (list[File]) –

    A list of files to upload. This cannot be mixed with the file parameter. Files will be appended to the message, see the attachments parameter to remove/replace existing files.

    New in version 2.0.

  • attachments (list[Attachment] | None) –

    A list of attachments to keep in the message. If [] or None is passed then all existing attachments are removed. Keeps existing attachments if not provided.

    New in version 2.2.

    Changed in version 2.5: Supports passing None to clear attachments.

  • view (View | None) –

    The view to update this message with. This cannot be mixed with components. If None is passed then the view is removed.

    New in version 2.0.

  • components (UIComponent | list[UIComponent | list[WrappedComponent]] | None) –

    A list of components to update the message with. This cannot be mixed with view. If None is passed then the components are removed.

    New in version 2.4.

    Note

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

  • flags (MessageFlags) –

    The new flags to set for this message. Overrides existing flags. Only suppress_embeds and is_components_v2 are supported.

    New in version 2.11.

  • allowed_mentions (AllowedMentions) – Controls the mentions being processed in this message. See abc.Messageable.send() for more information.

Raises:

  • HTTPException – Editing the message failed.

  • Forbidden – Edited a message that is not yours.

  • TypeError – You specified both embed and embeds or file and files.

  • ValueError – The length of embeds was invalid, or you tried to send v2 components together with content or embeds.

  • WebhookTokenMissing – There was no token associated with this webhook.

Returns:

The newly edited message.

Return type:

WebhookMessage

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

This function is a coroutine.

Deletes the message.

Parameters:

delay (float | None) – If provided, the number of seconds to wait before deleting the message. The waiting is done in the background and deletion failures are ignored.

Raises:

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

  • NotFound – The message was deleted already.

  • HTTPException – Deleting the message failed.

SyncWebhook

Attributes
Methods
class disnake.SyncWebhook[source]

Represents a synchronous Discord webhook.

For an asynchronous counterpart, see Webhook.

x == y

Checks if two webhooks are equal.

x != y

Checks if two webhooks are not equal.

hash(x)

Returns the webhooks’s hash.

Changed in version 1.4: Webhooks are now comparable and hashable.

id

The webhook’s ID

Type:

int

type

The webhook’s type.

New in version 1.3.

Type:

WebhookType

token

The authentication token of the webhook. If this is None then the webhook cannot be used to make requests.

Type:

str | None

guild_id

The guild ID this webhook belongs to.

Type:

int | None

channel_id

The channel ID this webhook belongs to.

Type:

int | None

user

The user this webhook was created by. If the webhook was received without authentication then this will be None.

Type:

abc.User | None

name

The default name of the webhook.

Type:

str | None

source_guild

The guild of the channel that this webhook is following. Only given if type is WebhookType.channel_follower.

New in version 2.0.

Type:

PartialWebhookGuild | None

source_channel

The channel that this webhook is following. Only given if type is WebhookType.channel_follower.

New in version 2.0.

Type:

PartialWebhookChannel | None

application_id

The ID of the application associated with this webhook, if it was created by an application.

New in version 2.6.

Type:

int | None

property url[source]

Returns the webhook’s url.

Type:

str

classmethod partial(id, token, *, session=..., bot_token=None)[source]

Creates a partial SyncWebhook.

Parameters:

  • id (int) – The webhook’s ID.

  • token (str) – The webhook’s authentication token.

  • session (requests.Session) – The session to use to send requests with. Note that the library does not manage the session and will not close it. If not given, the requests auto session creation functions are used instead.

  • bot_token (str | None) – The bot authentication token for authenticated requests involving the webhook.

Returns:

A partial SyncWebhook. A partial webhook is just a webhook object with an ID and a token.

Return type:

SyncWebhook

classmethod from_url(url, *, session=..., bot_token=None)[source]

Creates a partial SyncWebhook from a webhook URL.

Changed in version 2.6: Raises ValueError instead of InvalidArgument.

Parameters:

  • url (str) – The webhook’s URL.

  • session (requests.Session) – The session to use to send requests with. Note that the library does not manage the session and will not close it. If not given, the requests auto session creation functions are used instead.

  • bot_token (str | None) – The bot authentication token for authenticated requests involving the webhook.

Raises:

ValueError – The URL is invalid.

Returns:

A partial SyncWebhook. A partial webhook is just a webhook object with an ID and a token.

Return type:

SyncWebhook

fetch(*, prefer_auth=True)[source]

Fetches the current webhook.

This could be used to get a full webhook from a partial webhook.

Note

When fetching with an unauthenticated webhook, i.e. is_authenticated() returns False, then the returned webhook does not contain any user information.

Changed in version 2.6: Raises WebhookTokenMissing instead of InvalidArgument.

Parameters:

prefer_auth (bool) – Whether to use the bot token over the webhook token, if available. Defaults to True.

Raises:
Returns:

The fetched webhook.

Return type:

SyncWebhook

delete(*, reason=None, prefer_auth=True)[source]

Deletes this Webhook.

Changed in version 2.6: Raises WebhookTokenMissing instead of InvalidArgument.

Parameters:

  • reason (str | None) –

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

    New in version 1.4.

  • prefer_auth (bool) – Whether to use the bot token over the webhook token, if available. Defaults to True.

Raises:
edit(*, reason=None, name=..., avatar=..., channel=None, prefer_auth=True)[source]

Edits this Webhook.

Changed in version 2.6: Raises WebhookTokenMissing instead of InvalidArgument.

Parameters:

  • name (str | None) – The webhook’s new default name.

  • avatar (bytes | None) – A bytes-like object representing the webhook’s new default avatar.

  • channel (abc.Snowflake | None) – The webhook’s new channel. This requires an authenticated webhook.

  • prefer_auth (bool) – Whether to use the bot token over the webhook token if available. Defaults to True.

  • reason (str | None) –

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

    New in version 1.4.

Raises:

  • HTTPException – Editing the webhook failed.

  • NotFound – This webhook does not exist.

  • WebhookTokenMissing – This webhook does not have a token associated with it or it tried editing a channel without authentication.

Returns:

The newly edited webhook.

Return type:

SyncWebhook

property avatar[source]

Returns an Asset for the avatar the webhook has.

If the webhook does not have a traditional avatar, an asset for the default avatar is returned instead.

Type:

Asset

property channel[source]

The channel this webhook belongs to.

If this is a partial webhook, then this will always return None.

Webhooks in a ForumChannel or MediaChannel can not send messages directly. They can only create new threads (see thread_name for Webhook.send) and interact with existing threads.

Type:

TextChannel | VoiceChannel | StageChannel | ForumChannel | MediaChannel | None

property created_at[source]

Returns the webhook’s creation time in UTC.

Type:

datetime.datetime

property guild[source]

The guild this webhook belongs to.

If this is a partial webhook, then this will always return None.

Type:

Guild | None

is_authenticated()[source]

Whether the webhook is authenticated with a bot token.

New in version 2.0.

Return type:

bool

is_partial()[source]

Whether the webhook is a “partial” webhook.

New in version 2.0.

Return type:

bool

send(content=..., *, username=..., avatar_url=..., tts=False, file=..., files=..., embed=..., embeds=..., suppress_embeds=..., flags=..., allowed_mentions=..., thread=..., thread_name=..., applied_tags=..., wait=False)[source]

Sends a message using the webhook.

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

To upload a single file, the file parameter should be used with a single File object.

If the embed parameter is provided, it must be of type Embed and it must be a rich embed type. You cannot mix the embed parameter with the embeds parameter, which must be a list of Embed objects to send.

To send a message in a thread, provide the thread parameter. If this webhook is in a ForumChannel/MediaChannel, the thread_name parameter can be used to create a new thread instead (optionally with applied_tags).

Changed in version 2.6: Raises WebhookTokenMissing instead of InvalidArgument.

Parameters:

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

  • username (str) – The username to send with this message. If no username is provided then the default username for the webhook is used.

  • avatar_url (str) – The avatar URL to send with this message. If no avatar URL is provided then the default avatar for the webhook is used. If this is not a string then it is explicitly cast using str.

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

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

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

  • allowed_mentions (AllowedMentions) –

    Controls the mentions being processed in this message.

    New in version 1.4.

  • thread (Snowflake) –

    The thread to send this message to.

    New in version 2.0.

  • thread_name (str) –

    If in a forum/media channel, and thread is not specified, the name of the newly created thread.

    New in version 2.6.

  • applied_tags (Sequence[abc.Snowflake]) –

    If in a forum/media channel and creating a new thread (see thread_name above), the tags to apply to the new thread. Maximum of 5.

    New in version 2.10.

  • suppress_embeds (bool) –

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

    New in version 2.5.

  • flags (MessageFlags) –

    The flags to set for this message. Only suppress_embeds and suppress_notifications are supported.

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

    New in version 2.9.

  • wait (bool) – Whether the server should wait before sending a response. This essentially means that the return type of this function changes from None to a WebhookMessage if set to True.

Raises:

  • HTTPException – Sending the message failed.

  • NotFound – This webhook was not found.

  • Forbidden – The authorization token for the webhook is incorrect.

  • TypeError – You specified both embed and embeds or file and files, or both thread and thread_name/applied_tags were provided.

  • ValueError – The length of embeds was invalid

  • WebhookTokenMissing – There was no token associated with this webhook.

Returns:

If wait is True then the message that was sent, otherwise None.

Return type:

SyncWebhookMessage | None

fetch_message(id, /, *, thread=None)[source]

Retrieves a single SyncWebhookMessage owned by this webhook.

New in version 2.0.

Changed in version 2.6: Raises WebhookTokenMissing instead of InvalidArgument.

Parameters:

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

  • thread (Snowflake | None) –

    The thread the message is in, if any.

    New in version 2.10.

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.

  • WebhookTokenMissing – There was no token associated with this webhook.

Returns:

The message asked for.

Return type:

SyncWebhookMessage

edit_message(message_id, *, content=..., embed=..., embeds=..., file=..., files=..., attachments=..., allowed_mentions=None, thread=None)[source]

Edits a message owned by this webhook.

This is a lower level interface to WebhookMessage.edit() in case you only have an ID.

Note

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

New in version 1.6.

Changed in version 2.6: Raises WebhookTokenMissing instead of InvalidArgument.

Parameters:

  • message_id (int) – The ID of the message to edit.

  • content (str | None) – The content to edit the message with, or None to clear it.

  • embed (Embed | None) – The new embed to replace the original with. This cannot be mixed with the embeds parameter. Could be None to remove the embed.

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

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

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

  • attachments (list[Attachment] | None) –

    A list of attachments to keep in the message. If [] or None is passed then all existing attachments are removed. Keeps existing attachments if not provided.

    New in version 2.2.

    Changed in version 2.5: Supports passing None to clear attachments.

  • allowed_mentions (AllowedMentions) – Controls the mentions being processed in this message. See abc.Messageable.send() for more information.

  • thread (Snowflake | None) –

    The thread the message is in, if any.

    New in version 2.10.

Raises:
delete_message(message_id, /, *, thread=None)[source]

Deletes a message owned by this webhook.

This is a lower level interface to WebhookMessage.delete() in case you only have an ID.

New in version 1.6.

Changed in version 2.6: Raises WebhookTokenMissing instead of InvalidArgument.

Parameters:

  • message_id (int) – The ID of the message to delete.

  • thread (Snowflake | None) –

    The thread the message is in, if any.

    New in version 2.10.

Raises:

SyncWebhookMessage

Methods
class disnake.SyncWebhookMessage[source]

Represents a message sent from your webhook.

This allows you to edit or delete a message sent by your webhook.

This inherits from disnake.Message with changes to edit() and delete() to work.

New in version 2.0.

edit(content=..., embed=..., embeds=..., file=..., files=..., attachments=..., allowed_mentions=None)[source]

Edits the message.

Note

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

Changed in version 2.6: Raises WebhookTokenMissing instead of InvalidArgument.

Parameters:

  • content (str | None) – The content to edit the message with or None to clear it.

  • embed (Embed | None) – The new embed to replace the original with. This cannot be mixed with the embeds parameter. Could be None to remove the embed.

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

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

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

  • attachments (list[Attachment] | None) –

    A list of attachments to keep in the message. If [] or None is passed then all existing attachments are removed. Keeps existing attachments if not provided.

    New in version 2.2.

    Changed in version 2.5: Supports passing None to clear attachments.

  • allowed_mentions (AllowedMentions) – Controls the mentions being processed in this message. See abc.Messageable.send() for more information.

Raises:
Returns:

The newly edited message.

Return type:

SyncWebhookMessage

delete(*, delay=None)[source]

Deletes the message.

Changed in version 2.6: Raises WebhookTokenMissing instead of InvalidArgument.

Parameters:

delay (float | None) – If provided, the number of seconds to wait before deleting the message. This blocks the thread.

Raises:

PartialWebhookGuild

Attributes
class disnake.PartialWebhookGuild[source]

Represents a partial guild for webhooks.

These are typically given for channel follower webhooks.

New in version 2.0.

id

The partial guild’s ID.

Type:

int

name

The partial guild’s name.

Type:

str

property icon[source]

Returns the guild’s icon asset, if available.

Type:

Asset | None

PartialWebhookChannel

Attributes
class disnake.PartialWebhookChannel[source]

Represents a partial channel for webhooks.

These are typically given for channel follower webhooks.

New in version 2.0.

id

The partial channel’s ID.

Type:

int

name

The partial channel’s name.

Type:

str

Enumerations

WebhookType

class disnake.WebhookType[source]

Represents the type of webhook that can be received.

New in version 1.3.

incoming

Represents a webhook that can post messages to channels with a token.

channel_follower

Represents a webhook that is internally managed by Discord, used for following channels.

application

Represents a webhook that is used for interactions or applications.

New in version 2.0.

Events