#  hikari webhooks 

Application and entities that are used to describe webhooks on Discord.

### This module

Expand source code
Browse git
# -*- coding: utf-8 -*-
# cython: language_level=3
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in all
# copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
# SOFTWARE.
"""Application and entities that are used to describe webhooks on Discord."""

from __future__ import annotations

__all__: typing.Sequence[str] = (
"ApplicationWebhook",
"ChannelFollowerWebhook",
"ExecutableWebhook",
"PartialWebhook",
"WebhookType",
"IncomingWebhook",
)

import abc
import typing

import attr

from hikari import channels as channels_
from hikari import snowflakes
from hikari import undefined
from hikari import urls
from hikari.internal import attr_extensions
from hikari.internal import enums
from hikari.internal import routes

if typing.TYPE_CHECKING:
from hikari import embeds as embeds_
from hikari import files
from hikari import files as files_
from hikari import guilds as guilds_
from hikari import messages as messages_
from hikari import traits
from hikari import users as users_
from hikari.api import special_endpoints

@typing.final
class WebhookType(int, enums.Enum):
"""Types of webhook."""

INCOMING = 1
"""Incoming webhook."""

CHANNEL_FOLLOWER = 2
"""Channel Follower webhook."""

APPLICATION = 3
"""Application webhook (from the interactions flow)."""

class ExecutableWebhook(abc.ABC):
"""An abstract class with logic for executing entities as webhooks."""

# This is a mixin, do not add slotted fields.
__slots__: typing.Sequence[str] = ()

@property
@abc.abstractmethod
def app(self) -> traits.RESTAware:
"""Client application that models may use for procedures.

Returns
-------
hikari.traits.RESTAware
The client application that models may use for procedures.
"""

@property
@abc.abstractmethod
def webhook_id(self) -> snowflakes.Snowflake:
"""ID used to execute this entity as a webhook.

Returns
-------
hikari.snowflakes.Snowflake
The ID used to execute this entity as a webhook.
"""

@property
@abc.abstractmethod
def token(self) -> typing.Optional[str]:
"""Webhook's token.

!!! info
If this is builtins.None then the methods provided by ExecutableWebhook
will always raise a builtins.ValueError.

Returns
-------
typing.Optional[builtins.str]
The token for the webhook if known, else builtins.None.
"""

async def execute(
self,
content: undefined.UndefinedOr[typing.Any] = undefined.UNDEFINED,
*,
avatar_url: typing.Union[undefined.UndefinedType, str, files.URL] = undefined.UNDEFINED,
tts: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
attachment: undefined.UndefinedOr[files_.Resourceish] = undefined.UNDEFINED,
attachments: undefined.UndefinedOr[typing.Sequence[files_.Resourceish]] = undefined.UNDEFINED,
component: undefined.UndefinedOr[special_endpoints.ComponentBuilder] = undefined.UNDEFINED,
components: undefined.UndefinedOr[typing.Sequence[special_endpoints.ComponentBuilder]] = undefined.UNDEFINED,
embed: undefined.UndefinedOr[embeds_.Embed] = undefined.UNDEFINED,
embeds: undefined.UndefinedOr[typing.Sequence[embeds_.Embed]] = undefined.UNDEFINED,
mentions_everyone: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
user_mentions: undefined.UndefinedOr[
typing.Union[snowflakes.SnowflakeishSequence[users_.PartialUser], bool]
] = undefined.UNDEFINED,
role_mentions: undefined.UndefinedOr[
typing.Union[snowflakes.SnowflakeishSequence[guilds_.PartialRole], bool]
] = undefined.UNDEFINED,
flags: typing.Union[undefined.UndefinedType, int, messages_.MessageFlag] = undefined.UNDEFINED,
) -> messages_.Message:
"""Execute the webhook to create a message.

Parameters
----------
content : hikari.undefined.UndefinedOr[typing.Any]
If provided, the message contents. If
hikari.undefined.UNDEFINED, then nothing will be sent
in the content. Any other value here will be cast to a
builtins.str.

If this is a hikari.embeds.Embed and no embed kwarg is
provided, then this will instead update the embed. This allows for
simpler syntax when sending an embed alone.

Likewise, if this is a hikari.files.Resource, then the
content is instead treated as an attachment if no attachment and
no attachments kwargs are provided.

Other Parameters
----------------
for this request.
avatar_url : typing.Union[hikari.undefined.UndefinedType, builtins.str, hikari.files.URL]
If provided, the url of an image to override the webhook's
avatar with for this request.
tts : hikari.undefined.UndefinedOr[bool]
If provided, whether the message will be sent as a TTS message.
attachment : hikari.undefined.UndefinedOr[hikari.files.Resourceish]
If provided, the message attachment. This can be a resource,
or string of a path on your computer or a URL.
attachments : hikari.undefined.UndefinedOr[typing.Sequence[hikari.files.Resourceish]]
If provided, the message attachments. These can be resources, or
strings consisting of paths on your computer or URLs.
component : hikari.undefined.UndefinedOr[hikari.api.special_endpoints.ComponentBuilder]
If provided, builder object of the component to include in this message.
components : hikari.undefined.UndefinedOr[typing.Sequence[hikari.api.special_endpoints.ComponentBuilder]]
If provided, a sequence of the component builder objects to include
in this message.
embed : hikari.undefined.UndefinedOr[hikari.embeds.Embed]
If provided, the message embed.
embeds : hikari.undefined.UndefinedOr[typing.Sequence[hikari.embeds.Embed]]
If provided, the message embeds.
mentions_everyone : hikari.undefined.UndefinedOr[builtins.bool]
If provided, whether the message should parse @everyone/@here
mentions.
user_mentions : hikari.undefined.UndefinedOr[typing.Union[hikari.snowflakes.SnowflakeishSequence[hikari.users.PartialUser], builtins.bool]]
If provided, and builtins.True, all mentions will be parsed.
If provided, and builtins.False, no mentions will be parsed.
Alternatively this may be a collection of
hikari.snowflakes.Snowflake, or
hikari.users.PartialUser derivatives to enforce mentioning
specific users.
role_mentions : hikari.undefined.UndefinedOr[typing.Union[hikari.snowflakes.SnowflakeishSequence[hikari.guilds.PartialRole], builtins.bool]]
If provided, and builtins.True, all mentions will be parsed.
If provided, and builtins.False, no mentions will be parsed.
Alternatively this may be a collection of
hikari.snowflakes.Snowflake, or
hikari.guilds.PartialRole derivatives to enforce mentioning
specific roles.
flags : typing.Union[hikari.undefined.UndefinedType, builtins.int, hikari.messages.MessageFlag]
The flags to set for this webhook message.

!!! warning
As of writing this can only be set for interaction webhooks
and the only settable flag is EPHEMERAL; this field is just
ignored for non-interaction webhooks.

!!! warning
As of writing, username and avatar_url are ignored for
interaction webhooks.

Returns
-------
hikari.messages.Message
The created message object.

Raises
------
hikari.errors.NotFoundError
This can be raised if the file is too large; if the embed exceeds
the defined limits; if the message content is specified only and
empty or greater than 2000 characters; if neither content, file
or embeds are specified.
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
hikari.errors.UnauthorizedError
If you pass a token that's invalid for the target webhook.
builtins.ValueError
If either ExecutableWebhook.token is builtins.None or more than 100 unique
objects/entities are passed for role_mentions or user_mentions or
if token is not available.
builtins.TypeError
If both attachment and attachments are specified.
"""  # noqa: E501 - Line too long
if not self.token:
raise ValueError("Cannot send a message using a webhook where we don't know the token")

return await self.app.rest.execute_webhook(
webhook=self.webhook_id,
token=self.token,
content=content,
avatar_url=avatar_url,
tts=tts,
attachment=attachment,
attachments=attachments,
component=component,
components=components,
embed=embed,
embeds=embeds,
mentions_everyone=mentions_everyone,
user_mentions=user_mentions,
role_mentions=role_mentions,
flags=flags,
)

async def fetch_message(self, message: snowflakes.SnowflakeishOr[messages_.Message]) -> messages_.Message:
"""Fetch an old message sent by the webhook.

Parameters
----------
message : hikari.snowflakes.SnowflakeishOr[hikari.messages.PartialMessage]
The message to fetch. This may be the object or the ID of an
existing channel.

Returns
-------
hikari.messages.Message
The requested message.

Raises
------
builtins.ValueError
If token is not available.
hikari.errors.UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
hikari.errors.NotFoundError
If the webhook is not found or the webhook's message wasn't found.
hikari.errors.RateLimitTooLongError
Raised in the event that a rate limit occurs that is
longer than max_rate_limit when making a request.
hikari.errors.RateLimitedError
Usually, Hikari will handle and retry on hitting
rate-limits automatically. This includes most bucket-specific
rate-limits and global rate-limits. In some rare edge cases,
however, Discord implements other undocumented rules for
rate-limiting, such as limits per attribute. These cannot be
detected or handled normally by Hikari due to their undocumented
nature, and will trigger this exception if they occur.
hikari.errors.InternalServerError
If an internal error occurs on Discord while handling the request.
"""
if self.token is None:
raise ValueError("Cannot fetch a message using a webhook where we don't know the token")

return await self.app.rest.fetch_webhook_message(self.webhook_id, token=self.token, message=message)

async def edit_message(
self,
message: snowflakes.SnowflakeishOr[messages_.Message],
content: undefined.UndefinedNoneOr[typing.Any] = undefined.UNDEFINED,
*,
attachment: undefined.UndefinedOr[files.Resourceish] = undefined.UNDEFINED,
attachments: undefined.UndefinedOr[typing.Sequence[files.Resourceish]] = undefined.UNDEFINED,
component: undefined.UndefinedNoneOr[special_endpoints.ComponentBuilder] = undefined.UNDEFINED,
components: undefined.UndefinedNoneOr[
typing.Sequence[special_endpoints.ComponentBuilder]
] = undefined.UNDEFINED,
embed: undefined.UndefinedNoneOr[embeds_.Embed] = undefined.UNDEFINED,
embeds: undefined.UndefinedNoneOr[typing.Sequence[embeds_.Embed]] = undefined.UNDEFINED,
replace_attachments: bool = False,
mentions_everyone: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
user_mentions: undefined.UndefinedOr[
typing.Union[snowflakes.SnowflakeishSequence[users_.PartialUser], bool]
] = undefined.UNDEFINED,
role_mentions: undefined.UndefinedOr[
typing.Union[snowflakes.SnowflakeishSequence[guilds_.PartialRole], bool]
] = undefined.UNDEFINED,
) -> messages_.Message:
"""Edit a message sent by a webhook.

Parameters
----------
message : hikari.snowflakes.SnowflakeishOr[hikari.messages.PartialMessage]
The message to delete. This may be the object or the ID of
an existing message.
content : hikari.undefined.UndefinedNoneOr[typing.Any]
If provided, the message contents. If
hikari.undefined.UNDEFINED, then nothing will be sent
in the content. Any other value here will be cast to a
builtins.str.

If this is a hikari.embeds.Embed and no embed nor
no embeds kwarg is provided, then this will instead
update the embed. This allows for simpler syntax when
sending an embed alone.

Likewise, if this is a hikari.files.Resource, then the
content is instead treated as an attachment if no attachment and
no attachments kwargs are provided.

Other Parameters
----------------
attachment : hikari.undefined.UndefinedOr[hikari.files.Resourceish]
If provided, the attachment to set on the message. If
hikari.undefined.UNDEFINED, the previous attachment, if
present, is not changed. If this is builtins.None, then the
attachment is removed, if present. Otherwise, the new attachment
that was provided will be attached.
attachments : hikari.undefined.UndefinedOr[typing.Sequence[hikari.files.Resourceish]]
If provided, the attachments to set on the message. If
hikari.undefined.UNDEFINED, the previous attachments, if
present, are not changed. If this is builtins.None, then the
attachments is removed, if present. Otherwise, the new attachments
that were provided will be attached.
component : hikari.undefined.UndefinedNoneOr[hikari.api.special_endpoints.ComponentBuilder]
If provided, builder object of the component to set for this message.
This component will replace any previously set components and passing
builtins.None will remove all components.
components : hikari.undefined.UndefinedNoneOr[typing.Sequence[hikari.api.special_endpoints.ComponentBuilder]]
If provided, a sequence of the component builder objects set for
this message. These components will replace any previously set
components and passing builtins.None or an empty sequence will
remove all components.
embed : hikari.undefined.UndefinedNoneOr[hikari.embeds.Embed]
If provided, the embed to set on the message. If
hikari.undefined.UNDEFINED, the previous embed(s) are not changed.
If this is builtins.None then any present embeds are removed.
Otherwise, the new embed that was provided will be used as the
replacement.
embeds : hikari.undefined.UndefinedNoneOr[typing.Sequence[hikari.embeds.Embed]]
If provided, the embeds to set on the message. If
hikari.undefined.UNDEFINED, the previous embed(s) are not changed.
If this is builtins.None then any present embeds are removed.
Otherwise, the new embeds that were provided will be used as the
replacement.
replace_attachments: bool
Whether to replace the attachments with the provided ones. Defaults
to builtins.False.

Note this will also overwrite the embed attachments.
mentions_everyone : hikari.undefined.UndefinedOr[builtins.bool]
If provided, sanitation for @everyone mentions. If
hikari.undefined.UNDEFINED, then the previous setting is
not changed. If builtins.True, then @everyone/@here mentions
in the message content will show up as mentioning everyone that can
view the chat.
user_mentions : hikari.undefined.UndefinedOr[typing.Union[hikari.snowflakes.SnowflakeishSequence[hikari.users.PartialUser], builtins.bool]]
If provided, and builtins.True, all user mentions will be detected.
If provided, and builtins.False, all user mentions will be ignored
if appearing in the message body.
Alternatively this may be a collection of
hikari.snowflakes.Snowflake, or
hikari.users.PartialUser derivatives to enforce mentioning
specific users.
role_mentions : hikari.undefined.UndefinedOr[typing.Union[hikari.snowflakes.SnowflakeishSequence[hikari.guilds.PartialRole], builtins.bool]]
If provided, and builtins.True, all role mentions will be detected.
If provided, and builtins.False, all role mentions will be ignored
if appearing in the message body.
Alternatively this may be a collection of
hikari.snowflakes.Snowflake, or
hikari.guilds.PartialRole derivatives to enforce mentioning
specific roles.

!!! note
Mentioning everyone, roles, or users in message edits currently
will not send a push notification showing a new mention to people
on Discord. It will still highlight in their chat as if they
were mentioned, however.

!!! warning
If you specify a non-embed content, mentions_everyone,
mentions_reply, user_mentions, and role_mentions will default
to builtins.False as the message will be re-parsed for mentions.

This is a limitation of Discord's design. If in doubt, specify all
three of them each time.

!!! warning
If you specify one of mentions_everyone, mentions_reply,
user_mentions, or role_mentions, then all others will default to
builtins.False, even if they were enabled previously.

This is a limitation of Discord's design. If in doubt, specify all
three of them each time.

Returns
-------
hikari.messages.Message
The edited message.

Raises
------
builtins.ValueError
If more than 100 unique objects/entities are passed for
role_mentions or user_mentions or token is not available.
builtins.TypeError
If both attachment and attachments are specified or if both
embed and embeds are specified.
This may be raised in several discrete situations, such as messages
being empty with no attachments or embeds; messages with more than
2000 characters in them, embeds that exceed one of the many embed
limits; too many attachments; attachments that are too large;
too many components.
hikari.errors.UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
hikari.errors.NotFoundError
hikari.errors.RateLimitTooLongError
Raised in the event that a rate limit occurs that is
longer than max_rate_limit when making a request.
hikari.errors.RateLimitedError
Usually, Hikari will handle and retry on hitting
rate-limits automatically. This includes most bucket-specific
rate-limits and global rate-limits. In some rare edge cases,
however, Discord implements other undocumented rules for
rate-limiting, such as limits per attribute. These cannot be
detected or handled normally by Hikari due to their undocumented
nature, and will trigger this exception if they occur.
hikari.errors.InternalServerError
If an internal error occurs on Discord while handling the request.
"""  # noqa: E501 - Line too long
if self.token is None:
raise ValueError("Cannot edit a message using a webhook where we don't know the token")

return await self.app.rest.edit_webhook_message(
self.webhook_id,
token=self.token,
message=message,
content=content,
attachment=attachment,
attachments=attachments,
component=component,
components=components,
embed=embed,
embeds=embeds,
replace_attachments=replace_attachments,
mentions_everyone=mentions_everyone,
user_mentions=user_mentions,
role_mentions=role_mentions,
)

async def delete_message(self, message: snowflakes.SnowflakeishOr[messages_.Message]) -> None:
"""Delete a given message in a given channel.

Parameters
----------
message : hikari.snowflakes.SnowflakeishOr[hikari.messages.PartialMessage]
The message to delete. This may be the object or the ID of
an existing message.

Raises
------
builtins.ValueError
If token is not available.
hikari.errors.UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
hikari.errors.NotFoundError
hikari.errors.RateLimitTooLongError
Raised in the event that a rate limit occurs that is
longer than max_rate_limit when making a request.
hikari.errors.RateLimitedError
Usually, Hikari will handle and retry on hitting
rate-limits automatically. This includes most bucket-specific
rate-limits and global rate-limits. In some rare edge cases,
however, Discord implements other undocumented rules for
rate-limiting, such as limits per attribute. These cannot be
detected or handled normally by Hikari due to their undocumented
nature, and will trigger this exception if they occur.
hikari.errors.InternalServerError
If an internal error occurs on Discord while handling the request.
"""
if self.token is None:
raise ValueError("Cannot delete a message using a webhook where we don't know the token")

