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.
ChannelFollowerWebhook #
Bases: PartialWebhook
Represents a channel follower webhook object on Discord.
author class-attribute
instance-attribute
#
The user that created the webhook.
Note
This will be None
when received within an audit log.
channel_id class-attribute
instance-attribute
#
The channel ID this webhook is for.
guild_id class-attribute
instance-attribute
#
The guild ID 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.
delete async
#
delete() -> None
Delete this webhook.
RAISES | DESCRIPTION |
---|---|
NotFoundError | If this webhook is not found. |
ForbiddenError | If you either lack the |
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: |
avatar | If provided, the new avatar image. If TYPE: |
channel | If provided, the object or ID of the new channel the given webhook should be moved to. TYPE: |
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: |
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 |
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 |
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 |
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 |
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 |
InternalServerError | If an internal error occurs on Discord while handling the request. |
ExecutableWebhook #
Bases: ABC
An abstract class with logic for executing entities as webhooks.
token abstractmethod
property
#
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: |
RAISES | DESCRIPTION |
---|---|
ValueError | If |
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 |
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: |
content | If provided, the message contents. If If this is a Likewise, if this is a TYPE: |
attachment | If provided, the attachment to set on the message. If TYPE: |
attachments | If provided, the attachments to set on the message. If TYPE: |
component | If provided, builder object of the component to set for this message. This component will replace any previously set components and passing TYPE: |
components | If provided, a sequence of the component builder objects set for this message. These components will replace any previously set components and passing TYPE: |
embed | If provided, the embed to set on the message. If TYPE: |
embeds | If provided, the embeds to set on the message. If TYPE: |
mentions_everyone | If provided, sanitation for TYPE: |
user_mentions | If provided, and TYPE: |
role_mentions | If provided, and TYPE: |
RETURNS | DESCRIPTION |
---|---|
Message | The edited message. |
RAISES | DESCRIPTION |
---|---|
ValueError | If more than 100 unique objects/entities are passed for |
TypeError | If both |
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 |
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 If this is a Likewise, if this is a TYPE: |
username | If provided, the username to override the webhook's username for this request. TYPE: |
avatar_url | If provided, the url of an image to override the webhook's avatar with for this request. TYPE: |
tts | If provided, whether the message will be sent as a TTS message. TYPE: |
attachment | If provided, the message attachment. This can be a resource, or string of a path on your computer or a URL. TYPE: |
attachments | If provided, the message attachments. These can be resources, or strings consisting of paths on your computer or URLs. TYPE: |
component | If provided, builder object of the component to include in this message. TYPE: |
components | If provided, a sequence of the component builder objects to include in this message. TYPE: |
embed | If provided, the message embed. TYPE: |
embeds | If provided, the message embeds. TYPE: |
mentions_everyone | If provided, whether the message should parse @everyone/@here mentions. TYPE: |
user_mentions | If provided, and TYPE: |
role_mentions | If provided, and TYPE: |
flags | The flags to set for this webhook message. TYPE: |
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 |
UnauthorizedError | If you pass a token that's invalid for the target webhook. |
ValueError | If |
TypeError | If both |
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: |
RETURNS | DESCRIPTION |
---|---|
Message | The requested message. |
RAISES | DESCRIPTION |
---|---|
ValueError | If |
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 |
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.
author class-attribute
instance-attribute
#
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.
channel_id class-attribute
instance-attribute
#
The channel ID this webhook is for.
guild_id class-attribute
instance-attribute
#
The guild ID of the webhook.
token class-attribute
instance-attribute
#
The token for the webhook.
Note
This is only available for incoming webhooks that are created in the channel settings.
delete async
#
delete(*, use_token: UndefinedOr[bool] = undefined.UNDEFINED) -> None
Delete this webhook.
PARAMETER | DESCRIPTION |
---|---|
use_token | If set to TYPE: |
RAISES | DESCRIPTION |
---|---|
NotFoundError | If this webhook is not found. |
ForbiddenError | If you either lack the |
ValueError | If |
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: |
avatar | If provided, the new avatar image. If TYPE: |
channel | If provided, the object or ID of the new channel the given webhook should be moved to. TYPE: |
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: |
use_token | If set to TYPE: |
RETURNS | DESCRIPTION |
---|---|
IncomingWebhook | The updated webhook object. |
RAISES | DESCRIPTION |
---|---|
ValueError | If |
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 |
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 |
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 |
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 TYPE: |
RETURNS | DESCRIPTION |
---|---|
IncomingWebhook | The requested webhook object. |
RAISES | DESCRIPTION |
---|---|
ValueError | If |
ForbiddenError | If you're not in the guild that owns this webhook or lack the |
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 |
InternalServerError | If an internal error occurs on Discord while handling the request. |
PartialWebhook #
Bases: Unique
Base class for all webhook implementations.
app class-attribute
instance-attribute
#
Client application that models may use for procedures.
application_id class-attribute
instance-attribute
#
The ID of the application that created this webhook.
avatar_hash class-attribute
instance-attribute
#
The avatar hash of the webhook.
avatar_url property
#
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.
id class-attribute
instance-attribute
#
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
#
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 #
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 TYPE: |
size | The size to set for the URL. Can be any power of two between TYPE: |
RETURNS | DESCRIPTION |
---|---|
Optional[URL] | The URL of the resource. |
RAISES | DESCRIPTION |
---|---|
ValueError | If |