hikari.webhooks

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

ApplicationWebhook

Bases: PartialWebhook

Represents an application webhook object on Discord.

This is from the interactions flow.

app class-attribute instance-attribute

app: RESTAware = field(
    repr=False, eq=False, hash=False, metadata={SKIP_DEEP_COPY: True}
)

Client application that models may use for procedures.

application_id class-attribute instance-attribute

application_id: Snowflake = field()

The ID of the application that created this webhook.

avatar_hash class-attribute instance-attribute

avatar_hash: Optional[str] = field(eq=False, hash=False, repr=False)

The avatar hash of the webhook.

avatar_url property

avatar_url: Optional[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.

created_at property

created_at: datetime

When the object was created.

default_avatar_url property

default_avatar_url: URL

Default avatar URL for the user.

id class-attribute instance-attribute

id: Snowflake = field(hash=True, repr=True)

The ID of this entity.

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

Examples:

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

name class-attribute instance-attribute

name: str = field(eq=False, hash=False, repr=True)

The name of the webhook.

type class-attribute instance-attribute

type: Union[WebhookType, int] = field(eq=False, hash=False, repr=True)

The type of the webhook.

make_avatar_url

make_avatar_url(ext: str = 'png', size: int = 4096) -> Optional[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.

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

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

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

ChannelFollowerWebhook

Bases: PartialWebhook

Represents a channel follower webhook object on Discord.

app class-attribute instance-attribute

app: RESTAware = field(
    repr=False, eq=False, hash=False, metadata={SKIP_DEEP_COPY: True}
)

Client application that models may use for procedures.

application_id class-attribute instance-attribute

application_id: Optional[Snowflake] = field(eq=False, hash=False, repr=False)

The ID of the application that created this webhook.

author class-attribute instance-attribute

author: Optional[User] = field(eq=False, hash=False, repr=True)

The user that created the webhook.

Note

This will be None when received within an audit log.

avatar_hash class-attribute instance-attribute

avatar_hash: Optional[str] = field(eq=False, hash=False, repr=False)

The avatar hash of the webhook.

avatar_url property

avatar_url: Optional[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.

channel_id class-attribute instance-attribute

channel_id: Snowflake = field(eq=False, hash=False, repr=True)

The channel ID this webhook is for.

created_at property

created_at: datetime

When the object was created.

default_avatar_url property

default_avatar_url: URL

Default avatar URL for the user.

guild_id class-attribute instance-attribute

guild_id: Snowflake = field(eq=False, hash=False, repr=True)

The guild ID of the webhook.

id class-attribute instance-attribute

id: Snowflake = field(hash=True, repr=True)

The ID of this entity.

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

Examples:

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

name class-attribute instance-attribute

name: str = field(eq=False, hash=False, repr=True)

The name of the webhook.

source_channel class-attribute instance-attribute

source_channel: Optional[PartialChannel] = field(
    eq=False, hash=False, repr=True
)

The partial object of the channel this webhook is following.

This will be None when the user that followed the channel is no longer in the source guild or has lost access to the source channel.

source_guild class-attribute instance-attribute

source_guild: Optional[PartialGuild] = field(eq=False, hash=False, repr=True)

The partial object of the guild this webhook is following.

This will be None when the user that followed the channel is no longer in the source guild or has lost access to the source channel.

type class-attribute instance-attribute

type: Union[WebhookType, int] = field(eq=False, hash=False, repr=True)

The type of the webhook.

delete async

delete() -> None

Delete this webhook.

RAISES	DESCRIPTION
NotFoundError	If this webhook is not found.
ForbiddenError	If you either lack the hikari.permissions.Permissions.MANAGE_WEBHOOKS permission or are not a member of the guild this webhook belongs to.

edit async

edit(
    *,
    name: UndefinedOr[str] = undefined.UNDEFINED,
    avatar: UndefinedNoneOr[Resource[AsyncReader]] = undefined.UNDEFINED,
    channel: UndefinedOr[SnowflakeishOr[WebhookChannelT]] = undefined.UNDEFINED,
    reason: UndefinedOr[str] = undefined.UNDEFINED
) -> ChannelFollowerWebhook

Edit this webhook.

PARAMETER	DESCRIPTION
name	If provided, the new name string. TYPE: UndefinedOr[str]
avatar	If provided, the new avatar image. If None, then it is removed. If not specified, nothing is changed. TYPE: UndefinedOr[Resourceish]
channel	If provided, the object or ID of the new channel the given webhook should be moved to. TYPE: UndefinedOr[SnowflakeishOr[WebhookChannelT]]
reason	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. TYPE: UndefinedOr[str]

RETURNS	DESCRIPTION
ChannelFollowerWebhook	The updated webhook object.

RAISES	DESCRIPTION
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	If either the webhook or the channel are not found.
ForbiddenError	If you either lack the hikari.permissions.Permissions.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.
InternalServerError	If an internal error occurs on Discord while handling the request.

fetch_channel async

fetch_channel() -> WebhookChannelT

Fetch the channel this webhook is for.

RETURNS	DESCRIPTION
WebhookChannelT	The object of the channel this webhook targets.

RAISES	DESCRIPTION
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.
InternalServerError	If an internal error occurs on Discord while handling the request.

fetch_self async

fetch_self() -> ChannelFollowerWebhook

Fetch this webhook.

RETURNS	DESCRIPTION
ChannelFollowerWebhook	The requested webhook object.

RAISES	DESCRIPTION
ForbiddenError	If you're not in the guild that owns this webhook or lack the hikari.permissions.Permissions.MANAGE_WEBHOOKS permission.
NotFoundError	If the webhook is not found.
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.
InternalServerError	If an internal error occurs on Discord while handling the request.

make_avatar_url

make_avatar_url(ext: str = 'png', size: int = 4096) -> Optional[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.

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

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

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

ExecutableWebhook

Bases: ABC

An abstract class with logic for executing entities as webhooks.

app abstractmethod property

app: RESTAware

Client application that models may use for procedures.

token abstractmethod property

token: Optional[str]

Webhook's token.

Note

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

webhook_id abstractmethod property

webhook_id: Snowflake

ID used to execute this entity as a webhook.

delete_message async

delete_message(message: SnowflakeishOr[Message]) -> None

Delete a given message in a given channel.

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

RAISES	DESCRIPTION
ValueError	If token is not available.
UnauthorizedError	If you are unauthorized to make the request (invalid/missing token).
NotFoundError	If the webhook or the message are not found.
RateLimitTooLongError	Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
InternalServerError	If an internal error occurs on Discord while handling the request.

edit_message async

edit_message(
    message: SnowflakeishOr[Message],
    content: UndefinedNoneOr[Any] = undefined.UNDEFINED,
    *,
    attachment: UndefinedNoneOr[
        Union[Resourceish, Attachment]
    ] = undefined.UNDEFINED,
    attachments: UndefinedNoneOr[
        Sequence[Union[Resourceish, Attachment]]
    ] = undefined.UNDEFINED,
    component: UndefinedNoneOr[ComponentBuilder] = undefined.UNDEFINED,
    components: UndefinedNoneOr[
        Sequence[ComponentBuilder]
    ] = undefined.UNDEFINED,
    embed: UndefinedNoneOr[Embed] = undefined.UNDEFINED,
    embeds: UndefinedNoneOr[Sequence[Embed]] = undefined.UNDEFINED,
    mentions_everyone: UndefinedOr[bool] = undefined.UNDEFINED,
    user_mentions: UndefinedOr[
        Union[SnowflakeishSequence[PartialUser], bool]
    ] = undefined.UNDEFINED,
    role_mentions: UndefinedOr[
        Union[SnowflakeishSequence[PartialRole], bool]
    ] = undefined.UNDEFINED
) -> Message

Edit a message sent by a webhook.

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 text content, mentions_everyone, mentions_reply, user_mentions, and role_mentions will default to False as the message will be re-parsed for mentions. This will also occur if only one of the four are specified

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

PARAMETER	DESCRIPTION
message	The message to delete. This may be the object or the ID of an existing message. TYPE: SnowflakeishOr[PartialMessage]
content	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 str. If this is a hikari.embeds.Embed and no embed nor 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 nor attachments kwargs are provided. TYPE: UndefinedNoneOr[Any] DEFAULT: UNDEFINED

PARAMETER	DESCRIPTION
attachment	If provided, the attachment to set on the message. If hikari.undefined.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. TYPE: UndefinedNoneOr[Union[Resourceish, Attachment]]
attachments	If provided, the attachments to set on the message. If hikari.undefined.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. TYPE: UndefinedNoneOr[Sequence[Union[Resourceish, Attachment]]]
component	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. TYPE: UndefinedNoneOr[ComponentBuilder]
components	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. TYPE: UndefinedNoneOr[Sequence[ComponentBuilder]]
embed	If provided, the embed to set on the message. If hikari.undefined.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. TYPE: UndefinedNoneOr[Embed]
embeds	If provided, the embeds to set on the message. If hikari.undefined.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. TYPE: UndefinedNoneOr[Sequence[Embed]]
mentions_everyone	If provided, sanitation for @everyone mentions. If hikari.undefined.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. TYPE: UndefinedOr[bool]
user_mentions	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 hikari.snowflakes.Snowflake, or hikari.users.PartialUser derivatives to enforce mentioning specific users. TYPE: UndefinedOr[Union[SnowflakeishSequence[PartialUser], bool]]
role_mentions	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 hikari.snowflakes.Snowflake, or hikari.guilds.PartialRole derivatives to enforce mentioning specific roles. TYPE: UndefinedOr[Union[SnowflakeishSequence[PartialRole], bool]]

RETURNS	DESCRIPTION
Message	The edited message.

RAISES	DESCRIPTION
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	If the webhook or the message are not found.
RateLimitTooLongError	Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
InternalServerError	If an internal error occurs on Discord while handling the request.

execute async

execute(
    content: UndefinedOr[Any] = undefined.UNDEFINED,
    *,
    username: UndefinedOr[str] = undefined.UNDEFINED,
    avatar_url: Union[UndefinedType, str, URL] = undefined.UNDEFINED,
    tts: UndefinedOr[bool] = undefined.UNDEFINED,
    attachment: UndefinedOr[Resourceish] = undefined.UNDEFINED,
    attachments: UndefinedOr[Sequence[Resourceish]] = undefined.UNDEFINED,
    component: UndefinedOr[ComponentBuilder] = undefined.UNDEFINED,
    components: UndefinedOr[Sequence[ComponentBuilder]] = undefined.UNDEFINED,
    embed: UndefinedOr[Embed] = undefined.UNDEFINED,
    embeds: UndefinedOr[Sequence[Embed]] = undefined.UNDEFINED,
    mentions_everyone: UndefinedOr[bool] = undefined.UNDEFINED,
    user_mentions: UndefinedOr[
        Union[SnowflakeishSequence[PartialUser], bool]
    ] = undefined.UNDEFINED,
    role_mentions: UndefinedOr[
        Union[SnowflakeishSequence[PartialRole], bool]
    ] = undefined.UNDEFINED,
    flags: Union[UndefinedType, int, MessageFlag] = undefined.UNDEFINED
) -> Message

Execute the webhook to create a message.

Warning

At the time of writing, username and avatar_url are ignored for interaction webhooks.

Additionally, hikari.messages.MessageFlag.SUPPRESS_EMBEDS, hikari.messages.MessageFlag.SUPPRESS_NOTIFICATIONS and hikari.messages.MessageFlag.EPHEMERAL are the only flags that can be set, with hikari.messages.MessageFlag.EPHEMERAL being limited to interaction webhooks.

PARAMETER

DESCRIPTION

content

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 str. If this is a hikari.embeds.Embed and no embed and no embeds kwargs are 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. TYPE: UndefinedOr[Any] DEFAULT: UNDEFINED

PARAMETER	DESCRIPTION
username	If provided, the username to override the webhook's username for this request. TYPE: UndefinedOr[str]
avatar_url	If provided, the url of an image to override the webhook's avatar with for this request. TYPE: Union[UndefinedType, URL, str]
tts	If provided, whether the message will be sent as a TTS message. TYPE: UndefinedOr[bool]
attachment	If provided, the message attachment. This can be a resource, or string of a path on your computer or a URL. TYPE: UndefinedOr[Resourceish]
attachments	If provided, the message attachments. These can be resources, or strings consisting of paths on your computer or URLs. TYPE: UndefinedOr[Sequence[Resourceish]]
component	If provided, builder object of the component to include in this message. TYPE: UndefinedOr[ComponentBuilder]
components	If provided, a sequence of the component builder objects to include in this message. TYPE: UndefinedOr[Sequence[ComponentBuilder]]
embed	If provided, the message embed. TYPE: UndefinedOr[Embed]
embeds	If provided, the message embeds. TYPE: UndefinedOr[Sequence[Embed]]
mentions_everyone	If provided, whether the message should parse @everyone/@here mentions. TYPE: UndefinedOr[bool]
user_mentions	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 hikari.snowflakes.Snowflake, or hikari.users.PartialUser derivatives to enforce mentioning specific users. TYPE: UndefinedOr[Union[SnowflakeishSequence[PartialUser], bool]]
role_mentions	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 hikari.snowflakes.Snowflake, or hikari.guilds.PartialRole derivatives to enforce mentioning specific roles. TYPE: UndefinedOr[Union[SnowflakeishSequence[PartialRole], bool]]
flags	The flags to set for this webhook message. TYPE: Union[UndefinedType, int, MessageFlag]

RETURNS	DESCRIPTION
Message	The created message object.

RAISES	DESCRIPTION
NotFoundError	If the current webhook is not found.
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 token is not available.
TypeError	If both attachment and attachments, component and components or embed and embeds are specified.

fetch_message async

fetch_message(message: SnowflakeishOr[Message]) -> Message

Fetch an old message sent by the webhook.

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

RETURNS	DESCRIPTION
Message	The requested message.

RAISES	DESCRIPTION
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.
InternalServerError	If an internal error occurs on Discord while handling the request.

IncomingWebhook

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

app class-attribute instance-attribute

app: RESTAware = field(
    repr=False, eq=False, hash=False, metadata={SKIP_DEEP_COPY: True}
)

Client application that models may use for procedures.

application_id class-attribute instance-attribute

application_id: Optional[Snowflake] = field(eq=False, hash=False, repr=False)

The ID of the application that created this webhook.

author class-attribute instance-attribute

author: Optional[User] = field(eq=False, hash=False, repr=True)

The user that created the webhook.

Note

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

avatar_hash class-attribute instance-attribute

avatar_hash: Optional[str] = field(eq=False, hash=False, repr=False)

The avatar hash of the webhook.

avatar_url property

avatar_url: Optional[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.

channel_id class-attribute instance-attribute

channel_id: Snowflake = field(eq=False, hash=False, repr=True)

The channel ID this webhook is for.

created_at property

created_at: datetime

When the object was created.

default_avatar_url property

default_avatar_url: URL

Default avatar URL for the user.

guild_id class-attribute instance-attribute

guild_id: Snowflake = field(eq=False, hash=False, repr=True)

The guild ID of the webhook.

id class-attribute instance-attribute

id: Snowflake = field(hash=True, repr=True)

The ID of this entity.

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

Examples:

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

name class-attribute instance-attribute

name: str = field(eq=False, hash=False, repr=True)

The name of the webhook.

token class-attribute instance-attribute

token: Optional[str] = field(eq=False, hash=False, repr=False)

The token for the webhook.

Note

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

type class-attribute instance-attribute

type: Union[WebhookType, int] = field(eq=False, hash=False, repr=True)

The type of the webhook.

webhook_id property

webhook_id: Snowflake

ID used to execute this entity as a webhook.

delete async

delete(*, use_token: UndefinedOr[bool] = undefined.UNDEFINED) -> None

Delete this webhook.

PARAMETER	DESCRIPTION
use_token	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. TYPE: UndefinedOr[bool]

RAISES	DESCRIPTION
NotFoundError	If this webhook is not found.
ForbiddenError	If you either lack the hikari.permissions.Permissions.MANAGE_WEBHOOKS permission or are not a member of the guild this webhook belongs to.
ValueError	If use_token is passed as True when hikari.webhooks.IncomingWebhook.token is None.

delete_message async

delete_message(message: SnowflakeishOr[Message]) -> None

Delete a given message in a given channel.

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

RAISES	DESCRIPTION
ValueError	If token is not available.
UnauthorizedError	If you are unauthorized to make the request (invalid/missing token).
NotFoundError	If the webhook or the message are not found.
RateLimitTooLongError	Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
InternalServerError	If an internal error occurs on Discord while handling the request.

edit async

edit(
    *,
    name: UndefinedOr[str] = undefined.UNDEFINED,
    avatar: UndefinedNoneOr[Resource[AsyncReader]] = undefined.UNDEFINED,
    channel: UndefinedOr[SnowflakeishOr[WebhookChannelT]] = undefined.UNDEFINED,
    reason: UndefinedOr[str] = undefined.UNDEFINED,
    use_token: UndefinedOr[bool] = undefined.UNDEFINED
) -> IncomingWebhook

Edit this webhook.

PARAMETER	DESCRIPTION
name	If provided, the new name string. TYPE: UndefinedOr[str]
avatar	If provided, the new avatar image. If None, then it is removed. If not specified, nothing is changed. TYPE: UndefinedOr[Resourceish]
channel	If provided, the object or ID of the new channel the given webhook should be moved to. TYPE: UndefinedOr[SnowflakeishOr[WebhookChannelT]]
reason	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. TYPE: UndefinedOr[str]
use_token	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. TYPE: UndefinedOr[bool]

RETURNS	DESCRIPTION
IncomingWebhook	The updated webhook object.

RAISES	DESCRIPTION
ValueError	If use_token is passed as True when hikari.webhooks.IncomingWebhook.token is None.
BadRequestError	If any invalid snowflake IDs are passed; a snowflake may be invalid due to it being outside the range of a 64-bit integer.
NotFoundError	If either the webhook or the channel are not found.
ForbiddenError	If you either lack the hikari.permissions.Permissions.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.
InternalServerError	If an internal error occurs on Discord while handling the request.

edit_message async

edit_message(
    message: SnowflakeishOr[Message],
    content: UndefinedNoneOr[Any] = undefined.UNDEFINED,
    *,
    attachment: UndefinedNoneOr[
        Union[Resourceish, Attachment]
    ] = undefined.UNDEFINED,
    attachments: UndefinedNoneOr[
        Sequence[Union[Resourceish, Attachment]]
    ] = undefined.UNDEFINED,
    component: UndefinedNoneOr[ComponentBuilder] = undefined.UNDEFINED,
    components: UndefinedNoneOr[
        Sequence[ComponentBuilder]
    ] = undefined.UNDEFINED,
    embed: UndefinedNoneOr[Embed] = undefined.UNDEFINED,
    embeds: UndefinedNoneOr[Sequence[Embed]] = undefined.UNDEFINED,
    mentions_everyone: UndefinedOr[bool] = undefined.UNDEFINED,
    user_mentions: UndefinedOr[
        Union[SnowflakeishSequence[PartialUser], bool]
    ] = undefined.UNDEFINED,
    role_mentions: UndefinedOr[
        Union[SnowflakeishSequence[PartialRole], bool]
    ] = undefined.UNDEFINED
) -> Message

Edit a message sent by a webhook.

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 text content, mentions_everyone, mentions_reply, user_mentions, and role_mentions will default to False as the message will be re-parsed for mentions. This will also occur if only one of the four are specified

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

PARAMETER	DESCRIPTION
message	The message to delete. This may be the object or the ID of an existing message. TYPE: SnowflakeishOr[PartialMessage]
content	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 str. If this is a hikari.embeds.Embed and no embed nor 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 nor attachments kwargs are provided. TYPE: UndefinedNoneOr[Any] DEFAULT: UNDEFINED

PARAMETER	DESCRIPTION
attachment	If provided, the attachment to set on the message. If hikari.undefined.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. TYPE: UndefinedNoneOr[Union[Resourceish, Attachment]]
attachments	If provided, the attachments to set on the message. If hikari.undefined.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. TYPE: UndefinedNoneOr[Sequence[Union[Resourceish, Attachment]]]
component	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. TYPE: UndefinedNoneOr[ComponentBuilder]
components	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. TYPE: UndefinedNoneOr[Sequence[ComponentBuilder]]
embed	If provided, the embed to set on the message. If hikari.undefined.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. TYPE: UndefinedNoneOr[Embed]
embeds	If provided, the embeds to set on the message. If hikari.undefined.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. TYPE: UndefinedNoneOr[Sequence[Embed]]
mentions_everyone	If provided, sanitation for @everyone mentions. If hikari.undefined.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. TYPE: UndefinedOr[bool]
user_mentions	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 hikari.snowflakes.Snowflake, or hikari.users.PartialUser derivatives to enforce mentioning specific users. TYPE: UndefinedOr[Union[SnowflakeishSequence[PartialUser], bool]]
role_mentions	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 hikari.snowflakes.Snowflake, or hikari.guilds.PartialRole derivatives to enforce mentioning specific roles. TYPE: UndefinedOr[Union[SnowflakeishSequence[PartialRole], bool]]

RETURNS	DESCRIPTION
Message	The edited message.

RAISES	DESCRIPTION
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	If the webhook or the message are not found.
RateLimitTooLongError	Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
InternalServerError	If an internal error occurs on Discord while handling the request.

execute async

execute(
    content: UndefinedOr[Any] = undefined.UNDEFINED,
    *,
    username: UndefinedOr[str] = undefined.UNDEFINED,
    avatar_url: Union[UndefinedType, str, URL] = undefined.UNDEFINED,
    tts: UndefinedOr[bool] = undefined.UNDEFINED,
    attachment: UndefinedOr[Resourceish] = undefined.UNDEFINED,
    attachments: UndefinedOr[Sequence[Resourceish]] = undefined.UNDEFINED,
    component: UndefinedOr[ComponentBuilder] = undefined.UNDEFINED,
    components: UndefinedOr[Sequence[ComponentBuilder]] = undefined.UNDEFINED,
    embed: UndefinedOr[Embed] = undefined.UNDEFINED,
    embeds: UndefinedOr[Sequence[Embed]] = undefined.UNDEFINED,
    mentions_everyone: UndefinedOr[bool] = undefined.UNDEFINED,
    user_mentions: UndefinedOr[
        Union[SnowflakeishSequence[PartialUser], bool]
    ] = undefined.UNDEFINED,
    role_mentions: UndefinedOr[
        Union[SnowflakeishSequence[PartialRole], bool]
    ] = undefined.UNDEFINED,
    flags: Union[UndefinedType, int, MessageFlag] = undefined.UNDEFINED
) -> Message

Execute the webhook to create a message.

Warning

At the time of writing, username and avatar_url are ignored for interaction webhooks.

Additionally, hikari.messages.MessageFlag.SUPPRESS_EMBEDS, hikari.messages.MessageFlag.SUPPRESS_NOTIFICATIONS and hikari.messages.MessageFlag.EPHEMERAL are the only flags that can be set, with hikari.messages.MessageFlag.EPHEMERAL being limited to interaction webhooks.

PARAMETER

DESCRIPTION

content

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 str. If this is a hikari.embeds.Embed and no embed and no embeds kwargs are 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. TYPE: UndefinedOr[Any] DEFAULT: UNDEFINED

PARAMETER	DESCRIPTION
username	If provided, the username to override the webhook's username for this request. TYPE: UndefinedOr[str]
avatar_url	If provided, the url of an image to override the webhook's avatar with for this request. TYPE: Union[UndefinedType, URL, str]
tts	If provided, whether the message will be sent as a TTS message. TYPE: UndefinedOr[bool]
attachment	If provided, the message attachment. This can be a resource, or string of a path on your computer or a URL. TYPE: UndefinedOr[Resourceish]
attachments	If provided, the message attachments. These can be resources, or strings consisting of paths on your computer or URLs. TYPE: UndefinedOr[Sequence[Resourceish]]
component	If provided, builder object of the component to include in this message. TYPE: UndefinedOr[ComponentBuilder]
components	If provided, a sequence of the component builder objects to include in this message. TYPE: UndefinedOr[Sequence[ComponentBuilder]]
embed	If provided, the message embed. TYPE: UndefinedOr[Embed]
embeds	If provided, the message embeds. TYPE: UndefinedOr[Sequence[Embed]]
mentions_everyone	If provided, whether the message should parse @everyone/@here mentions. TYPE: UndefinedOr[bool]
user_mentions	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 hikari.snowflakes.Snowflake, or hikari.users.PartialUser derivatives to enforce mentioning specific users. TYPE: UndefinedOr[Union[SnowflakeishSequence[PartialUser], bool]]
role_mentions	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 hikari.snowflakes.Snowflake, or hikari.guilds.PartialRole derivatives to enforce mentioning specific roles. TYPE: UndefinedOr[Union[SnowflakeishSequence[PartialRole], bool]]
flags	The flags to set for this webhook message. TYPE: Union[UndefinedType, int, MessageFlag]

RETURNS	DESCRIPTION
Message	The created message object.

RAISES	DESCRIPTION
NotFoundError	If the current webhook is not found.
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 token is not available.
TypeError	If both attachment and attachments, component and components or embed and embeds are specified.

fetch_channel async

fetch_channel() -> WebhookChannelT

Fetch the channel this webhook is for.

RETURNS	DESCRIPTION
WebhookChannelT	The object of the channel this webhook targets.

RAISES	DESCRIPTION
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.
InternalServerError	If an internal error occurs on Discord while handling the request.

fetch_message async

fetch_message(message: SnowflakeishOr[Message]) -> Message

Fetch an old message sent by the webhook.

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

RETURNS	DESCRIPTION
Message	The requested message.

RAISES	DESCRIPTION
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.
InternalServerError	If an internal error occurs on Discord while handling the request.

fetch_self async

fetch_self(
    *, use_token: UndefinedOr[bool] = undefined.UNDEFINED
) -> IncomingWebhook

Fetch this webhook.

PARAMETER	DESCRIPTION
use_token	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. TYPE: UndefinedOr[bool]

RETURNS	DESCRIPTION
IncomingWebhook	The requested webhook object.

RAISES	DESCRIPTION
ValueError	If use_token is passed as True when hikari.webhooks.IncomingWebhook.token is None.
ForbiddenError	If you're not in the guild that owns this webhook or lack the hikari.permissions.Permissions.MANAGE_WEBHOOKS permission.
NotFoundError	If the webhook is not found.
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.
InternalServerError	If an internal error occurs on Discord while handling the request.

make_avatar_url

make_avatar_url(ext: str = 'png', size: int = 4096) -> Optional[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.

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

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

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

PartialWebhook

Bases: Unique

Base class for all webhook implementations.

app class-attribute instance-attribute

app: RESTAware = field(
    repr=False, eq=False, hash=False, metadata={SKIP_DEEP_COPY: True}
)

Client application that models may use for procedures.

application_id class-attribute instance-attribute

application_id: Optional[Snowflake] = field(eq=False, hash=False, repr=False)

The ID of the application that created this webhook.

avatar_hash class-attribute instance-attribute

avatar_hash: Optional[str] = field(eq=False, hash=False, repr=False)

The avatar hash of the webhook.

avatar_url property

avatar_url: Optional[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.

created_at property

created_at: datetime

When the object was created.

default_avatar_url property

default_avatar_url: URL

Default avatar URL for the user.

id class-attribute instance-attribute

id: Snowflake = field(hash=True, repr=True)

The ID of this entity.

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

Examples:

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

name class-attribute instance-attribute

name: str = field(eq=False, hash=False, repr=True)

The name of the webhook.

type class-attribute instance-attribute

type: Union[WebhookType, int] = field(eq=False, hash=False, repr=True)

The type of the webhook.

make_avatar_url

make_avatar_url(ext: str = 'png', size: int = 4096) -> Optional[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.

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

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

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

WebhookType

Bases: int, Enum

Types of webhook.

APPLICATION class-attribute instance-attribute

APPLICATION = 3

Application webhook (from the interactions flow).

CHANNEL_FOLLOWER class-attribute instance-attribute

CHANNEL_FOLLOWER = 2

Channel Follower webhook.

INCOMING class-attribute instance-attribute

INCOMING = 1

Incoming webhook.

name property

name: str

Return the name of the enum member as a str.

value property

value

Return the value of the enum member.