await self.app.rest.delete_webhook_message(self.webhook_id, token=self.token, message=message)

@attr_extensions.with_copy
@attr.define(hash=True, kw_only=True, weakref_slot=False)
class PartialWebhook(snowflakes.Unique):
"""Base class for all webhook implementations."""

app: traits.RESTAware = attr.field(
)
"""The client application that models may use for procedures."""

id: snowflakes.Snowflake = attr.field(hash=True, repr=True)
"""The ID of this entity."""

type: typing.Union[WebhookType, int] = attr.field(eq=False, hash=False, repr=True)
"""The type of the webhook."""

name: str = attr.field(eq=False, hash=False, repr=True)
"""The name of the webhook."""

avatar_hash: typing.Optional[str] = attr.field(eq=False, hash=False, repr=False)
"""The avatar hash of the webhook."""

application_id: typing.Optional[snowflakes.Snowflake] = attr.field(eq=False, hash=False, repr=False)
"""The ID of the application that created this webhook."""

def __str__(self) -> str:
return self.name if self.name is not None else f"Unnamed webhook ID {self.id}"

@property
def mention(self) -> str:
"""Return a raw mention string for the given webhook's user.

!!! note
This exists purely for consistency. Webhooks do not receive events
from the gateway, and without some bot backend to support it, will
not be able to detect mentions of their webhook.

Example
-------

py
>>> some_webhook.mention
'<@123456789123456789>'


Returns
-------
builtins.str
The mention string to use.
"""
return f"<@{self.id}>"

@property
def avatar_url(self) -> typing.Optional[files_.URL]:
"""URL for this webhook's avatar, if set.

May be builtins.None if no avatar is set. In this case, you should use
default_avatar_url instead.
"""
return self.make_avatar_url()

@property
def default_avatar_url(self) -> files_.URL:
"""Avatar URL for the user, if they have one set.

May be builtins.None if no custom avatar is set. In this case, you
should use default_avatar_url instead.
"""
return routes.CDN_DEFAULT_USER_AVATAR.compile_to_file(
urls.CDN_URL,
discriminator=0,
file_format="png",
)

def make_avatar_url(self, ext: str = "png", size: int = 4096) -> typing.Optional[files_.URL]:
"""Generate the avatar URL for this webhook's custom avatar if set.

If no avatar is specified, return None. In this case, you should
use default_avatar instead.

Parameters
----------
ext : builtins.str
The extension to use for this URL, defaults to png.
Supports png, jpeg, jpg and webp.
size : builtins.int
The size to set for the URL, defaults to 4096.
Can be any power of two between 16 and 4096.
Will be ignored for default avatars.

Returns
-------
typing.Optional[hikari.files.URL]
The URL of the resource. builtins.None if no avatar is set (in
this case, use the default_avatar instead).

Raises
------
builtins.ValueError
If size is not a power of two between 16 and 4096 (inclusive).
"""
if self.avatar_hash is None:
return None

return routes.CDN_USER_AVATAR.compile_to_file(
urls.CDN_URL,
user_id=self.id,
hash=self.avatar_hash,
size=size,
file_format=ext,
)

@attr.define(hash=True, kw_only=True, weakref_slot=False)
class IncomingWebhook(PartialWebhook, ExecutableWebhook):
"""Represents an incoming webhook object on Discord.

This is an endpoint that can have messages sent to it using standard
HTTP requests, which enables external services that are not bots to
send informational messages to specific channels.
"""

channel_id: snowflakes.Snowflake = attr.field(eq=False, hash=False, repr=True)
"""The channel ID this webhook is for."""

guild_id: snowflakes.Snowflake = attr.field(eq=False, hash=False, repr=True)
"""The guild ID of the webhook."""

author: typing.Optional[users_.User] = attr.field(eq=False, hash=False, repr=True)
"""The user that created the webhook

!!! info
This will be builtins.None when fetched with the webhook's token
rather than bot authorization or when received within audit logs.
"""

token: typing.Optional[str] = attr.field(eq=False, hash=False, repr=False)
"""The token for the webhook.

!!! info
This is only available for incoming webhooks that are created in the
channel settings.
"""

@property
def webhook_id(self) -> snowflakes.Snowflake:
# <<inherited docstring from ExecutableWebhook>>.
return self.id

async def delete(self, *, use_token: undefined.UndefinedOr[bool] = undefined.UNDEFINED) -> None:
"""Delete this webhook.

Other Parameters
----------------
use_token : hikari.undefined.UndefinedOr[builtins.bool]
If set to builtins.True then the webhook's token will be used for
this request; if set to builtins.False then bot authorization will
be used; if not specified then the webhook's token will be used for
the request if it's set else bot authorization.

Raises
------
hikari.errors.NotFoundError
hikari.errors.ForbiddenError
If you either lack the MANAGE_WEBHOOKS permission or
are not a member of the guild this webhook belongs to.
builtins.ValueError
If use_token is passed as builtins.True when IncomingWebhook.token is
builtins.None.
"""
token: undefined.UndefinedOr[str] = undefined.UNDEFINED
if use_token:
if self.token is None:
raise ValueError("This webhook's token is unknown, so cannot be used")
token = self.token

elif use_token is undefined.UNDEFINED and self.token:
token = self.token

await self.app.rest.delete_webhook(self.id, token=token)

async def edit(
self,
*,
name: undefined.UndefinedOr[str] = undefined.UNDEFINED,
channel: undefined.UndefinedOr[snowflakes.SnowflakeishOr[channels_.WebhookChannelT]] = undefined.UNDEFINED,
reason: undefined.UndefinedOr[str] = undefined.UNDEFINED,
use_token: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
) -> IncomingWebhook:
"""Edit this webhook.

Other Parameters
----------------
name : hikari.undefined.UndefinedOr[builtins.str]
If provided, the new name string.
avatar : hikari.undefined.UndefinedOr[hikari.files.Resourceish]
If provided, the new avatar image. If builtins.None, then
it is removed. If not specified, nothing is changed.
channel : hikari.undefined.UndefinedOr[hikari.snowflakes.SnowflakeishOr[hikari.channels.WebhookChannelT]]
If provided, the object or ID of the new channel the given
webhook should be moved to.
reason : hikari.undefined.UndefinedOr[builtins.str]
If provided, the audit log reason explaining why the operation
was performed. This field will be used when using the webhook's
token rather than bot authorization.
use_token : hikari.undefined.UndefinedOr[builtins.bool]
If set to builtins.True then the webhook's token will be used for
this request; if set to builtins.False then bot authorization will
be used; if not specified then the webhook's token will be used for
the request if it's set else bot authorization.

Returns
-------
IncomingWebhook
The updated webhook object.

Raises
------
builtins.ValueError
If use_token is passed as builtins.True when IncomingWebhook.token is builtins.None.
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
hikari.errors.NotFoundError
hikari.errors.ForbiddenError
If you either lack the MANAGE_WEBHOOKS permission or
are not a member of the guild this webhook belongs to.
hikari.errors.UnauthorizedError
If you pass a token that's invalid for the target webhook.
hikari.errors.RateLimitTooLongError
Raised in the event that a rate limit occurs that is
longer than max_rate_limit when making a request.
hikari.errors.RateLimitedError
Usually, Hikari will handle and retry on hitting
rate-limits automatically. This includes most bucket-specific
rate-limits and global rate-limits. In some rare edge cases,
however, Discord implements other undocumented rules for
rate-limiting, such as limits per attribute. These cannot be
detected or handled normally by Hikari due to their undocumented
nature, and will trigger this exception if they occur.
hikari.errors.InternalServerError
If an internal error occurs on Discord while handling the request.
"""  # noqa: E501 - Line too long
token: undefined.UndefinedOr[str] = undefined.UNDEFINED
if use_token:
if self.token is None:
raise ValueError("This webhook's token is unknown, so cannot be used")
token = self.token

elif use_token is undefined.UNDEFINED and self.token:
token = self.token

webhook = await self.app.rest.edit_webhook(
self.id,
token=token,
name=name,
avatar=avatar,
channel=channel,
reason=reason,
)
assert isinstance(webhook, IncomingWebhook)
return webhook

async def fetch_channel(self) -> channels_.WebhookChannelT:
"""Fetch the channel this webhook is for.

Returns
-------
hikari.channels.WebhookChannelT
The object of the channel this webhook targets.

Raises
------
hikari.errors.ForbiddenError
If you don't have access to the channel this webhook belongs to.
hikari.errors.NotFoundError
If the channel this message was created in does not exist.
hikari.errors.UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
hikari.errors.RateLimitTooLongError
Raised in the event that a rate limit occurs that is
longer than max_rate_limit when making a request.
hikari.errors.RateLimitedError
Usually, Hikari will handle and retry on hitting
rate-limits automatically. This includes most bucket-specific
rate-limits and global rate-limits. In some rare edge cases,
however, Discord implements other undocumented rules for
rate-limiting, such as limits per attribute. These cannot be
detected or handled normally by Hikari due to their undocumented
nature, and will trigger this exception if they occur.
hikari.errors.InternalServerError
If an internal error occurs on Discord while handling the request.
"""
channel = await self.app.rest.fetch_channel(self.channel_id)
assert isinstance(channel, channels_.WebhookChannelTypes)
return channel

async def fetch_self(self, *, use_token: undefined.UndefinedOr[bool] = undefined.UNDEFINED) -> IncomingWebhook:
"""Fetch this webhook.

Other Parameters
----------------
use_token : hikari.undefined.UndefinedOr[builtins.bool]
If set to builtins.True then the webhook's token will be used for
this request; if set to builtins.False then bot authorization will
be used; if not specified then the webhook's token will be used for
the request if it's set else bot authorization.

Returns
-------
IncomingWebhook
The requested webhook object.

Raises
------
builtins.ValueError
If use_token is passed as builtins.True when Webhook.token
is builtins.None.
hikari.errors.ForbiddenError
If you're not in the guild that owns this webhook or
lack the MANAGE_WEBHOOKS permission.
hikari.errors.NotFoundError
hikari.errors.UnauthorizedError
If you pass a token that's invalid for the target webhook.
hikari.errors.RateLimitTooLongError
Raised in the event that a rate limit occurs that is
longer than max_rate_limit when making a request.
hikari.errors.RateLimitedError
Usually, Hikari will handle and retry on hitting
rate-limits automatically. This includes most bucket-specific
rate-limits and global rate-limits. In some rare edge cases,
however, Discord implements other undocumented rules for
rate-limiting, such as limits per attribute. These cannot be
detected or handled normally by Hikari due to their undocumented
nature, and will trigger this exception if they occur.
hikari.errors.InternalServerError
If an internal error occurs on Discord while handling the request.
"""
token: undefined.UndefinedOr[str] = undefined.UNDEFINED
if use_token:
if self.token is None:
raise ValueError("This webhook's token is unknown, so cannot be used")
token = self.token

elif use_token is undefined.UNDEFINED and self.token:
token = self.token

webhook = await self.app.rest.fetch_webhook(self.id, token=token)
assert isinstance(webhook, IncomingWebhook)
return webhook

@attr.define(hash=True, kw_only=True, weakref_slot=False)
class ChannelFollowerWebhook(PartialWebhook):
"""Represents a channel follower webhook object on Discord."""

channel_id: snowflakes.Snowflake = attr.field(eq=False, hash=False, repr=True)
"""The channel ID this webhook is for."""

guild_id: snowflakes.Snowflake = attr.field(eq=False, hash=False, repr=True)
"""The guild ID of the webhook."""

author: typing.Optional[users_.User] = attr.field(eq=False, hash=False, repr=True)
"""The user that created the webhook

!!! info
This will be builtins.None when received within an audit log.
"""

source_channel: channels_.PartialChannel = attr.field(eq=False, hash=False, repr=True)
"""The partial object of the channel this webhook is following."""

source_guild: guilds_.PartialGuild = attr.field(eq=False, hash=False, repr=True)
"""The partial object of the guild this webhook is following."""

async def delete(self) -> None:
"""Delete this webhook.

Raises
------
hikari.errors.NotFoundError
hikari.errors.ForbiddenError
If you either lack the MANAGE_WEBHOOKS permission or
are not a member of the guild this webhook belongs to.
"""
await self.app.rest.delete_webhook(self.id)

async def edit(
self,
*,
name: undefined.UndefinedOr[str] = undefined.UNDEFINED,
channel: undefined.UndefinedOr[snowflakes.SnowflakeishOr[channels_.WebhookChannelT]] = undefined.UNDEFINED,
reason: undefined.UndefinedOr[str] = undefined.UNDEFINED,
) -> ChannelFollowerWebhook:
"""Edit this webhook.

Other Parameters
----------------
name : hikari.undefined.UndefinedOr[builtins.str]
If provided, the new name string.
avatar : hikari.undefined.UndefinedOr[hikari.files.Resourceish]
If provided, the new avatar image. If builtins.None, then
it is removed. If not specified, nothing is changed.
channel : hikari.undefined.UndefinedOr[hikari.snowflakes.SnowflakeishOr[hikari.channels.WebhookChannelT]]
If provided, the object or ID of the new channel the given
webhook should be moved to.
reason : hikari.undefined.UndefinedOr[builtins.str]
If provided, the audit log reason explaining why the operation
was performed. This field will be used when using the webhook's
token rather than bot authorization.

Returns
-------
hikari.webhooks.ChannelFollowerWebhook
The updated webhook object.

Raises
------
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
hikari.errors.NotFoundError
hikari.errors.ForbiddenError
If you either lack the MANAGE_WEBHOOKS permission or
are not a member of the guild this webhook belongs to.
hikari.errors.UnauthorizedError
If you pass a token that's invalid for the target webhook.
hikari.errors.RateLimitTooLongError
Raised in the event that a rate limit occurs that is
longer than max_rate_limit when making a request.
hikari.errors.RateLimitedError
Usually, Hikari will handle and retry on hitting
rate-limits automatically. This includes most bucket-specific
rate-limits and global rate-limits. In some rare edge cases,
however, Discord implements other undocumented rules for
rate-limiting, such as limits per attribute. These cannot be
detected or handled normally by Hikari due to their undocumented
nature, and will trigger this exception if they occur.
hikari.errors.InternalServerError
If an internal error occurs on Discord while handling the request.
"""  # noqa: E501 - Line too long
webhook = await self.app.rest.edit_webhook(
self.id,
name=name,
avatar=avatar,
channel=channel,
reason=reason,
)
assert isinstance(webhook, ChannelFollowerWebhook)
return webhook

async def fetch_channel(self) -> channels_.WebhookChannelT:
"""Fetch the channel this webhook is for.

Returns
-------
hikari.channels.WebhookChannelT
The object of the channel this webhook targets.

Raises
------
hikari.errors.ForbiddenError
If you don't have access to the channel this webhook belongs to.
hikari.errors.NotFoundError
If the channel this message was created in does not exist.
hikari.errors.UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
hikari.errors.RateLimitTooLongError
Raised in the event that a rate limit occurs that is
longer than max_rate_limit when making a request.
hikari.errors.RateLimitedError
Usually, Hikari will handle and retry on hitting
rate-limits automatically. This includes most bucket-specific
rate-limits and global rate-limits. In some rare edge cases,
however, Discord implements other undocumented rules for
rate-limiting, such as limits per attribute. These cannot be
detected or handled normally by Hikari due to their undocumented
nature, and will trigger this exception if they occur.
hikari.errors.InternalServerError
If an internal error occurs on Discord while handling the request.
"""
channel = await self.app.rest.fetch_channel(self.channel_id)
assert isinstance(channel, channels_.WebhookChannelTypes)
return channel

async def fetch_self(self) -> ChannelFollowerWebhook:
"""Fetch this webhook.

Returns
-------
hikari.webhooks.ChannelFollowerWebhook
The requested webhook object.

Raises
------
hikari.errors.ForbiddenError
If you're not in the guild that owns this webhook or
lack the MANAGE_WEBHOOKS permission.
hikari.errors.NotFoundError
hikari.errors.UnauthorizedError
If you pass a token that's invalid for the target webhook.
hikari.errors.RateLimitTooLongError
Raised in the event that a rate limit occurs that is
longer than max_rate_limit when making a request.
hikari.errors.RateLimitedError
Usually, Hikari will handle and retry on hitting
rate-limits automatically. This includes most bucket-specific
rate-limits and global rate-limits. In some rare edge cases,
however, Discord implements other undocumented rules for
rate-limiting, such as limits per attribute. These cannot be
detected or handled normally by Hikari due to their undocumented
nature, and will trigger this exception if they occur.
hikari.errors.InternalServerError
If an internal error occurs on Discord while handling the request.
"""
webhook = await self.app.rest.fetch_webhook(self.id)
assert isinstance(webhook, ChannelFollowerWebhook)
return webhook

@attr.define(hash=True, kw_only=True, weakref_slot=False)
class ApplicationWebhook(PartialWebhook):
"""Represents an application webhook object on Discord.

This is from the interactions flow.
"""

application_id: snowflakes.Snowflake = attr.ib()
# <<inherited docstring from PartialWebhook>>.

## Classes

#### dataclassApplicationWebhook

class ApplicationWebhook (
*,
app: traits.RESTAware,
id: snowflakes.Snowflake,
type: Union[WebhookType, int],
name: str,
avatar_hash: Optional[str],
application_id: snowflakes.Snowflake,
): ...

Represents an application webhook object on Discord.

This is from the interactions flow.

Method generated by attrs for class ApplicationWebhook.

Expand source code
Browse git
class ApplicationWebhook(PartialWebhook):
"""Represents an application webhook object on Discord.

This is from the interactions flow.
"""

application_id: snowflakes.Snowflake = attr.ib()
# <<inherited docstring from PartialWebhook>>.
##### Method resolution order
dataclass ApplicationWebhook
That's this class!
dataclass PartialWebhook

Base class for all webhook implementations …

abstract class Unique

Mixin for a class that enforces uniqueness by a snowflake ID.

extern class abc.ABC

Helper class that provides a standard way to create an ABC using inheritance.

##### Variables and properties
property app : traits.RESTAware

The client application that models may use for procedures.

property application_id : snowflakes.Snowflake

Return an attribute of instance, which is of type owner.

property avatar_hash : Optional[str]

The avatar hash of the webhook.

property avatar_url : Optional[files_.URL]

URL for this webhook's avatar, if set.

May be None if no avatar is set. In this case, you should use default_avatar_url instead.

property created_at : datetime.datetime

When the object was created.

property default_avatar_url : files_.URL

Avatar URL for the user, if they have one set.

May be None if no custom avatar is set. In this case, you should use default_avatar_url instead.

property id : snowflakes.Snowflake

The ID of this entity.

property mention : str

Return a raw mention string for the given webhook's user.

Note

This exists purely for consistency. Webhooks do not receive events from the gateway, and without some bot backend to support it, will not be able to detect mentions of their webhook.

## Example

>>> some_webhook.mention
'<@123456789123456789>'


## Returns

str
The mention string to use.
property name : str

The name of the webhook.

property type : Union[WebhookType, int]

The type of the webhook.

##### Methods
def make_avatar_url(
ext: str = 'png',
size: int = 4096,
) -> Optional[files_.URL]: ...

Inherited from: PartialWebhook.make_avatar_url

Generate the avatar URL for this webhook's custom avatar if set.

If no avatar is specified, return None. In this case, you should use default_avatar instead.

## Parameters

ext : str
The extension to use for this URL, defaults to png. Supports png, jpeg, jpg and webp.
size : int
The size to set for the URL, defaults to 4096. Can be any power of two between 16 and 4096. Will be ignored for default avatars.

## Returns

Optional[URL]
The URL of the resource. None if no avatar is set (in this case, use the default_avatar instead).

## Raises

ValueError
If size is not a power of two between 16 and 4096 (inclusive).

#### dataclassChannelFollowerWebhook

class ChannelFollowerWebhook (
*,
app: traits.RESTAware,
id: snowflakes.Snowflake,
type: Union[WebhookType, int],
name: str,
avatar_hash: Optional[str],
application_id: Optional[snowflakes.Snowflake],
channel_id: snowflakes.Snowflake,
guild_id: snowflakes.Snowflake,
author: Optional[users_.User],
source_channel: channels_.PartialChannel,
source_guild: guilds_.PartialGuild,
): ...

Represents a channel follower webhook object on Discord.

Method generated by attrs for class ChannelFollowerWebhook.

Expand source code
Browse git
class ChannelFollowerWebhook(PartialWebhook):
"""Represents a channel follower webhook object on Discord."""

channel_id: snowflakes.Snowflake = attr.field(eq=False, hash=False, repr=True)
"""The channel ID this webhook is for."""

guild_id: snowflakes.Snowflake = attr.field(eq=False, hash=False, repr=True)
"""The guild ID of the webhook."""

author: typing.Optional[users_.User] = attr.field(eq=False, hash=False, repr=True)
"""The user that created the webhook

!!! info
This will be builtins.None when received within an audit log.
"""

source_channel: channels_.PartialChannel = attr.field(eq=False, hash=False, repr=True)
"""The partial object of the channel this webhook is following."""

source_guild: guilds_.PartialGuild = attr.field(eq=False, hash=False, repr=True)
"""The partial object of the guild this webhook is following."""

async def delete(self) -> None:
"""Delete this webhook.

Raises
------
hikari.errors.NotFoundError
hikari.errors.ForbiddenError
If you either lack the MANAGE_WEBHOOKS permission or
are not a member of the guild this webhook belongs to.
"""
await self.app.rest.delete_webhook(self.id)

async def edit(
self,
*,
name: undefined.UndefinedOr[str] = undefined.UNDEFINED,
channel: undefined.UndefinedOr[snowflakes.SnowflakeishOr[channels_.WebhookChannelT]] = undefined.UNDEFINED,
reason: undefined.UndefinedOr[str] = undefined.UNDEFINED,
) -> ChannelFollowerWebhook:
"""Edit this webhook.

Other Parameters
----------------
name : hikari.undefined.UndefinedOr[builtins.str]
If provided, the new name string.
avatar : hikari.undefined.UndefinedOr[hikari.files.Resourceish]
If provided, the new avatar image. If builtins.None, then
it is removed. If not specified, nothing is changed.
channel : hikari.undefined.UndefinedOr[hikari.snowflakes.SnowflakeishOr[hikari.channels.WebhookChannelT]]
If provided, the object or ID of the new channel the given
webhook should be moved to.
reason : hikari.undefined.UndefinedOr[builtins.str]
If provided, the audit log reason explaining why the operation
was performed. This field will be used when using the webhook's
token rather than bot authorization.

Returns
-------
hikari.webhooks.ChannelFollowerWebhook
The updated webhook object.

Raises
------
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
hikari.errors.NotFoundError
hikari.errors.ForbiddenError
If you either lack the MANAGE_WEBHOOKS permission or
are not a member of the guild this webhook belongs to.
hikari.errors.UnauthorizedError
If you pass a token that's invalid for the target webhook.
hikari.errors.RateLimitTooLongError
Raised in the event that a rate limit occurs that is
longer than max_rate_limit when making a request.
hikari.errors.RateLimitedError
Usually, Hikari will handle and retry on hitting
rate-limits automatically. This includes most bucket-specific
rate-limits and global rate-limits. In some rare edge cases,
however, Discord implements other undocumented rules for
rate-limiting, such as limits per attribute. These cannot be
detected or handled normally by Hikari due to their undocumented
nature, and will trigger this exception if they occur.
hikari.errors.InternalServerError
If an internal error occurs on Discord while handling the request.
"""  # noqa: E501 - Line too long
webhook = await self.app.rest.edit_webhook(
self.id,
name=name,
avatar=avatar,
channel=channel,
reason=reason,
)
assert isinstance(webhook, ChannelFollowerWebhook)
return webhook

async def fetch_channel(self) -> channels_.WebhookChannelT:
"""Fetch the channel this webhook is for.

Returns
-------
hikari.channels.WebhookChannelT
The object of the channel this webhook targets.

Raises
------
hikari.errors.ForbiddenError
If you don't have access to the channel this webhook belongs to.
hikari.errors.NotFoundError
If the channel this message was created in does not exist.
hikari.errors.UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
hikari.errors.RateLimitTooLongError
Raised in the event that a rate limit occurs that is
longer than max_rate_limit when making a request.
hikari.errors.RateLimitedError
Usually, Hikari will handle and retry on hitting
rate-limits automatically. This includes most bucket-specific
rate-limits and global rate-limits. In some rare edge cases,
however, Discord implements other undocumented rules for
rate-limiting, such as limits per attribute. These cannot be
detected or handled normally by Hikari due to their undocumented
nature, and will trigger this exception if they occur.
hikari.errors.InternalServerError
If an internal error occurs on Discord while handling the request.
"""
channel = await self.app.rest.fetch_channel(self.channel_id)
assert isinstance(channel, channels_.WebhookChannelTypes)
return channel

async def fetch_self(self) -> ChannelFollowerWebhook:
"""Fetch this webhook.

Returns
-------
hikari.webhooks.ChannelFollowerWebhook
The requested webhook object.

Raises
------
hikari.errors.ForbiddenError
If you're not in the guild that owns this webhook or
lack the MANAGE_WEBHOOKS permission.
hikari.errors.NotFoundError
hikari.errors.UnauthorizedError
If you pass a token that's invalid for the target webhook.
hikari.errors.RateLimitTooLongError
Raised in the event that a rate limit occurs that is
longer than max_rate_limit when making a request.
hikari.errors.RateLimitedError
Usually, Hikari will handle and retry on hitting
rate-limits automatically. This includes most bucket-specific
rate-limits and global rate-limits. In some rare edge cases,
however, Discord implements other undocumented rules for
rate-limiting, such as limits per attribute. These cannot be
detected or handled normally by Hikari due to their undocumented
nature, and will trigger this exception if they occur.
hikari.errors.InternalServerError
If an internal error occurs on Discord while handling the request.
"""
webhook = await self.app.rest.fetch_webhook(self.id)
assert isinstance(webhook, ChannelFollowerWebhook)
return webhook
##### Method resolution order
dataclass ChannelFollowerWebhook
That's this class!
dataclass PartialWebhook

Base class for all webhook implementations …

abstract class Unique

Mixin for a class that enforces uniqueness by a snowflake ID.

extern class abc.ABC

Helper class that provides a standard way to create an ABC using inheritance.

##### Variables and properties
property app : traits.RESTAware

The client application that models may use for procedures.

property application_id : Optional[snowflakes.Snowflake]

The ID of the application that created this webhook.

property author : Optional[users_.User]

The user that created the webhook

Info

This will be None when received within an audit log.

property avatar_hash : Optional[str]

The avatar hash of the webhook.

property avatar_url : Optional[files_.URL]

URL for this webhook's avatar, if set.

May be None if no avatar is set. In this case, you should use default_avatar_url instead.

property channel_id : snowflakes.Snowflake

The channel ID this webhook is for.

property created_at : datetime.datetime

When the object was created.

property default_avatar_url : files_.URL

Avatar URL for the user, if they have one set.

May be None if no custom avatar is set. In this case, you should use default_avatar_url instead.

property guild_id : snowflakes.Snowflake

The guild ID of the webhook.

property id : snowflakes.Snowflake

The ID of this entity.

property mention : str

Return a raw mention string for the given webhook's user.

Note

This exists purely for consistency. Webhooks do not receive events from the gateway, and without some bot backend to support it, will not be able to detect mentions of their webhook.

## Example

>>> some_webhook.mention
'<@123456789123456789>'


## Returns

str
The mention string to use.
property name : str

The name of the webhook.

property source_channel : channels_.PartialChannel

The partial object of the channel this webhook is following.

property source_guild : guilds_.PartialGuild

The partial object of the guild this webhook is following.

property type : Union[WebhookType, int]

The type of the webhook.

##### Methods
async def delete() -> None: ...

Delete this webhook.

## Raises

NotFoundError
ForbiddenError
If you either lack the MANAGE_WEBHOOKS permission or are not a member of the guild this webhook belongs to.
Expand source code
Browse git
async def delete(self) -> None:
"""Delete this webhook.

Raises
------
hikari.errors.NotFoundError
hikari.errors.ForbiddenError
If you either lack the MANAGE_WEBHOOKS permission or
are not a member of the guild this webhook belongs to.
"""
await self.app.rest.delete_webhook(self.id)
async def edit(
*,
name: undefined.UndefinedOr[str] = UNDEFINED,
channel: undefined.UndefinedOr[snowflakes.SnowflakeishOr[channels_.WebhookChannelT]] = UNDEFINED,
reason: undefined.UndefinedOr[str] = UNDEFINED,
) -> ChannelFollowerWebhook: ...

Edit this webhook.

## Other Parameters

name : UndefinedOr[str]
If provided, the new name string.
avatar : UndefinedOr[Resourceish]
If provided, the new avatar image. If None, then it is removed. If not specified, nothing is changed.
channel : UndefinedOr[SnowflakeishOr[WebhookChannelT]]
If provided, the object or ID of the new channel the given webhook should be moved to.
reason : UndefinedOr[str]
If provided, the audit log reason explaining why the operation was performed. This field will be used when using the webhook's token rather than bot authorization.

## Returns

ChannelFollowerWebhook
The updated webhook object.

## Raises

BadRequestError
If any invalid snowflake IDs are passed; a snowflake may be invalid due to it being outside of the range of a 64 bit integer.
NotFoundError
ForbiddenError
If you either lack the MANAGE_WEBHOOKS permission or are not a member of the guild this webhook belongs to.
UnauthorizedError
If you pass a token that's invalid for the target webhook.
RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
RateLimitedError
Usually, Hikari will handle and retry on hitting rate-limits automatically. This includes most bucket-specific rate-limits and global rate-limits. In some rare edge cases, however, Discord implements other undocumented rules for rate-limiting, such as limits per attribute. These cannot be detected or handled normally by Hikari due to their undocumented nature, and will trigger this exception if they occur.
InternalServerError
If an internal error occurs on Discord while handling the request.
Expand source code
Browse git
async def edit(
self,
*,
name: undefined.UndefinedOr[str] = undefined.UNDEFINED,
channel: undefined.UndefinedOr[snowflakes.SnowflakeishOr[channels_.WebhookChannelT]] = undefined.UNDEFINED,
reason: undefined.UndefinedOr[str] = undefined.UNDEFINED,
) -> ChannelFollowerWebhook:
"""Edit this webhook.

Other Parameters
----------------
name : hikari.undefined.UndefinedOr[builtins.str]
If provided, the new name string.
avatar : hikari.undefined.UndefinedOr[hikari.files.Resourceish]
If provided, the new avatar image. If builtins.None, then
it is removed. If not specified, nothing is changed.
channel : hikari.undefined.UndefinedOr[hikari.snowflakes.SnowflakeishOr[hikari.channels.WebhookChannelT]]
If provided, the object or ID of the new channel the given
webhook should be moved to.
reason : hikari.undefined.UndefinedOr[builtins.str]
If provided, the audit log reason explaining why the operation
was performed. This field will be used when using the webhook's
token rather than bot authorization.

Returns
-------
hikari.webhooks.ChannelFollowerWebhook
The updated webhook object.

Raises
------
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
hikari.errors.NotFoundError
hikari.errors.ForbiddenError
If you either lack the MANAGE_WEBHOOKS permission or
are not a member of the guild this webhook belongs to.
hikari.errors.UnauthorizedError
If you pass a token that's invalid for the target webhook.
hikari.errors.RateLimitTooLongError
Raised in the event that a rate limit occurs that is
longer than max_rate_limit when making a request.
hikari.errors.RateLimitedError
Usually, Hikari will handle and retry on hitting
rate-limits automatically. This includes most bucket-specific
rate-limits and global rate-limits. In some rare edge cases,
however, Discord implements other undocumented rules for
rate-limiting, such as limits per attribute. These cannot be
detected or handled normally by Hikari due to their undocumented
nature, and will trigger this exception if they occur.
hikari.errors.InternalServerError
If an internal error occurs on Discord while handling the request.
"""  # noqa: E501 - Line too long
webhook = await self.app.rest.edit_webhook(
self.id,
name=name,
avatar=avatar,
channel=channel,
reason=reason,
)
assert isinstance(webhook, ChannelFollowerWebhook)
return webhook
async def fetch_channel() -> Union[GuildTextChannel, GuildNewsChannel]: ...

Fetch the channel this webhook is for.

## Returns

WebhookChannelT
The object of the channel this webhook targets.

## Raises

ForbiddenError
If you don't have access to the channel this webhook belongs to.
NotFoundError
If the channel this message was created in does not exist.
UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
RateLimitedError
Usually, Hikari will handle and retry on hitting rate-limits automatically. This includes most bucket-specific rate-limits and global rate-limits. In some rare edge cases, however, Discord implements other undocumented rules for rate-limiting, such as limits per attribute. These cannot be detected or handled normally by Hikari due to their undocumented nature, and will trigger this exception if they occur.
InternalServerError
If an internal error occurs on Discord while handling the request.
Expand source code
Browse git
async def fetch_channel(self) -> channels_.WebhookChannelT:
"""Fetch the channel this webhook is for.

Returns
-------
hikari.channels.WebhookChannelT
The object of the channel this webhook targets.

Raises
------
hikari.errors.ForbiddenError
If you don't have access to the channel this webhook belongs to.
hikari.errors.NotFoundError
If the channel this message was created in does not exist.
hikari.errors.UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
hikari.errors.RateLimitTooLongError
Raised in the event that a rate limit occurs that is
longer than max_rate_limit when making a request.
hikari.errors.RateLimitedError
Usually, Hikari will handle and retry on hitting
rate-limits automatically. This includes most bucket-specific
rate-limits and global rate-limits. In some rare edge cases,
however, Discord implements other undocumented rules for
rate-limiting, such as limits per attribute. These cannot be
detected or handled normally by Hikari due to their undocumented
nature, and will trigger this exception if they occur.
hikari.errors.InternalServerError
If an internal error occurs on Discord while handling the request.
"""
channel = await self.app.rest.fetch_channel(self.channel_id)
assert isinstance(channel, channels_.WebhookChannelTypes)
return channel
async def fetch_self() -> ChannelFollowerWebhook: ...

Fetch this webhook.

## Returns

ChannelFollowerWebhook
The requested webhook object.

## Raises

ForbiddenError
If you're not in the guild that owns this webhook or lack the MANAGE_WEBHOOKS permission.
NotFoundError
UnauthorizedError
If you pass a token that's invalid for the target webhook.
RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
RateLimitedError
Usually, Hikari will handle and retry on hitting rate-limits automatically. This includes most bucket-specific rate-limits and global rate-limits. In some rare edge cases, however, Discord implements other undocumented rules for rate-limiting, such as limits per attribute. These cannot be detected or handled normally by Hikari due to their undocumented nature, and will trigger this exception if they occur.
InternalServerError
If an internal error occurs on Discord while handling the request.
Expand source code
Browse git
async def fetch_self(self) -> ChannelFollowerWebhook:
"""Fetch this webhook.

Returns
-------
hikari.webhooks.ChannelFollowerWebhook
The requested webhook object.

Raises
------
hikari.errors.ForbiddenError
If you're not in the guild that owns this webhook or
lack the MANAGE_WEBHOOKS permission.
hikari.errors.NotFoundError
hikari.errors.UnauthorizedError
If you pass a token that's invalid for the target webhook.
hikari.errors.RateLimitTooLongError
Raised in the event that a rate limit occurs that is
longer than max_rate_limit when making a request.
hikari.errors.RateLimitedError
Usually, Hikari will handle and retry on hitting
rate-limits automatically. This includes most bucket-specific
rate-limits and global rate-limits. In some rare edge cases,
however, Discord implements other undocumented rules for
rate-limiting, such as limits per attribute. These cannot be
detected or handled normally by Hikari due to their undocumented
nature, and will trigger this exception if they occur.
hikari.errors.InternalServerError
If an internal error occurs on Discord while handling the request.
"""
webhook = await self.app.rest.fetch_webhook(self.id)
assert isinstance(webhook, ChannelFollowerWebhook)
return webhook
def make_avatar_url(
ext: str = 'png',
size: int = 4096,
) -> Optional[files_.URL]: ...

Inherited from: PartialWebhook.make_avatar_url

Generate the avatar URL for this webhook's custom avatar if set.

If no avatar is specified, return None. In this case, you should use default_avatar instead.

## Parameters

ext : str
The extension to use for this URL, defaults to png. Supports png, jpeg, jpg and webp.
size : int
The size to set for the URL, defaults to 4096. Can be any power of two between 16 and 4096. Will be ignored for default avatars.

## Returns

Optional[URL]
The URL of the resource. None if no avatar is set (in this case, use the default_avatar instead).

## Raises

ValueError
If size is not a power of two between 16 and 4096 (inclusive).

#### classExecutableWebhook

class ExecutableWebhook: ...

An abstract class with logic for executing entities as webhooks.

Expand source code
Browse git
class ExecutableWebhook(abc.ABC):
"""An abstract class with logic for executing entities as webhooks."""

# This is a mixin, do not add slotted fields.
__slots__: typing.Sequence[str] = ()

@property
@abc.abstractmethod
def app(self) -> traits.RESTAware:
"""Client application that models may use for procedures.

Returns
-------
hikari.traits.RESTAware
The client application that models may use for procedures.
"""

@property
@abc.abstractmethod
def webhook_id(self) -> snowflakes.Snowflake:
"""ID used to execute this entity as a webhook.

Returns
-------
hikari.snowflakes.Snowflake
The ID used to execute this entity as a webhook.
"""

@property
@abc.abstractmethod
def token(self) -> typing.Optional[str]:
"""Webhook's token.

!!! info
If this is builtins.None then the methods provided by ExecutableWebhook
will always raise a builtins.ValueError.

Returns
-------
typing.Optional[builtins.str]
The token for the webhook if known, else builtins.None.
"""

async def execute(
self,
content: undefined.UndefinedOr[typing.Any] = undefined.UNDEFINED,
*,
avatar_url: typing.Union[undefined.UndefinedType, str, files.URL] = undefined.UNDEFINED,
tts: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
attachment: undefined.UndefinedOr[files_.Resourceish] = undefined.UNDEFINED,
attachments: undefined.UndefinedOr[typing.Sequence[files_.Resourceish]] = undefined.UNDEFINED,
component: undefined.UndefinedOr[special_endpoints.ComponentBuilder] = undefined.UNDEFINED,
components: undefined.UndefinedOr[typing.Sequence[special_endpoints.ComponentBuilder]] = undefined.UNDEFINED,
embed: undefined.UndefinedOr[embeds_.Embed] = undefined.UNDEFINED,
embeds: undefined.UndefinedOr[typing.Sequence[embeds_.Embed]] = undefined.UNDEFINED,
mentions_everyone: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
user_mentions: undefined.UndefinedOr[
typing.Union[snowflakes.SnowflakeishSequence[users_.PartialUser], bool]
] = undefined.UNDEFINED,
role_mentions: undefined.UndefinedOr[
typing.Union[snowflakes.SnowflakeishSequence[guilds_.PartialRole], bool]
] = undefined.UNDEFINED,
flags: typing.Union[undefined.UndefinedType, int, messages_.MessageFlag] = undefined.UNDEFINED,
) -> messages_.Message:
"""Execute the webhook to create a message.

Parameters
----------
content : hikari.undefined.UndefinedOr[typing.Any]
If provided, the message contents. If
hikari.undefined.UNDEFINED, then nothing will be sent
in the content. Any other value here will be cast to a
builtins.str.

If this is a hikari.embeds.Embed and no embed kwarg is
provided, then this will instead update the embed. This allows for
simpler syntax when sending an embed alone.

Likewise, if this is a hikari.files.Resource, then the
content is instead treated as an attachment if no attachment and
no attachments kwargs are provided.

Other Parameters
----------------
for this request.
avatar_url : typing.Union[hikari.undefined.UndefinedType, builtins.str, hikari.files.URL]
If provided, the url of an image to override the webhook's
avatar with for this request.
tts : hikari.undefined.UndefinedOr[bool]
If provided, whether the message will be sent as a TTS message.
attachment : hikari.undefined.UndefinedOr[hikari.files.Resourceish]
If provided, the message attachment. This can be a resource,
or string of a path on your computer or a URL.
attachments : hikari.undefined.UndefinedOr[typing.Sequence[hikari.files.Resourceish]]
If provided, the message attachments. These can be resources, or
strings consisting of paths on your computer or URLs.
component : hikari.undefined.UndefinedOr[hikari.api.special_endpoints.ComponentBuilder]
If provided, builder object of the component to include in this message.
components : hikari.undefined.UndefinedOr[typing.Sequence[hikari.api.special_endpoints.ComponentBuilder]]
If provided, a sequence of the component builder objects to include
in this message.
embed : hikari.undefined.UndefinedOr[hikari.embeds.Embed]
If provided, the message embed.
embeds : hikari.undefined.UndefinedOr[typing.Sequence[hikari.embeds.Embed]]
If provided, the message embeds.
mentions_everyone : hikari.undefined.UndefinedOr[builtins.bool]
If provided, whether the message should parse @everyone/@here
mentions.
user_mentions : hikari.undefined.UndefinedOr[typing.Union[hikari.snowflakes.SnowflakeishSequence[hikari.users.PartialUser], builtins.bool]]
If provided, and builtins.True, all mentions will be parsed.
If provided, and builtins.False, no mentions will be parsed.
Alternatively this may be a collection of
hikari.snowflakes.Snowflake, or
hikari.users.PartialUser derivatives to enforce mentioning
specific users.
role_mentions : hikari.undefined.UndefinedOr[typing.Union[hikari.snowflakes.SnowflakeishSequence[hikari.guilds.PartialRole], builtins.bool]]
If provided, and builtins.True, all mentions will be parsed.
If provided, and builtins.False, no mentions will be parsed.
Alternatively this may be a collection of
hikari.snowflakes.Snowflake, or
hikari.guilds.PartialRole derivatives to enforce mentioning
specific roles.
flags : typing.Union[hikari.undefined.UndefinedType, builtins.int, hikari.messages.MessageFlag]
The flags to set for this webhook message.

!!! warning
As of writing this can only be set for interaction webhooks
and the only settable flag is EPHEMERAL; this field is just
ignored for non-interaction webhooks.

!!! warning
As of writing, username and avatar_url are ignored for
interaction webhooks.

Returns
-------
hikari.messages.Message
The created message object.

Raises
------
hikari.errors.NotFoundError
This can be raised if the file is too large; if the embed exceeds
the defined limits; if the message content is specified only and
empty or greater than 2000 characters; if neither content, file
or embeds are specified.
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
hikari.errors.UnauthorizedError
If you pass a token that's invalid for the target webhook.
builtins.ValueError
If either ExecutableWebhook.token is builtins.None or more than 100 unique
objects/entities are passed for role_mentions or user_mentions or
if token is not available.
builtins.TypeError
If both attachment and attachments are specified.
"""  # noqa: E501 - Line too long
if not self.token:
raise ValueError("Cannot send a message using a webhook where we don't know the token")

return await self.app.rest.execute_webhook(
webhook=self.webhook_id,
token=self.token,
content=content,
avatar_url=avatar_url,
tts=tts,
attachment=attachment,
attachments=attachments,
component=component,
components=components,
embed=embed,
embeds=embeds,
mentions_everyone=mentions_everyone,
user_mentions=user_mentions,
role_mentions=role_mentions,
flags=flags,
)

async def fetch_message(self, message: snowflakes.SnowflakeishOr[messages_.Message]) -> messages_.Message:
"""Fetch an old message sent by the webhook.

Parameters
----------
message : hikari.snowflakes.SnowflakeishOr[hikari.messages.PartialMessage]
The message to fetch. This may be the object or the ID of an
existing channel.

Returns
-------
hikari.messages.Message
The requested message.

Raises
------
builtins.ValueError
If token is not available.
hikari.errors.UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
hikari.errors.NotFoundError
If the webhook is not found or the webhook's message wasn't found.
hikari.errors.RateLimitTooLongError
Raised in the event that a rate limit occurs that is
longer than max_rate_limit when making a request.
hikari.errors.RateLimitedError
Usually, Hikari will handle and retry on hitting
rate-limits automatically. This includes most bucket-specific
rate-limits and global rate-limits. In some rare edge cases,
however, Discord implements other undocumented rules for
rate-limiting, such as limits per attribute. These cannot be
detected or handled normally by Hikari due to their undocumented
nature, and will trigger this exception if they occur.
hikari.errors.InternalServerError
If an internal error occurs on Discord while handling the request.
"""
if self.token is None:
raise ValueError("Cannot fetch a message using a webhook where we don't know the token")

return await self.app.rest.fetch_webhook_message(self.webhook_id, token=self.token, message=message)

async def edit_message(
self,
message: snowflakes.SnowflakeishOr[messages_.Message],
content: undefined.UndefinedNoneOr[typing.Any] = undefined.UNDEFINED,
*,
attachment: undefined.UndefinedOr[files.Resourceish] = undefined.UNDEFINED,
attachments: undefined.UndefinedOr[typing.Sequence[files.Resourceish]] = undefined.UNDEFINED,
component: undefined.UndefinedNoneOr[special_endpoints.ComponentBuilder] = undefined.UNDEFINED,
components: undefined.UndefinedNoneOr[
typing.Sequence[special_endpoints.ComponentBuilder]
] = undefined.UNDEFINED,
embed: undefined.UndefinedNoneOr[embeds_.Embed] = undefined.UNDEFINED,
embeds: undefined.UndefinedNoneOr[typing.Sequence[embeds_.Embed]] = undefined.UNDEFINED,
replace_attachments: bool = False,
mentions_everyone: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
user_mentions: undefined.UndefinedOr[
typing.Union[snowflakes.SnowflakeishSequence[users_.PartialUser], bool]
] = undefined.UNDEFINED,
role_mentions: undefined.UndefinedOr[
typing.Union[snowflakes.SnowflakeishSequence[guilds_.PartialRole], bool]
] = undefined.UNDEFINED,
) -> messages_.Message:
"""Edit a message sent by a webhook.

Parameters
----------
message : hikari.snowflakes.SnowflakeishOr[hikari.messages.PartialMessage]
The message to delete. This may be the object or the ID of
an existing message.
content : hikari.undefined.UndefinedNoneOr[typing.Any]
If provided, the message contents. If
hikari.undefined.UNDEFINED, then nothing will be sent
in the content. Any other value here will be cast to a
builtins.str.

If this is a hikari.embeds.Embed and no embed nor
no embeds kwarg is provided, then this will instead
update the embed. This allows for simpler syntax when
sending an embed alone.

Likewise, if this is a hikari.files.Resource, then the
content is instead treated as an attachment if no attachment and
no attachments kwargs are provided.

Other Parameters
----------------
attachment : hikari.undefined.UndefinedOr[hikari.files.Resourceish]
If provided, the attachment to set on the message. If
hikari.undefined.UNDEFINED, the previous attachment, if
present, is not changed. If this is builtins.None, then the
attachment is removed, if present. Otherwise, the new attachment
that was provided will be attached.
attachments : hikari.undefined.UndefinedOr[typing.Sequence[hikari.files.Resourceish]]
If provided, the attachments to set on the message. If
hikari.undefined.UNDEFINED, the previous attachments, if
present, are not changed. If this is builtins.None, then the
attachments is removed, if present. Otherwise, the new attachments
that were provided will be attached.
component : hikari.undefined.UndefinedNoneOr[hikari.api.special_endpoints.ComponentBuilder]
If provided, builder object of the component to set for this message.
This component will replace any previously set components and passing
builtins.None will remove all components.
components : hikari.undefined.UndefinedNoneOr[typing.Sequence[hikari.api.special_endpoints.ComponentBuilder]]
If provided, a sequence of the component builder objects set for
this message. These components will replace any previously set
components and passing builtins.None or an empty sequence will
remove all components.
embed : hikari.undefined.UndefinedNoneOr[hikari.embeds.Embed]
If provided, the embed to set on the message. If
hikari.undefined.UNDEFINED, the previous embed(s) are not changed.
If this is builtins.None then any present embeds are removed.
Otherwise, the new embed that was provided will be used as the
replacement.
embeds : hikari.undefined.UndefinedNoneOr[typing.Sequence[hikari.embeds.Embed]]
If provided, the embeds to set on the message. If
hikari.undefined.UNDEFINED, the previous embed(s) are not changed.
If this is builtins.None then any present embeds are removed.
Otherwise, the new embeds that were provided will be used as the
replacement.
replace_attachments: bool
Whether to replace the attachments with the provided ones. Defaults
to builtins.False.

Note this will also overwrite the embed attachments.
mentions_everyone : hikari.undefined.UndefinedOr[builtins.bool]
If provided, sanitation for @everyone mentions. If
hikari.undefined.UNDEFINED, then the previous setting is
not changed. If builtins.True, then @everyone/@here mentions
in the message content will show up as mentioning everyone that can
view the chat.
user_mentions : hikari.undefined.UndefinedOr[typing.Union[hikari.snowflakes.SnowflakeishSequence[hikari.users.PartialUser], builtins.bool]]
If provided, and builtins.True, all user mentions will be detected.
If provided, and builtins.False, all user mentions will be ignored
if appearing in the message body.
Alternatively this may be a collection of
hikari.snowflakes.Snowflake, or
hikari.users.PartialUser derivatives to enforce mentioning
specific users.
role_mentions : hikari.undefined.UndefinedOr[typing.Union[hikari.snowflakes.SnowflakeishSequence[hikari.guilds.PartialRole], builtins.bool]]
If provided, and builtins.True, all role mentions will be detected.
If provided, and builtins.False, all role mentions will be ignored
if appearing in the message body.
Alternatively this may be a collection of
hikari.snowflakes.Snowflake, or
hikari.guilds.PartialRole derivatives to enforce mentioning
specific roles.

!!! note
Mentioning everyone, roles, or users in message edits currently
will not send a push notification showing a new mention to people
on Discord. It will still highlight in their chat as if they
were mentioned, however.

!!! warning
If you specify a non-embed content, mentions_everyone,
mentions_reply, user_mentions, and role_mentions will default
to builtins.False as the message will be re-parsed for mentions.

This is a limitation of Discord's design. If in doubt, specify all
three of them each time.

!!! warning
If you specify one of mentions_everyone, mentions_reply,
user_mentions, or role_mentions, then all others will default to
builtins.False, even if they were enabled previously.

This is a limitation of Discord's design. If in doubt, specify all
three of them each time.

Returns
-------
hikari.messages.Message
The edited message.

Raises
------
builtins.ValueError
If more than 100 unique objects/entities are passed for
role_mentions or user_mentions or token is not available.
builtins.TypeError
If both attachment and attachments are specified or if both
embed and embeds are specified.
This may be raised in several discrete situations, such as messages
being empty with no attachments or embeds; messages with more than
2000 characters in them, embeds that exceed one of the many embed
limits; too many attachments; attachments that are too large;
too many components.
hikari.errors.UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
hikari.errors.NotFoundError
hikari.errors.RateLimitTooLongError
Raised in the event that a rate limit occurs that is
longer than max_rate_limit when making a request.
hikari.errors.RateLimitedError
Usually, Hikari will handle and retry on hitting
rate-limits automatically. This includes most bucket-specific
rate-limits and global rate-limits. In some rare edge cases,
however, Discord implements other undocumented rules for
rate-limiting, such as limits per attribute. These cannot be
detected or handled normally by Hikari due to their undocumented
nature, and will trigger this exception if they occur.
hikari.errors.InternalServerError
If an internal error occurs on Discord while handling the request.
"""  # noqa: E501 - Line too long
if self.token is None:
raise ValueError("Cannot edit a message using a webhook where we don't know the token")

return await self.app.rest.edit_webhook_message(
self.webhook_id,
token=self.token,
message=message,
content=content,
attachment=attachment,
attachments=attachments,
component=component,
components=components,
embed=embed,
embeds=embeds,
replace_attachments=replace_attachments,
mentions_everyone=mentions_everyone,
user_mentions=user_mentions,
role_mentions=role_mentions,
)

async def delete_message(self, message: snowflakes.SnowflakeishOr[messages_.Message]) -> None:
"""Delete a given message in a given channel.

Parameters
----------
message : hikari.snowflakes.SnowflakeishOr[hikari.messages.PartialMessage]
The message to delete. This may be the object or the ID of
an existing message.

Raises
------
builtins.ValueError
If token is not available.
hikari.errors.UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
hikari.errors.NotFoundError
hikari.errors.RateLimitTooLongError
Raised in the event that a rate limit occurs that is
longer than max_rate_limit when making a request.
hikari.errors.RateLimitedError
Usually, Hikari will handle and retry on hitting
rate-limits automatically. This includes most bucket-specific
rate-limits and global rate-limits. In some rare edge cases,
however, Discord implements other undocumented rules for
rate-limiting, such as limits per attribute. These cannot be
detected or handled normally by Hikari due to their undocumented
nature, and will trigger this exception if they occur.
hikari.errors.InternalServerError
If an internal error occurs on Discord while handling the request.
"""
if self.token is None:
raise ValueError("Cannot delete a message using a webhook where we don't know the token")

await self.app.rest.delete_webhook_message(self.webhook_id, token=self.token, message=message)
##### Subclasses
dataclass PartialInteraction

The base model for all interaction models …

dataclass IncomingWebhook

Represents an incoming webhook object on Discord …

##### Method resolution order
abstract class ExecutableWebhook
That's this class!
extern class abc.ABC

Helper class that provides a standard way to create an ABC using inheritance.

##### Variables and properties
abstract property app : traits.RESTAware

Client application that models may use for procedures.

## Returns

RESTAware
The client application that models may use for procedures.
abstract property token : Optional[str]

Webhook's token.

Info

If this is None then the methods provided by ExecutableWebhook will always raise a ValueError.

## Returns

Optional[str]
The token for the webhook if known, else None.
abstract property webhook_id : Snowflake

ID used to execute this entity as a webhook.

## Returns

Snowflake
The ID used to execute this entity as a webhook.
##### Methods
async def delete_message(
message: snowflakes.SnowflakeishOr[messages_.Message],
) -> None: ...

Delete a given message in a given channel.

## Parameters

message : SnowflakeishOr[PartialMessage]
The message to delete. This may be the object or the ID of an existing message.

## Raises

ValueError
If token is not available.
UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
NotFoundError
RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
RateLimitedError
Usually, Hikari will handle and retry on hitting rate-limits automatically. This includes most bucket-specific rate-limits and global rate-limits. In some rare edge cases, however, Discord implements other undocumented rules for rate-limiting, such as limits per attribute. These cannot be detected or handled normally by Hikari due to their undocumented nature, and will trigger this exception if they occur.
InternalServerError
If an internal error occurs on Discord while handling the request.
Expand source code
Browse git
async def delete_message(self, message: snowflakes.SnowflakeishOr[messages_.Message]) -> None:
"""Delete a given message in a given channel.

Parameters
----------
message : hikari.snowflakes.SnowflakeishOr[hikari.messages.PartialMessage]
The message to delete. This may be the object or the ID of
an existing message.

Raises
------
builtins.ValueError
If token is not available.
hikari.errors.UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
hikari.errors.NotFoundError
hikari.errors.RateLimitTooLongError
Raised in the event that a rate limit occurs that is
longer than max_rate_limit when making a request.
hikari.errors.RateLimitedError
Usually, Hikari will handle and retry on hitting
rate-limits automatically. This includes most bucket-specific
rate-limits and global rate-limits. In some rare edge cases,
however, Discord implements other undocumented rules for
rate-limiting, such as limits per attribute. These cannot be
detected or handled normally by Hikari due to their undocumented
nature, and will trigger this exception if they occur.
hikari.errors.InternalServerError
If an internal error occurs on Discord while handling the request.
"""
if self.token is None:
raise ValueError("Cannot delete a message using a webhook where we don't know the token")

await self.app.rest.delete_webhook_message(self.webhook_id, token=self.token, message=message)
async def edit_message(
message: snowflakes.SnowflakeishOr[messages_.Message],
content: undefined.UndefinedNoneOr[Any] = UNDEFINED,
*,
attachment: undefined.UndefinedOr[files.Resourceish] = UNDEFINED,
attachments: undefined.UndefinedOr[Sequence[files.Resourceish]] = UNDEFINED,
component: undefined.UndefinedNoneOr[special_endpoints.ComponentBuilder] = UNDEFINED,
components: undefined.UndefinedNoneOr[Sequence[special_endpoints.ComponentBuilder]] = UNDEFINED,
embed: undefined.UndefinedNoneOr[embeds_.Embed] = UNDEFINED,
embeds: undefined.UndefinedNoneOr[Sequence[embeds_.Embed]] = UNDEFINED,
replace_attachments: bool = False,
mentions_everyone: undefined.UndefinedOr[bool] = UNDEFINED,
user_mentions: undefined.UndefinedOr[Union[snowflakes.SnowflakeishSequence[users_.PartialUser], bool]] = UNDEFINED,
role_mentions: undefined.UndefinedOr[Union[snowflakes.SnowflakeishSequence[guilds_.PartialRole], bool]] = UNDEFINED,
) -> messages_.Message: ...

Edit a message sent by a webhook.

## Parameters

message : SnowflakeishOr[PartialMessage]
The message to delete. This may be the object or the ID of an existing message.
content : UndefinedNoneOr[Any]

If provided, the message contents. If UNDEFINED, then nothing will be sent in the content. Any other value here will be cast to a str.

If this is a Embed and no embed nor no embeds kwarg is provided, then this will instead update the embed. This allows for simpler syntax when sending an embed alone.

Likewise, if this is a Resource, then the content is instead treated as an attachment if no attachment and no attachments kwargs are provided.

## Other Parameters

attachment : UndefinedOr[Resourceish]
If provided, the attachment to set on the message. If UNDEFINED, the previous attachment, if present, is not changed. If this is None, then the attachment is removed, if present. Otherwise, the new attachment that was provided will be attached.
attachments : UndefinedOr[Sequence[Resourceish]]
If provided, the attachments to set on the message. If UNDEFINED, the previous attachments, if present, are not changed. If this is None, then the attachments is removed, if present. Otherwise, the new attachments that were provided will be attached.
component : UndefinedNoneOr[ComponentBuilder]
If provided, builder object of the component to set for this message. This component will replace any previously set components and passing None will remove all components.
components : UndefinedNoneOr[Sequence[ComponentBuilder]]
If provided, a sequence of the component builder objects set for this message. These components will replace any previously set components and passing None or an empty sequence will remove all components.
embed : UndefinedNoneOr[Embed]
If provided, the embed to set on the message. If UNDEFINED, the previous embed(s) are not changed. If this is None then any present embeds are removed. Otherwise, the new embed that was provided will be used as the replacement.
embeds : UndefinedNoneOr[Sequence[Embed]]
If provided, the embeds to set on the message. If UNDEFINED, the previous embed(s) are not changed. If this is None then any present embeds are removed. Otherwise, the new embeds that were provided will be used as the replacement.
replace_attachments : bool

Whether to replace the attachments with the provided ones. Defaults to False.

Note this will also overwrite the embed attachments.

mentions_everyone : UndefinedOr[bool]
If provided, sanitation for @everyone mentions. If UNDEFINED, then the previous setting is not changed. If True, then @everyone/@here mentions in the message content will show up as mentioning everyone that can view the chat.
user_mentions : UndefinedOr[Union[SnowflakeishSequence[PartialUser], bool]]
If provided, and True, all user mentions will be detected. If provided, and False, all user mentions will be ignored if appearing in the message body. Alternatively this may be a collection of Snowflake, or PartialUser derivatives to enforce mentioning specific users.
role_mentions : UndefinedOr[Union[SnowflakeishSequence[PartialRole], bool]]
If provided, and True, all role mentions will be detected. If provided, and False, all role mentions will be ignored if appearing in the message body. Alternatively this may be a collection of Snowflake, or PartialRole derivatives to enforce mentioning specific roles.

Note

Mentioning everyone, roles, or users in message edits currently will not send a push notification showing a new mention to people on Discord. It will still highlight in their chat as if they were mentioned, however.

Warning

If you specify a non-embed content, mentions_everyone, mentions_reply, user_mentions, and role_mentions will default to False as the message will be re-parsed for mentions.

This is a limitation of Discord's design. If in doubt, specify all three of them each time.

Warning

If you specify one of mentions_everyone, mentions_reply, user_mentions, or role_mentions, then all others will default to False, even if they were enabled previously.

This is a limitation of Discord's design. If in doubt, specify all three of them each time.

## Returns

Message
The edited message.

## Raises

ValueError
If more than 100 unique objects/entities are passed for role_mentions or user_mentions or token is not available.
TypeError
If both attachment and attachments are specified or if both embed and embeds are specified.
BadRequestError
This may be raised in several discrete situations, such as messages being empty with no attachments or embeds; messages with more than 2000 characters in them, embeds that exceed one of the many embed limits; too many attachments; attachments that are too large; too many components.
UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
NotFoundError
RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
RateLimitedError
Usually, Hikari will handle and retry on hitting rate-limits automatically. This includes most bucket-specific rate-limits and global rate-limits. In some rare edge cases, however, Discord implements other undocumented rules for rate-limiting, such as limits per attribute. These cannot be detected or handled normally by Hikari due to their undocumented nature, and will trigger this exception if they occur.
InternalServerError
If an internal error occurs on Discord while handling the request.
Expand source code
Browse git
async def edit_message(
self,
message: snowflakes.SnowflakeishOr[messages_.Message],
content: undefined.UndefinedNoneOr[typing.Any] = undefined.UNDEFINED,
*,
attachment: undefined.UndefinedOr[files.Resourceish] = undefined.UNDEFINED,
attachments: undefined.UndefinedOr[typing.Sequence[files.Resourceish]] = undefined.UNDEFINED,
component: undefined.UndefinedNoneOr[special_endpoints.ComponentBuilder] = undefined.UNDEFINED,
components: undefined.UndefinedNoneOr[
typing.Sequence[special_endpoints.ComponentBuilder]
] = undefined.UNDEFINED,
embed: undefined.UndefinedNoneOr[embeds_.Embed] = undefined.UNDEFINED,
embeds: undefined.UndefinedNoneOr[typing.Sequence[embeds_.Embed]] = undefined.UNDEFINED,
replace_attachments: bool = False,
mentions_everyone: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
user_mentions: undefined.UndefinedOr[
typing.Union[snowflakes.SnowflakeishSequence[users_.PartialUser], bool]
] = undefined.UNDEFINED,
role_mentions: undefined.UndefinedOr[
typing.Union[snowflakes.SnowflakeishSequence[guilds_.PartialRole], bool]
] = undefined.UNDEFINED,
) -> messages_.Message:
"""Edit a message sent by a webhook.

Parameters
----------
message : hikari.snowflakes.SnowflakeishOr[hikari.messages.PartialMessage]
The message to delete. This may be the object or the ID of
an existing message.
content : hikari.undefined.UndefinedNoneOr[typing.Any]
If provided, the message contents. If
hikari.undefined.UNDEFINED, then nothing will be sent
in the content. Any other value here will be cast to a
builtins.str.

If this is a hikari.embeds.Embed and no embed nor
no embeds kwarg is provided, then this will instead
update the embed. This allows for simpler syntax when
sending an embed alone.

Likewise, if this is a hikari.files.Resource, then the
content is instead treated as an attachment if no attachment and
no attachments kwargs are provided.

Other Parameters
----------------
attachment : hikari.undefined.UndefinedOr[hikari.files.Resourceish]
If provided, the attachment to set on the message. If
hikari.undefined.UNDEFINED, the previous attachment, if
present, is not changed. If this is builtins.None, then the
attachment is removed, if present. Otherwise, the new attachment
that was provided will be attached.
attachments : hikari.undefined.UndefinedOr[typing.Sequence[hikari.files.Resourceish]]
If provided, the attachments to set on the message. If
hikari.undefined.UNDEFINED, the previous attachments, if
present, are not changed. If this is builtins.None, then the
attachments is removed, if present. Otherwise, the new attachments
that were provided will be attached.
component : hikari.undefined.UndefinedNoneOr[hikari.api.special_endpoints.ComponentBuilder]
If provided, builder object of the component to set for this message.
This component will replace any previously set components and passing
builtins.None will remove all components.
components : hikari.undefined.UndefinedNoneOr[typing.Sequence[hikari.api.special_endpoints.ComponentBuilder]]
If provided, a sequence of the component builder objects set for
this message. These components will replace any previously set
components and passing builtins.None or an empty sequence will
remove all components.
embed : hikari.undefined.UndefinedNoneOr[hikari.embeds.Embed]
If provided, the embed to set on the message. If
hikari.undefined.UNDEFINED, the previous embed(s) are not changed.
If this is builtins.None then any present embeds are removed.
Otherwise, the new embed that was provided will be used as the
replacement.
embeds : hikari.undefined.UndefinedNoneOr[typing.Sequence[hikari.embeds.Embed]]
If provided, the embeds to set on the message. If
hikari.undefined.UNDEFINED, the previous embed(s) are not changed.
If this is builtins.None then any present embeds are removed.
Otherwise, the new embeds that were provided will be used as the
replacement.
replace_attachments: bool
Whether to replace the attachments with the provided ones. Defaults
to builtins.False.

Note this will also overwrite the embed attachments.
mentions_everyone : hikari.undefined.UndefinedOr[builtins.bool]
If provided, sanitation for @everyone mentions. If
hikari.undefined.UNDEFINED, then the previous setting is
not changed. If builtins.True, then @everyone/@here mentions
in the message content will show up as mentioning everyone that can
view the chat.
user_mentions : hikari.undefined.UndefinedOr[typing.Union[hikari.snowflakes.SnowflakeishSequence[hikari.users.PartialUser], builtins.bool]]
If provided, and builtins.True, all user mentions will be detected.
If provided, and builtins.False, all user mentions will be ignored
if appearing in the message body.
Alternatively this may be a collection of
hikari.snowflakes.Snowflake, or
hikari.users.PartialUser derivatives to enforce mentioning
specific users.
role_mentions : hikari.undefined.UndefinedOr[typing.Union[hikari.snowflakes.SnowflakeishSequence[hikari.guilds.PartialRole], builtins.bool]]
If provided, and builtins.True, all role mentions will be detected.
If provided, and builtins.False, all role mentions will be ignored
if appearing in the message body.
Alternatively this may be a collection of
hikari.snowflakes.Snowflake, or
hikari.guilds.PartialRole derivatives to enforce mentioning
specific roles.

!!! note
Mentioning everyone, roles, or users in message edits currently
will not send a push notification showing a new mention to people
on Discord. It will still highlight in their chat as if they
were mentioned, however.

!!! warning
If you specify a non-embed content, mentions_everyone,
mentions_reply, user_mentions, and role_mentions will default
to builtins.False as the message will be re-parsed for mentions.

This is a limitation of Discord's design. If in doubt, specify all
three of them each time.

!!! warning
If you specify one of mentions_everyone, mentions_reply,
user_mentions, or role_mentions, then all others will default to
builtins.False, even if they were enabled previously.

This is a limitation of Discord's design. If in doubt, specify all
three of them each time.

Returns
-------
hikari.messages.Message
The edited message.

Raises
------
builtins.ValueError
If more than 100 unique objects/entities are passed for
role_mentions or user_mentions or token is not available.
builtins.TypeError
If both attachment and attachments are specified or if both
embed and embeds are specified.
This may be raised in several discrete situations, such as messages
being empty with no attachments or embeds; messages with more than
2000 characters in them, embeds that exceed one of the many embed
limits; too many attachments; attachments that are too large;
too many components.
hikari.errors.UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
hikari.errors.NotFoundError
hikari.errors.RateLimitTooLongError
Raised in the event that a rate limit occurs that is
longer than max_rate_limit when making a request.
hikari.errors.RateLimitedError
Usually, Hikari will handle and retry on hitting
rate-limits automatically. This includes most bucket-specific
rate-limits and global rate-limits. In some rare edge cases,
however, Discord implements other undocumented rules for
rate-limiting, such as limits per attribute. These cannot be
detected or handled normally by Hikari due to their undocumented
nature, and will trigger this exception if they occur.
hikari.errors.InternalServerError
If an internal error occurs on Discord while handling the request.
"""  # noqa: E501 - Line too long
if self.token is None:
raise ValueError("Cannot edit a message using a webhook where we don't know the token")

return await self.app.rest.edit_webhook_message(
self.webhook_id,
token=self.token,
message=message,
content=content,
attachment=attachment,
attachments=attachments,
component=component,
components=components,
embed=embed,
embeds=embeds,
replace_attachments=replace_attachments,
mentions_everyone=mentions_everyone,
user_mentions=user_mentions,
role_mentions=role_mentions,
)
async def execute(
content: undefined.UndefinedOr[Any] = UNDEFINED,
*,
avatar_url: Union[undefined.UndefinedType, str, files.URL] = UNDEFINED,
tts: undefined.UndefinedOr[bool] = UNDEFINED,
attachment: undefined.UndefinedOr[files_.Resourceish] = UNDEFINED,
attachments: undefined.UndefinedOr[Sequence[files_.Resourceish]] = UNDEFINED,
component: undefined.UndefinedOr[special_endpoints.ComponentBuilder] = UNDEFINED,
components: undefined.UndefinedOr[Sequence[special_endpoints.ComponentBuilder]] = UNDEFINED,
embed: undefined.UndefinedOr[embeds_.Embed] = UNDEFINED,
embeds: undefined.UndefinedOr[Sequence[embeds_.Embed]] = UNDEFINED,
mentions_everyone: undefined.UndefinedOr[bool] = UNDEFINED,
user_mentions: undefined.UndefinedOr[Union[snowflakes.SnowflakeishSequence[users_.PartialUser], bool]] = UNDEFINED,
role_mentions: undefined.UndefinedOr[Union[snowflakes.SnowflakeishSequence[guilds_.PartialRole], bool]] = UNDEFINED,
flags: Union[undefined.UndefinedType, int, messages_.MessageFlag] = UNDEFINED,
) -> messages_.Message: ...

Execute the webhook to create a message.

## Parameters

content : UndefinedOr[Any]

If provided, the message contents. If UNDEFINED, then nothing will be sent in the content. Any other value here will be cast to a str.

If this is a Embed and no embed kwarg is provided, then this will instead update the embed. This allows for simpler syntax when sending an embed alone.

Likewise, if this is a Resource, then the content is instead treated as an attachment if no attachment and no attachments kwargs are provided.

## Other Parameters

username : UndefinedOr[str]
If provided, the username to override the webhook's username for this request.
avatar_url : Union[UndefinedType, str, URL]
If provided, the url of an image to override the webhook's avatar with for this request.
tts : UndefinedOr[bool]
If provided, whether the message will be sent as a TTS message.
attachment : UndefinedOr[Resourceish]
If provided, the message attachment. This can be a resource, or string of a path on your computer or a URL.
attachments : UndefinedOr[Sequence[Resourceish]]
If provided, the message attachments. These can be resources, or strings consisting of paths on your computer or URLs.
component : UndefinedOr[ComponentBuilder]
If provided, builder object of the component to include in this message.
components : UndefinedOr[Sequence[ComponentBuilder]]
If provided, a sequence of the component builder objects to include in this message.
embed : UndefinedOr[Embed]
If provided, the message embed.
embeds : UndefinedOr[Sequence[Embed]]
If provided, the message embeds.
mentions_everyone : UndefinedOr[bool]
If provided, whether the message should parse @everyone/@here mentions.
user_mentions : UndefinedOr[Union[SnowflakeishSequence[PartialUser], bool]]
If provided, and True, all mentions will be parsed. If provided, and False, no mentions will be parsed. Alternatively this may be a collection of Snowflake, or PartialUser derivatives to enforce mentioning specific users.
role_mentions : UndefinedOr[Union[SnowflakeishSequence[PartialRole], bool]]
If provided, and True, all mentions will be parsed. If provided, and False, no mentions will be parsed. Alternatively this may be a collection of Snowflake, or PartialRole derivatives to enforce mentioning specific roles.
flags : Union[UndefinedType, int, MessageFlag]

The flags to set for this webhook message.

Warning

As of writing this can only be set for interaction webhooks and the only settable flag is EPHEMERAL; this field is just ignored for non-interaction webhooks.

Warning

As of writing, username and avatar_url are ignored for interaction webhooks.

## Returns

Message
The created message object.

## Raises

NotFoundError
BadRequestError
This can be raised if the file is too large; if the embed exceeds the defined limits; if the message content is specified only and empty or greater than 2000 characters; if neither content, file or embeds are specified. If any invalid snowflake IDs are passed; a snowflake may be invalid due to it being outside of the range of a 64 bit integer.
UnauthorizedError
If you pass a token that's invalid for the target webhook.
ValueError
If either token is None or more than 100 unique objects/entities are passed for role_mentions or user_mentions or if token is not available.
TypeError
If both attachment and attachments are specified.
Expand source code
Browse git
async def execute(
self,
content: undefined.UndefinedOr[typing.Any] = undefined.UNDEFINED,
*,
avatar_url: typing.Union[undefined.UndefinedType, str, files.URL] = undefined.UNDEFINED,
tts: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
attachment: undefined.UndefinedOr[files_.Resourceish] = undefined.UNDEFINED,
attachments: undefined.UndefinedOr[typing.Sequence[files_.Resourceish]] = undefined.UNDEFINED,
component: undefined.UndefinedOr[special_endpoints.ComponentBuilder] = undefined.UNDEFINED,
components: undefined.UndefinedOr[typing.Sequence[special_endpoints.ComponentBuilder]] = undefined.UNDEFINED,
embed: undefined.UndefinedOr[embeds_.Embed] = undefined.UNDEFINED,
embeds: undefined.UndefinedOr[typing.Sequence[embeds_.Embed]] = undefined.UNDEFINED,
mentions_everyone: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
user_mentions: undefined.UndefinedOr[
typing.Union[snowflakes.SnowflakeishSequence[users_.PartialUser], bool]
] = undefined.UNDEFINED,
role_mentions: undefined.UndefinedOr[
typing.Union[snowflakes.SnowflakeishSequence[guilds_.PartialRole], bool]
] = undefined.UNDEFINED,
flags: typing.Union[undefined.UndefinedType, int, messages_.MessageFlag] = undefined.UNDEFINED,
) -> messages_.Message:
"""Execute the webhook to create a message.

Parameters
----------
content : hikari.undefined.UndefinedOr[typing.Any]
If provided, the message contents. If
hikari.undefined.UNDEFINED, then nothing will be sent
in the content. Any other value here will be cast to a
builtins.str.

If this is a hikari.embeds.Embed and no embed kwarg is
provided, then this will instead update the embed. This allows for
simpler syntax when sending an embed alone.

Likewise, if this is a hikari.files.Resource, then the
content is instead treated as an attachment if no attachment and
no attachments kwargs are provided.

Other Parameters
----------------
for this request.
avatar_url : typing.Union[hikari.undefined.UndefinedType, builtins.str, hikari.files.URL]
If provided, the url of an image to override the webhook's
avatar with for this request.
tts : hikari.undefined.UndefinedOr[bool]
If provided, whether the message will be sent as a TTS message.
attachment : hikari.undefined.UndefinedOr[hikari.files.Resourceish]
If provided, the message attachment. This can be a resource,
or string of a path on your computer or a URL.
attachments : hikari.undefined.UndefinedOr[typing.Sequence[hikari.files.Resourceish]]
If provided, the message attachments. These can be resources, or
strings consisting of paths on your computer or URLs.
component : hikari.undefined.UndefinedOr[hikari.api.special_endpoints.ComponentBuilder]
If provided, builder object of the component to include in this message.
components : hikari.undefined.UndefinedOr[typing.Sequence[hikari.api.special_endpoints.ComponentBuilder]]
If provided, a sequence of the component builder objects to include
in this message.
embed : hikari.undefined.UndefinedOr[hikari.embeds.Embed]
If provided, the message embed.
embeds : hikari.undefined.UndefinedOr[typing.Sequence[hikari.embeds.Embed]]
If provided, the message embeds.
mentions_everyone : hikari.undefined.UndefinedOr[builtins.bool]
If provided, whether the message should parse @everyone/@here
mentions.
user_mentions : hikari.undefined.UndefinedOr[typing.Union[hikari.snowflakes.SnowflakeishSequence[hikari.users.PartialUser], builtins.bool]]
If provided, and builtins.True, all mentions will be parsed.
If provided, and builtins.False, no mentions will be parsed.
Alternatively this may be a collection of
hikari.snowflakes.Snowflake, or
hikari.users.PartialUser derivatives to enforce mentioning
specific users.
role_mentions : hikari.undefined.UndefinedOr[typing.Union[hikari.snowflakes.SnowflakeishSequence[hikari.guilds.PartialRole], builtins.bool]]
If provided, and builtins.True, all mentions will be parsed.
If provided, and builtins.False, no mentions will be parsed.
Alternatively this may be a collection of
hikari.snowflakes.Snowflake, or
hikari.guilds.PartialRole derivatives to enforce mentioning
specific roles.
flags : typing.Union[hikari.undefined.UndefinedType, builtins.int, hikari.messages.MessageFlag]
The flags to set for this webhook message.

!!! warning
As of writing this can only be set for interaction webhooks
and the only settable flag is EPHEMERAL; this field is just
ignored for non-interaction webhooks.

!!! warning
As of writing, username and avatar_url are ignored for
interaction webhooks.

Returns
-------
hikari.messages.Message
The created message object.

Raises
------
hikari.errors.NotFoundError
This can be raised if the file is too large; if the embed exceeds
the defined limits; if the message content is specified only and
empty or greater than 2000 characters; if neither content, file
or embeds are specified.
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
hikari.errors.UnauthorizedError
If you pass a token that's invalid for the target webhook.
builtins.ValueError
If either ExecutableWebhook.token is builtins.None or more than 100 unique
objects/entities are passed for role_mentions or user_mentions or
if token is not available.
builtins.TypeError
If both attachment and attachments are specified.
"""  # noqa: E501 - Line too long
if not self.token:
raise ValueError("Cannot send a message using a webhook where we don't know the token")

return await self.app.rest.execute_webhook(
webhook=self.webhook_id,
token=self.token,
content=content,
avatar_url=avatar_url,
tts=tts,
attachment=attachment,
attachments=attachments,
component=component,
components=components,
embed=embed,
embeds=embeds,
mentions_everyone=mentions_everyone,
user_mentions=user_mentions,
role_mentions=role_mentions,
flags=flags,
)
async def fetch_message(
message: snowflakes.SnowflakeishOr[messages_.Message],
) -> messages_.Message: ...

Fetch an old message sent by the webhook.

## Parameters

message : SnowflakeishOr[PartialMessage]
The message to fetch. This may be the object or the ID of an existing channel.

## Returns

Message
The requested message.

## Raises

ValueError
If token is not available.
UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
NotFoundError
If the webhook is not found or the webhook's message wasn't found.
RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
RateLimitedError
Usually, Hikari will handle and retry on hitting rate-limits automatically. This includes most bucket-specific rate-limits and global rate-limits. In some rare edge cases, however, Discord implements other undocumented rules for rate-limiting, such as limits per attribute. These cannot be detected or handled normally by Hikari due to their undocumented nature, and will trigger this exception if they occur.
InternalServerError
If an internal error occurs on Discord while handling the request.
Expand source code
Browse git
async def fetch_message(self, message: snowflakes.SnowflakeishOr[messages_.Message]) -> messages_.Message:
"""Fetch an old message sent by the webhook.

Parameters
----------
message : hikari.snowflakes.SnowflakeishOr[hikari.messages.PartialMessage]
The message to fetch. This may be the object or the ID of an
existing channel.

Returns
-------
hikari.messages.Message
The requested message.

Raises
------
builtins.ValueError
If token is not available.
hikari.errors.UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
hikari.errors.NotFoundError
If the webhook is not found or the webhook's message wasn't found.
hikari.errors.RateLimitTooLongError
Raised in the event that a rate limit occurs that is
longer than max_rate_limit when making a request.
hikari.errors.RateLimitedError
Usually, Hikari will handle and retry on hitting
rate-limits automatically. This includes most bucket-specific
rate-limits and global rate-limits. In some rare edge cases,
however, Discord implements other undocumented rules for
rate-limiting, such as limits per attribute. These cannot be
detected or handled normally by Hikari due to their undocumented
nature, and will trigger this exception if they occur.
hikari.errors.InternalServerError
If an internal error occurs on Discord while handling the request.
"""
if self.token is None:
raise ValueError("Cannot fetch a message using a webhook where we don't know the token")

return await self.app.rest.fetch_webhook_message(self.webhook_id, token=self.token, message=message)

#### dataclassIncomingWebhook

class IncomingWebhook (
*,
app: traits.RESTAware,
id: snowflakes.Snowflake,
type: Union[WebhookType, int],
name: str,
avatar_hash: Optional[str],
application_id: Optional[snowflakes.Snowflake],
channel_id: snowflakes.Snowflake,
guild_id: snowflakes.Snowflake,
author: Optional[users_.User],
token: Optional[str],
): ...

Represents an incoming webhook object on Discord.

This is an endpoint that can have messages sent to it using standard HTTP requests, which enables external services that are not bots to send informational messages to specific channels.

Method generated by attrs for class IncomingWebhook.

Expand source code
Browse git
class IncomingWebhook(PartialWebhook, ExecutableWebhook):
"""Represents an incoming webhook object on Discord.

This is an endpoint that can have messages sent to it using standard
HTTP requests, which enables external services that are not bots to
send informational messages to specific channels.
"""

channel_id: snowflakes.Snowflake = attr.field(eq=False, hash=False, repr=True)
"""The channel ID this webhook is for."""

guild_id: snowflakes.Snowflake = attr.field(eq=False, hash=False, repr=True)
"""The guild ID of the webhook."""

author: typing.Optional[users_.User] = attr.field(eq=False, hash=False, repr=True)
"""The user that created the webhook

!!! info
This will be builtins.None when fetched with the webhook's token
rather than bot authorization or when received within audit logs.
"""

token: typing.Optional[str] = attr.field(eq=False, hash=False, repr=False)
"""The token for the webhook.

!!! info
This is only available for incoming webhooks that are created in the
channel settings.
"""

@property
def webhook_id(self) -> snowflakes.Snowflake:
# <<inherited docstring from ExecutableWebhook>>.
return self.id

async def delete(self, *, use_token: undefined.UndefinedOr[bool] = undefined.UNDEFINED) -> None:
"""Delete this webhook.

Other Parameters
----------------
use_token : hikari.undefined.UndefinedOr[builtins.bool]
If set to builtins.True then the webhook's token will be used for
this request; if set to builtins.False then bot authorization will
be used; if not specified then the webhook's token will be used for
the request if it's set else bot authorization.

Raises
------
hikari.errors.NotFoundError
hikari.errors.ForbiddenError
If you either lack the MANAGE_WEBHOOKS permission or
are not a member of the guild this webhook belongs to.
builtins.ValueError
If use_token is passed as builtins.True when IncomingWebhook.token is
builtins.None.
"""
token: undefined.UndefinedOr[str] = undefined.UNDEFINED
if use_token:
if self.token is None:
raise ValueError("This webhook's token is unknown, so cannot be used")
token = self.token

elif use_token is undefined.UNDEFINED and self.token:
token = self.token

await self.app.rest.delete_webhook(self.id, token=token)

async def edit(
self,
*,
name: undefined.UndefinedOr[str] = undefined.UNDEFINED,
channel: undefined.UndefinedOr[snowflakes.SnowflakeishOr[channels_.WebhookChannelT]] = undefined.UNDEFINED,
reason: undefined.UndefinedOr[str] = undefined.UNDEFINED,
use_token: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
) -> IncomingWebhook:
"""Edit this webhook.

Other Parameters
----------------
name : hikari.undefined.UndefinedOr[builtins.str]
If provided, the new name string.
avatar : hikari.undefined.UndefinedOr[hikari.files.Resourceish]
If provided, the new avatar image. If builtins.None, then
it is removed. If not specified, nothing is changed.
channel : hikari.undefined.UndefinedOr[hikari.snowflakes.SnowflakeishOr[hikari.channels.WebhookChannelT]]
If provided, the object or ID of the new channel the given
webhook should be moved to.
reason : hikari.undefined.UndefinedOr[builtins.str]
If provided, the audit log reason explaining why the operation
was performed. This field will be used when using the webhook's
token rather than bot authorization.
use_token : hikari.undefined.UndefinedOr[builtins.bool]
If set to builtins.True then the webhook's token will be used for
this request; if set to builtins.False then bot authorization will
be used; if not specified then the webhook's token will be used for
the request if it's set else bot authorization.

Returns
-------
IncomingWebhook
The updated webhook object.

Raises
------
builtins.ValueError
If use_token is passed as builtins.True when IncomingWebhook.token is builtins.None.
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
hikari.errors.NotFoundError
hikari.errors.ForbiddenError
If you either lack the MANAGE_WEBHOOKS permission or
are not a member of the guild this webhook belongs to.
hikari.errors.UnauthorizedError
If you pass a token that's invalid for the target webhook.
hikari.errors.RateLimitTooLongError
Raised in the event that a rate limit occurs that is
longer than max_rate_limit when making a request.
hikari.errors.RateLimitedError
Usually, Hikari will handle and retry on hitting
rate-limits automatically. This includes most bucket-specific
rate-limits and global rate-limits. In some rare edge cases,
however, Discord implements other undocumented rules for
rate-limiting, such as limits per attribute. These cannot be
detected or handled normally by Hikari due to their undocumented
nature, and will trigger this exception if they occur.
hikari.errors.InternalServerError
If an internal error occurs on Discord while handling the request.
"""  # noqa: E501 - Line too long
token: undefined.UndefinedOr[str] = undefined.UNDEFINED
if use_token:
if self.token is None:
raise ValueError("This webhook's token is unknown, so cannot be used")
token = self.token

elif use_token is undefined.UNDEFINED and self.token:
token = self.token

webhook = await self.app.rest.edit_webhook(
self.id,
token=token,
name=name,
avatar=avatar,
channel=channel,
reason=reason,
)
assert isinstance(webhook, IncomingWebhook)
return webhook

async def fetch_channel(self) -> channels_.WebhookChannelT:
"""Fetch the channel this webhook is for.

Returns
-------
hikari.channels.WebhookChannelT
The object of the channel this webhook targets.

Raises
------
hikari.errors.ForbiddenError
If you don't have access to the channel this webhook belongs to.
hikari.errors.NotFoundError
If the channel this message was created in does not exist.
hikari.errors.UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
hikari.errors.RateLimitTooLongError
Raised in the event that a rate limit occurs that is
longer than max_rate_limit when making a request.
hikari.errors.RateLimitedError
Usually, Hikari will handle and retry on hitting
rate-limits automatically. This includes most bucket-specific
rate-limits and global rate-limits. In some rare edge cases,
however, Discord implements other undocumented rules for
rate-limiting, such as limits per attribute. These cannot be
detected or handled normally by Hikari due to their undocumented
nature, and will trigger this exception if they occur.
hikari.errors.InternalServerError
If an internal error occurs on Discord while handling the request.
"""
channel = await self.app.rest.fetch_channel(self.channel_id)
assert isinstance(channel, channels_.WebhookChannelTypes)
return channel

async def fetch_self(self, *, use_token: undefined.UndefinedOr[bool] = undefined.UNDEFINED) -> IncomingWebhook:
"""Fetch this webhook.

Other Parameters
----------------
use_token : hikari.undefined.UndefinedOr[builtins.bool]
If set to builtins.True then the webhook's token will be used for
this request; if set to builtins.False then bot authorization will
be used; if not specified then the webhook's token will be used for
the request if it's set else bot authorization.

Returns
-------
IncomingWebhook
The requested webhook object.

Raises
------
builtins.ValueError
If use_token is passed as builtins.True when Webhook.token
is builtins.None.
hikari.errors.ForbiddenError
If you're not in the guild that owns this webhook or
lack the MANAGE_WEBHOOKS permission.
hikari.errors.NotFoundError
hikari.errors.UnauthorizedError
If you pass a token that's invalid for the target webhook.
hikari.errors.RateLimitTooLongError
Raised in the event that a rate limit occurs that is
longer than max_rate_limit when making a request.
hikari.errors.RateLimitedError
Usually, Hikari will handle and retry on hitting
rate-limits automatically. This includes most bucket-specific
rate-limits and global rate-limits. In some rare edge cases,
however, Discord implements other undocumented rules for
rate-limiting, such as limits per attribute. These cannot be
detected or handled normally by Hikari due to their undocumented
nature, and will trigger this exception if they occur.
hikari.errors.InternalServerError
If an internal error occurs on Discord while handling the request.
"""
token: undefined.UndefinedOr[str] = undefined.UNDEFINED
if use_token:
if self.token is None:
raise ValueError("This webhook's token is unknown, so cannot be used")
token = self.token

elif use_token is undefined.UNDEFINED and self.token:
token = self.token

webhook = await self.app.rest.fetch_webhook(self.id, token=token)
assert isinstance(webhook, IncomingWebhook)
return webhook
##### Method resolution order
dataclass IncomingWebhook
That's this class!
dataclass PartialWebhook

Base class for all webhook implementations …

abstract class Unique

Mixin for a class that enforces uniqueness by a snowflake ID.

abstract class ExecutableWebhook

An abstract class with logic for executing entities as webhooks.

extern class abc.ABC

Helper class that provides a standard way to create an ABC using inheritance.

##### Variables and properties
property app : traits.RESTAware

The client application that models may use for procedures.

property application_id : Optional[snowflakes.Snowflake]

The ID of the application that created this webhook.

property author : Optional[users_.User]

The user that created the webhook

Info

This will be None when fetched with the webhook's token rather than bot authorization or when received within audit logs.

property avatar_hash : Optional[str]

The avatar hash of the webhook.

property avatar_url : Optional[files_.URL]

URL for this webhook's avatar, if set.

May be None if no avatar is set. In this case, you should use default_avatar_url instead.

property channel_id : snowflakes.Snowflake

The channel ID this webhook is for.

property created_at : datetime.datetime

When the object was created.

property default_avatar_url : files_.URL

Avatar URL for the user, if they have one set.

May be None if no custom avatar is set. In this case, you should use default_avatar_url instead.

property guild_id : snowflakes.Snowflake

The guild ID of the webhook.

property id : snowflakes.Snowflake

The ID of this entity.

property mention : str

Return a raw mention string for the given webhook's user.

Note

This exists purely for consistency. Webhooks do not receive events from the gateway, and without some bot backend to support it, will not be able to detect mentions of their webhook.

## Example

>>> some_webhook.mention
'<@123456789123456789>'


## Returns

str
The mention string to use.
property name : str

The name of the webhook.

property token : Optional[str]

The token for the webhook.

Info

This is only available for incoming webhooks that are created in the channel settings.

property type : Union[WebhookType, int]

The type of the webhook.

property webhook_id : Snowflake

ID used to execute this entity as a webhook.

## Returns

Snowflake
The ID used to execute this entity as a webhook.
##### Methods
async def delete(
*,
use_token: undefined.UndefinedOr[bool] = UNDEFINED,
) -> None: ...

Delete this webhook.

## Other Parameters

use_token : UndefinedOr[bool]
If set to True then the webhook's token will be used for this request; if set to False then bot authorization will be used; if not specified then the webhook's token will be used for the request if it's set else bot authorization.

## Raises

NotFoundError
ForbiddenError
If you either lack the MANAGE_WEBHOOKS permission or are not a member of the guild this webhook belongs to.
ValueError
If use_token is passed as True when token is None.
Expand source code
Browse git
async def delete(self, *, use_token: undefined.UndefinedOr[bool] = undefined.UNDEFINED) -> None:
"""Delete this webhook.

Other Parameters
----------------
use_token : hikari.undefined.UndefinedOr[builtins.bool]
If set to builtins.True then the webhook's token will be used for
this request; if set to builtins.False then bot authorization will
be used; if not specified then the webhook's token will be used for
the request if it's set else bot authorization.

Raises
------
hikari.errors.NotFoundError
hikari.errors.ForbiddenError
If you either lack the MANAGE_WEBHOOKS permission or
are not a member of the guild this webhook belongs to.
builtins.ValueError
If use_token is passed as builtins.True when IncomingWebhook.token is
builtins.None.
"""
token: undefined.UndefinedOr[str] = undefined.UNDEFINED
if use_token:
if self.token is None:
raise ValueError("This webhook's token is unknown, so cannot be used")
token = self.token

elif use_token is undefined.UNDEFINED and self.token:
token = self.token

await self.app.rest.delete_webhook(self.id, token=token)
async def delete_message(
message: snowflakes.SnowflakeishOr[messages_.Message],
) -> None: ...

Inherited from: ExecutableWebhook.delete_message

Delete a given message in a given channel.

## Parameters

message : SnowflakeishOr[PartialMessage]
The message to delete. This may be the object or the ID of an existing message.

## Raises

ValueError
If token is not available.
UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
NotFoundError
RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
RateLimitedError
Usually, Hikari will handle and retry on hitting rate-limits automatically. This includes most bucket-specific rate-limits and global rate-limits. In some rare edge cases, however, Discord implements other undocumented rules for rate-limiting, such as limits per attribute. These cannot be detected or handled normally by Hikari due to their undocumented nature, and will trigger this exception if they occur.
InternalServerError
If an internal error occurs on Discord while handling the request.
async def edit(
*,
name: undefined.UndefinedOr[str] = UNDEFINED,
channel: undefined.UndefinedOr[snowflakes.SnowflakeishOr[channels_.WebhookChannelT]] = UNDEFINED,
reason: undefined.UndefinedOr[str] = UNDEFINED,
use_token: undefined.UndefinedOr[bool] = UNDEFINED,
) -> IncomingWebhook: ...

Edit this webhook.

## Other Parameters

name : UndefinedOr[str]
If provided, the new name string.
avatar : UndefinedOr[Resourceish]
If provided, the new avatar image. If None, then it is removed. If not specified, nothing is changed.
channel : UndefinedOr[SnowflakeishOr[WebhookChannelT]]
If provided, the object or ID of the new channel the given webhook should be moved to.
reason : UndefinedOr[str]
If provided, the audit log reason explaining why the operation was performed. This field will be used when using the webhook's token rather than bot authorization.
use_token : UndefinedOr[bool]
If set to True then the webhook's token will be used for this request; if set to False then bot authorization will be used; if not specified then the webhook's token will be used for the request if it's set else bot authorization.

## Returns

IncomingWebhook
The updated webhook object.

## Raises

ValueError
If use_token is passed as True when token is None.
BadRequestError
If any invalid snowflake IDs are passed; a snowflake may be invalid due to it being outside of the range of a 64 bit integer.
NotFoundError
ForbiddenError
If you either lack the MANAGE_WEBHOOKS permission or are not a member of the guild this webhook belongs to.
UnauthorizedError
If you pass a token that's invalid for the target webhook.
RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
RateLimitedError
Usually, Hikari will handle and retry on hitting rate-limits automatically. This includes most bucket-specific rate-limits and global rate-limits. In some rare edge cases, however, Discord implements other undocumented rules for rate-limiting, such as limits per attribute. These cannot be detected or handled normally by Hikari due to their undocumented nature, and will trigger this exception if they occur.
InternalServerError
If an internal error occurs on Discord while handling the request.
Expand source code
Browse git
async def edit(
self,
*,
name: undefined.UndefinedOr[str] = undefined.UNDEFINED,
channel: undefined.UndefinedOr[snowflakes.SnowflakeishOr[channels_.WebhookChannelT]] = undefined.UNDEFINED,
reason: undefined.UndefinedOr[str] = undefined.UNDEFINED,
use_token: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
) -> IncomingWebhook:
"""Edit this webhook.

Other Parameters
----------------
name : hikari.undefined.UndefinedOr[builtins.str]
If provided, the new name string.
avatar : hikari.undefined.UndefinedOr[hikari.files.Resourceish]
If provided, the new avatar image. If builtins.None, then
it is removed. If not specified, nothing is changed.
channel : hikari.undefined.UndefinedOr[hikari.snowflakes.SnowflakeishOr[hikari.channels.WebhookChannelT]]
If provided, the object or ID of the new channel the given
webhook should be moved to.
reason : hikari.undefined.UndefinedOr[builtins.str]
If provided, the audit log reason explaining why the operation
was performed. This field will be used when using the webhook's
token rather than bot authorization.
use_token : hikari.undefined.UndefinedOr[builtins.bool]
If set to builtins.True then the webhook's token will be used for
this request; if set to builtins.False then bot authorization will
be used; if not specified then the webhook's token will be used for
the request if it's set else bot authorization.

Returns
-------
IncomingWebhook
The updated webhook object.

Raises
------
builtins.ValueError
If use_token is passed as builtins.True when IncomingWebhook.token is builtins.None.
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
hikari.errors.NotFoundError
hikari.errors.ForbiddenError
If you either lack the MANAGE_WEBHOOKS permission or
are not a member of the guild this webhook belongs to.
hikari.errors.UnauthorizedError
If you pass a token that's invalid for the target webhook.
hikari.errors.RateLimitTooLongError
Raised in the event that a rate limit occurs that is
longer than max_rate_limit when making a request.
hikari.errors.RateLimitedError
Usually, Hikari will handle and retry on hitting
rate-limits automatically. This includes most bucket-specific
rate-limits and global rate-limits. In some rare edge cases,
however, Discord implements other undocumented rules for
rate-limiting, such as limits per attribute. These cannot be
detected or handled normally by Hikari due to their undocumented
nature, and will trigger this exception if they occur.
hikari.errors.InternalServerError
If an internal error occurs on Discord while handling the request.
"""  # noqa: E501 - Line too long
token: undefined.UndefinedOr[str] = undefined.UNDEFINED
if use_token:
if self.token is None:
raise ValueError("This webhook's token is unknown, so cannot be used")
token = self.token

elif use_token is undefined.UNDEFINED and self.token:
token = self.token

webhook = await self.app.rest.edit_webhook(
self.id,
token=token,
name=name,
avatar=avatar,
channel=channel,
reason=reason,
)
assert isinstance(webhook, IncomingWebhook)
return webhook
async def edit_message(
message: snowflakes.SnowflakeishOr[messages_.Message],
content: undefined.UndefinedNoneOr[Any] = UNDEFINED,
*,
attachment: undefined.UndefinedOr[files.Resourceish] = UNDEFINED,
attachments: undefined.UndefinedOr[Sequence[files.Resourceish]] = UNDEFINED,
component: undefined.UndefinedNoneOr[special_endpoints.ComponentBuilder] = UNDEFINED,
components: undefined.UndefinedNoneOr[Sequence[special_endpoints.ComponentBuilder]] = UNDEFINED,
embed: undefined.UndefinedNoneOr[embeds_.Embed] = UNDEFINED,
embeds: undefined.UndefinedNoneOr[Sequence[embeds_.Embed]] = UNDEFINED,
replace_attachments: bool = False,
mentions_everyone: undefined.UndefinedOr[bool] = UNDEFINED,
user_mentions: undefined.UndefinedOr[Union[snowflakes.SnowflakeishSequence[users_.PartialUser], bool]] = UNDEFINED,
role_mentions: undefined.UndefinedOr[Union[snowflakes.SnowflakeishSequence[guilds_.PartialRole], bool]] = UNDEFINED,
) -> messages_.Message: ...

Inherited from: ExecutableWebhook.edit_message

Edit a message sent by a webhook.

## Parameters

message : SnowflakeishOr[PartialMessage]
The message to delete. This may be the object or the ID of an existing message.
content : UndefinedNoneOr[Any]

If provided, the message contents. If UNDEFINED, then nothing will be sent in the content. Any other value here will be cast to a str.

If this is a Embed and no embed nor no embeds kwarg is provided, then this will instead update the embed. This allows for simpler syntax when sending an embed alone.

Likewise, if this is a Resource, then the content is instead treated as an attachment if no attachment and no attachments kwargs are provided.

## Other Parameters

attachment : UndefinedOr[Resourceish]
If provided, the attachment to set on the message. If UNDEFINED, the previous attachment, if present, is not changed. If this is None, then the attachment is removed, if present. Otherwise, the new attachment that was provided will be attached.
attachments : UndefinedOr[Sequence[Resourceish]]
If provided, the attachments to set on the message. If UNDEFINED, the previous attachments, if present, are not changed. If this is None, then the attachments is removed, if present. Otherwise, the new attachments that were provided will be attached.
component : UndefinedNoneOr[ComponentBuilder]
If provided, builder object of the component to set for this message. This component will replace any previously set components and passing None will remove all components.
components : UndefinedNoneOr[Sequence[ComponentBuilder]]
If provided, a sequence of the component builder objects set for this message. These components will replace any previously set components and passing None or an empty sequence will remove all components.
embed : UndefinedNoneOr[Embed]
If provided, the embed to set on the message. If UNDEFINED, the previous embed(s) are not changed. If this is None then any present embeds are removed. Otherwise, the new embed that was provided will be used as the replacement.
embeds : UndefinedNoneOr[Sequence[Embed]]
If provided, the embeds to set on the message. If UNDEFINED, the previous embed(s) are not changed. If this is None then any present embeds are removed. Otherwise, the new embeds that were provided will be used as the replacement.
replace_attachments : bool

Whether to replace the attachments with the provided ones. Defaults to False.

Note this will also overwrite the embed attachments.

mentions_everyone : UndefinedOr[bool]
If provided, sanitation for @everyone mentions. If UNDEFINED, then the previous setting is not changed. If True, then @everyone/@here mentions in the message content will show up as mentioning everyone that can view the chat.
user_mentions : UndefinedOr[Union[SnowflakeishSequence[PartialUser], bool]]
If provided, and True, all user mentions will be detected. If provided, and False, all user mentions will be ignored if appearing in the message body. Alternatively this may be a collection of Snowflake, or PartialUser derivatives to enforce mentioning specific users.
role_mentions : UndefinedOr[Union[SnowflakeishSequence[PartialRole], bool]]
If provided, and True, all role mentions will be detected. If provided, and False, all role mentions will be ignored if appearing in the message body. Alternatively this may be a collection of Snowflake, or PartialRole derivatives to enforce mentioning specific roles.

Note

Mentioning everyone, roles, or users in message edits currently will not send a push notification showing a new mention to people on Discord. It will still highlight in their chat as if they were mentioned, however.

Warning

If you specify a non-embed content, mentions_everyone, mentions_reply, user_mentions, and role_mentions will default to False as the message will be re-parsed for mentions.

This is a limitation of Discord's design. If in doubt, specify all three of them each time.

Warning

If you specify one of mentions_everyone, mentions_reply, user_mentions, or role_mentions, then all others will default to False, even if they were enabled previously.

This is a limitation of Discord's design. If in doubt, specify all three of them each time.

## Returns

Message
The edited message.

## Raises

ValueError
If more than 100 unique objects/entities are passed for role_mentions or user_mentions or token is not available.
TypeError
If both attachment and attachments are specified or if both embed and embeds are specified.
BadRequestError
This may be raised in several discrete situations, such as messages being empty with no attachments or embeds; messages with more than 2000 characters in them, embeds that exceed one of the many embed limits; too many attachments; attachments that are too large; too many components.
UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
NotFoundError
RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
RateLimitedError
Usually, Hikari will handle and retry on hitting rate-limits automatically. This includes most bucket-specific rate-limits and global rate-limits. In some rare edge cases, however, Discord implements other undocumented rules for rate-limiting, such as limits per attribute. These cannot be detected or handled normally by Hikari due to their undocumented nature, and will trigger this exception if they occur.
InternalServerError
If an internal error occurs on Discord while handling the request.
async def execute(
content: undefined.UndefinedOr[Any] = UNDEFINED,
*,
avatar_url: Union[undefined.UndefinedType, str, files.URL] = UNDEFINED,
tts: undefined.UndefinedOr[bool] = UNDEFINED,
attachment: undefined.UndefinedOr[files_.Resourceish] = UNDEFINED,
attachments: undefined.UndefinedOr[Sequence[files_.Resourceish]] = UNDEFINED,
component: undefined.UndefinedOr[special_endpoints.ComponentBuilder] = UNDEFINED,
components: undefined.UndefinedOr[Sequence[special_endpoints.ComponentBuilder]] = UNDEFINED,
embed: undefined.UndefinedOr[embeds_.Embed] = UNDEFINED,
embeds: undefined.UndefinedOr[Sequence[embeds_.Embed]] = UNDEFINED,
mentions_everyone: undefined.UndefinedOr[bool] = UNDEFINED,
user_mentions: undefined.UndefinedOr[Union[snowflakes.SnowflakeishSequence[users_.PartialUser], bool]] = UNDEFINED,
role_mentions: undefined.UndefinedOr[Union[snowflakes.SnowflakeishSequence[guilds_.PartialRole], bool]] = UNDEFINED,
flags: Union[undefined.UndefinedType, int, messages_.MessageFlag] = UNDEFINED,
) -> messages_.Message: ...

Inherited from: ExecutableWebhook.execute

Execute the webhook to create a message.

## Parameters

content : UndefinedOr[Any]

If provided, the message contents. If UNDEFINED, then nothing will be sent in the content. Any other value here will be cast to a str.

If this is a Embed and no embed kwarg is provided, then this will instead update the embed. This allows for simpler syntax when sending an embed alone.

Likewise, if this is a Resource, then the content is instead treated as an attachment if no attachment and no attachments kwargs are provided.

## Other Parameters

username : UndefinedOr[str]
If provided, the username to override the webhook's username for this request.
avatar_url : Union[UndefinedType, str, URL]
If provided, the url of an image to override the webhook's avatar with for this request.
tts : UndefinedOr[bool]
If provided, whether the message will be sent as a TTS message.
attachment : UndefinedOr[Resourceish]
If provided, the message attachment. This can be a resource, or string of a path on your computer or a URL.
attachments : UndefinedOr[Sequence[Resourceish]]
If provided, the message attachments. These can be resources, or strings consisting of paths on your computer or URLs.
component : UndefinedOr[ComponentBuilder]
If provided, builder object of the component to include in this message.
components : UndefinedOr[Sequence[ComponentBuilder]]
If provided, a sequence of the component builder objects to include in this message.
embed : UndefinedOr[Embed]
If provided, the message embed.
embeds : UndefinedOr[Sequence[Embed]]
If provided, the message embeds.
mentions_everyone : UndefinedOr[bool]
If provided, whether the message should parse @everyone/@here mentions.
user_mentions : UndefinedOr[Union[SnowflakeishSequence[PartialUser], bool]]
If provided, and True, all mentions will be parsed. If provided, and False, no mentions will be parsed. Alternatively this may be a collection of Snowflake, or PartialUser derivatives to enforce mentioning specific users.
role_mentions : UndefinedOr[Union[SnowflakeishSequence[PartialRole], bool]]
If provided, and True, all mentions will be parsed. If provided, and False, no mentions will be parsed. Alternatively this may be a collection of Snowflake, or PartialRole derivatives to enforce mentioning specific roles.
flags : Union[UndefinedType, int, MessageFlag]

The flags to set for this webhook message.

Warning

As of writing this can only be set for interaction webhooks and the only settable flag is EPHEMERAL; this field is just ignored for non-interaction webhooks.

Warning

As of writing, username and avatar_url are ignored for interaction webhooks.

## Returns

Message
The created message object.

## Raises

NotFoundError
BadRequestError
This can be raised if the file is too large; if the embed exceeds the defined limits; if the message content is specified only and empty or greater than 2000 characters; if neither content, file or embeds are specified. If any invalid snowflake IDs are passed; a snowflake may be invalid due to it being outside of the range of a 64 bit integer.
UnauthorizedError
If you pass a token that's invalid for the target webhook.
ValueError
If either token is None or more than 100 unique objects/entities are passed for role_mentions or user_mentions or if token is not available.
TypeError
If both attachment and attachments are specified.
async def fetch_channel() -> Union[GuildTextChannel, GuildNewsChannel]: ...

Fetch the channel this webhook is for.

## Returns

WebhookChannelT
The object of the channel this webhook targets.

## Raises

ForbiddenError
If you don't have access to the channel this webhook belongs to.
NotFoundError
If the channel this message was created in does not exist.
UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
RateLimitedError
Usually, Hikari will handle and retry on hitting rate-limits automatically. This includes most bucket-specific rate-limits and global rate-limits. In some rare edge cases, however, Discord implements other undocumented rules for rate-limiting, such as limits per attribute. These cannot be detected or handled normally by Hikari due to their undocumented nature, and will trigger this exception if they occur.
InternalServerError
If an internal error occurs on Discord while handling the request.
Expand source code
Browse git
async def fetch_channel(self) -> channels_.WebhookChannelT:
"""Fetch the channel this webhook is for.

Returns
-------
hikari.channels.WebhookChannelT
The object of the channel this webhook targets.

Raises
------
hikari.errors.ForbiddenError
If you don't have access to the channel this webhook belongs to.
hikari.errors.NotFoundError
If the channel this message was created in does not exist.
hikari.errors.UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
hikari.errors.RateLimitTooLongError
Raised in the event that a rate limit occurs that is
longer than max_rate_limit when making a request.
hikari.errors.RateLimitedError
Usually, Hikari will handle and retry on hitting
rate-limits automatically. This includes most bucket-specific
rate-limits and global rate-limits. In some rare edge cases,
however, Discord implements other undocumented rules for
rate-limiting, such as limits per attribute. These cannot be
detected or handled normally by Hikari due to their undocumented
nature, and will trigger this exception if they occur.
hikari.errors.InternalServerError
If an internal error occurs on Discord while handling the request.
"""
channel = await self.app.rest.fetch_channel(self.channel_id)
assert isinstance(channel, channels_.WebhookChannelTypes)
return channel
async def fetch_message(
message: snowflakes.SnowflakeishOr[messages_.Message],
) -> messages_.Message: ...

Inherited from: ExecutableWebhook.fetch_message

Fetch an old message sent by the webhook.

## Parameters

message : SnowflakeishOr[PartialMessage]
The message to fetch. This may be the object or the ID of an existing channel.

## Returns

Message
The requested message.

## Raises

ValueError
If token is not available.
UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
NotFoundError
If the webhook is not found or the webhook's message wasn't found.
RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
RateLimitedError
Usually, Hikari will handle and retry on hitting rate-limits automatically. This includes most bucket-specific rate-limits and global rate-limits. In some rare edge cases, however, Discord implements other undocumented rules for rate-limiting, such as limits per attribute. These cannot be detected or handled normally by Hikari due to their undocumented nature, and will trigger this exception if they occur.
InternalServerError
If an internal error occurs on Discord while handling the request.
async def fetch_self(
*,
use_token: undefined.UndefinedOr[bool] = UNDEFINED,
) -> IncomingWebhook: ...

Fetch this webhook.

## Other Parameters

use_token : UndefinedOr[bool]
If set to True then the webhook's token will be used for this request; if set to False then bot authorization will be used; if not specified then the webhook's token will be used for the request if it's set else bot authorization.

## Returns

IncomingWebhook
The requested webhook object.

## Raises

ValueError
If use_token is passed as True when Webhook.token is None.
ForbiddenError
If you're not in the guild that owns this webhook or lack the MANAGE_WEBHOOKS permission.
NotFoundError
UnauthorizedError
If you pass a token that's invalid for the target webhook.
RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
RateLimitedError
Usually, Hikari will handle and retry on hitting rate-limits automatically. This includes most bucket-specific rate-limits and global rate-limits. In some rare edge cases, however, Discord implements other undocumented rules for rate-limiting, such as limits per attribute. These cannot be detected or handled normally by Hikari due to their undocumented nature, and will trigger this exception if they occur.
InternalServerError
If an internal error occurs on Discord while handling the request.
Expand source code
Browse git
async def fetch_self(self, *, use_token: undefined.UndefinedOr[bool] = undefined.UNDEFINED) -> IncomingWebhook:
"""Fetch this webhook.

Other Parameters
----------------
use_token : hikari.undefined.UndefinedOr[builtins.bool]
If set to builtins.True then the webhook's token will be used for
this request; if set to builtins.False then bot authorization will
be used; if not specified then the webhook's token will be used for
the request if it's set else bot authorization.

Returns
-------
IncomingWebhook
The requested webhook object.

Raises
------
builtins.ValueError
If use_token is passed as builtins.True when Webhook.token
is builtins.None.
hikari.errors.ForbiddenError
If you're not in the guild that owns this webhook or
lack the MANAGE_WEBHOOKS permission.
hikari.errors.NotFoundError
hikari.errors.UnauthorizedError
If you pass a token that's invalid for the target webhook.
hikari.errors.RateLimitTooLongError
Raised in the event that a rate limit occurs that is
longer than max_rate_limit when making a request.
hikari.errors.RateLimitedError
Usually, Hikari will handle and retry on hitting
rate-limits automatically. This includes most bucket-specific
rate-limits and global rate-limits. In some rare edge cases,
however, Discord implements other undocumented rules for
rate-limiting, such as limits per attribute. These cannot be
detected or handled normally by Hikari due to their undocumented
nature, and will trigger this exception if they occur.
hikari.errors.InternalServerError
If an internal error occurs on Discord while handling the request.
"""
token: undefined.UndefinedOr[str] = undefined.UNDEFINED
if use_token:
if self.token is None:
raise ValueError("This webhook's token is unknown, so cannot be used")
token = self.token

elif use_token is undefined.UNDEFINED and self.token:
token = self.token

webhook = await self.app.rest.fetch_webhook(self.id, token=token)
assert isinstance(webhook, IncomingWebhook)
return webhook
def make_avatar_url(
ext: str = 'png',
size: int = 4096,
) -> Optional[files_.URL]: ...

Inherited from: PartialWebhook.make_avatar_url

Generate the avatar URL for this webhook's custom avatar if set.

If no avatar is specified, return None. In this case, you should use default_avatar instead.

## Parameters

ext : str
The extension to use for this URL, defaults to png. Supports png, jpeg, jpg and webp.
size : int
The size to set for the URL, defaults to 4096. Can be any power of two between 16 and 4096. Will be ignored for default avatars.

## Returns

Optional[URL]
The URL of the resource. None if no avatar is set (in this case, use the default_avatar instead).

## Raises

ValueError
If size is not a power of two between 16 and 4096 (inclusive).

#### dataclassPartialWebhook

class PartialWebhook (
*,
app: traits.RESTAware,
id: snowflakes.Snowflake,
type: Union[WebhookType, int],
name: str,
avatar_hash: Optional[str],
application_id: Optional[snowflakes.Snowflake],
): ...

Base class for all webhook implementations.

Method generated by attrs for class PartialWebhook.

Expand source code
Browse git
class PartialWebhook(snowflakes.Unique):
"""Base class for all webhook implementations."""

app: traits.RESTAware = attr.field(
)
"""The client application that models may use for procedures."""

id: snowflakes.Snowflake = attr.field(hash=True, repr=True)
"""The ID of this entity."""

type: typing.Union[WebhookType, int] = attr.field(eq=False, hash=False, repr=True)
"""The type of the webhook."""

name: str = attr.field(eq=False, hash=False, repr=True)
"""The name of the webhook."""

avatar_hash: typing.Optional[str] = attr.field(eq=False, hash=False, repr=False)
"""The avatar hash of the webhook."""

application_id: typing.Optional[snowflakes.Snowflake] = attr.field(eq=False, hash=False, repr=False)
"""The ID of the application that created this webhook."""

def __str__(self) -> str:
return self.name if self.name is not None else f"Unnamed webhook ID {self.id}"

@property
def mention(self) -> str:
"""Return a raw mention string for the given webhook's user.

!!! note
This exists purely for consistency. Webhooks do not receive events
from the gateway, and without some bot backend to support it, will
not be able to detect mentions of their webhook.

Example
-------

py
>>> some_webhook.mention
'<@123456789123456789>'


Returns
-------
builtins.str
The mention string to use.
"""
return f"<@{self.id}>"

@property
def avatar_url(self) -> typing.Optional[files_.URL]:
"""URL for this webhook's avatar, if set.

May be builtins.None if no avatar is set. In this case, you should use
default_avatar_url instead.
"""
return self.make_avatar_url()

@property
def default_avatar_url(self) -> files_.URL:
"""Avatar URL for the user, if they have one set.

May be builtins.None if no custom avatar is set. In this case, you
should use default_avatar_url instead.
"""
return routes.CDN_DEFAULT_USER_AVATAR.compile_to_file(
urls.CDN_URL,
discriminator=0,
file_format="png",
)

def make_avatar_url(self, ext: str = "png", size: int = 4096) -> typing.Optional[files_.URL]:
"""Generate the avatar URL for this webhook's custom avatar if set.

If no avatar is specified, return None. In this case, you should
use default_avatar instead.

Parameters
----------
ext : builtins.str
The extension to use for this URL, defaults to png.
Supports png, jpeg, jpg and webp.
size : builtins.int
The size to set for the URL, defaults to 4096.
Can be any power of two between 16 and 4096.
Will be ignored for default avatars.

Returns
-------
typing.Optional[hikari.files.URL]
The URL of the resource. builtins.None if no avatar is set (in
this case, use the default_avatar instead).

Raises
------
builtins.ValueError
If size is not a power of two between 16 and 4096 (inclusive).
"""
if self.avatar_hash is None:
return None

return routes.CDN_USER_AVATAR.compile_to_file(
urls.CDN_URL,
user_id=self.id,
hash=self.avatar_hash,
size=size,
file_format=ext,
)
##### Subclasses
dataclass ApplicationWebhook

Represents an application webhook object on Discord …

dataclass ChannelFollowerWebhook

Represents a channel follower webhook object on Discord …

dataclass IncomingWebhook

Represents an incoming webhook object on Discord …

##### Method resolution order
dataclass PartialWebhook
That's this class!
abstract class Unique

Mixin for a class that enforces uniqueness by a snowflake ID.

extern class abc.ABC

Helper class that provides a standard way to create an ABC using inheritance.

##### Variables and properties
property app : traits.RESTAware

The client application that models may use for procedures.

property application_id : Optional[snowflakes.Snowflake]

The ID of the application that created this webhook.

property avatar_hash : Optional[str]

The avatar hash of the webhook.

property avatar_url : Optional[files_.URL]

URL for this webhook's avatar, if set.

May be None if no avatar is set. In this case, you should use default_avatar_url instead.

property created_at : datetime.datetime

When the object was created.

property default_avatar_url : files_.URL

Avatar URL for the user, if they have one set.

May be None if no custom avatar is set. In this case, you should use default_avatar_url instead.

property id : snowflakes.Snowflake

The ID of this entity.

property mention : str

Return a raw mention string for the given webhook's user.

Note

This exists purely for consistency. Webhooks do not receive events from the gateway, and without some bot backend to support it, will not be able to detect mentions of their webhook.

## Example

>>> some_webhook.mention
'<@123456789123456789>'


## Returns

str
The mention string to use.
property name : str

The name of the webhook.

property type : Union[WebhookType, int]

The type of the webhook.

##### Methods
def make_avatar_url(
ext: str = 'png',
size: int = 4096,
) -> Optional[files_.URL]: ...

Generate the avatar URL for this webhook's custom avatar if set.

If no avatar is specified, return None. In this case, you should use default_avatar instead.

## Parameters

ext : str
The extension to use for this URL, defaults to png. Supports png, jpeg, jpg and webp.
size : int
The size to set for the URL, defaults to 4096. Can be any power of two between 16 and 4096. Will be ignored for default avatars.

## Returns

Optional[URL]
The URL of the resource. None if no avatar is set (in this case, use the default_avatar instead).

## Raises

ValueError
If size is not a power of two between 16 and 4096 (inclusive).
Expand source code
Browse git
def make_avatar_url(self, ext: str = "png", size: int = 4096) -> typing.Optional[files_.URL]:
"""Generate the avatar URL for this webhook's custom avatar if set.

If no avatar is specified, return None. In this case, you should
use default_avatar instead.

Parameters
----------
ext : builtins.str
The extension to use for this URL, defaults to png.
Supports png, jpeg, jpg and webp.
size : builtins.int
The size to set for the URL, defaults to 4096.
Can be any power of two between 16 and 4096.
Will be ignored for default avatars.

Returns
-------
typing.Optional[hikari.files.URL]
The URL of the resource. builtins.None if no avatar is set (in
this case, use the default_avatar instead).

Raises
------
builtins.ValueError
If size is not a power of two between 16 and 4096 (inclusive).
"""
if self.avatar_hash is None:
return None

return routes.CDN_USER_AVATAR.compile_to_file(
urls.CDN_URL,
user_id=self.id,
hash=self.avatar_hash,
size=size,
file_format=ext,
)

#### enumWebhookType

class WebhookType (
value: Any,
): ...

Types of webhook.

Expand source code
Browse git
class WebhookType(int, enums.Enum):
"""Types of webhook."""

INCOMING = 1
"""Incoming webhook."""

CHANNEL_FOLLOWER = 2
"""Channel Follower webhook."""

APPLICATION = 3
"""Application webhook (from the interactions flow)."""
##### Method resolution order
enum WebhookType
That's this class!
extern class int

int([x]) -> integer int(x, base=10) -> integer …

enum Enum

Clone of Python's enum.Enum implementation …

##### Variables and properties
property name : str

Return the name of the enum member as a str.

property value

Return the value of the enum member.

const APPLICATION = 3

Application webhook (from the interactions flow).

const CHANNEL_FOLLOWER = 2

Channel Follower webhook.

const INCOMING = 1`

Incoming webhook.