hikari.api.special_endpoints#

Special additional endpoints used by the REST API.

Module Contents#

class hikari.api.special_endpoints.AutocompleteChoiceBuilder[source]#

Bases: abc.ABC

Interface of an autocomplete choice used to respond to interactions.

abstract property name: str[source]#

The choice’s name.

abstract property value: int | str | float[source]#

The choice’s value.

abstract build()[source]#

Build a JSON object from this builder.

Returns:
typing.MutableMapping[str, typing.Any]

The built json object representation of this builder.

abstract set_name(name, /)[source]#

Set this choice’s name.

Returns:
AutocompleteChoiceBuilder

The autocomplete choice builder.

abstract set_value(value, /)[source]#

Set this choice’s value.

Returns:
AutocompleteChoiceBuilder

The autocomplete choice builder.

class hikari.api.special_endpoints.ButtonBuilder[source]#

Bases: ComponentBuilder, abc.ABC

Builder class for a message button component.

abstract property emoji: hikari.snowflakes.Snowflakeish | hikari.emojis.Emoji | str | hikari.undefined.UndefinedType[source]#

Emoji which should appear on this button.

abstract property is_disabled: bool[source]#

Whether the button should be marked as disabled.

abstract property label: hikari.undefined.UndefinedOr[str][source]#

Text label which should appear on this button.

Note

The text label to that should appear on this button. This may be up to 80 characters long.

abstract property style: hikari.components.ButtonStyle | int[source]#

Button’s style.

abstract property type: Literal[hikari.components.ComponentType.BUTTON][source]#

Type of component this builder represents.

abstract set_emoji(emoji, /)[source]#

Set the emoji to display on this button.

Parameters:
emojityping.Union[hikari.snowflakes.Snowflakeish, hikari.emojis.Emoji, str, hikari.undefined.UndefinedType]

Object, ID or raw string of the emoji which should be displayed on this button.

Returns:
ButtonBuilder

The builder object to enable chained calls.

abstract set_is_disabled(state, /)[source]#

Set whether this button should be disabled.

Parameters:
statebool

Whether this button should be disabled.

Returns:
ButtonBuilder

The builder object to enable chained calls.

abstract set_label(label, /)[source]#

Set the text label which should be displayed on this button.

Parameters:
labelhikari.undefined.UndefinedOr[str]

The text label to show on this button.

This may be up to 80 characters long.

Returns:
ButtonBuilder

The builder object to enable chained calls.

class hikari.api.special_endpoints.ChannelSelectMenuBuilder[source]#

Bases: SelectMenuBuilder, abc.ABC

Builder class for a channel select menu.

abstract property channel_types: Sequence[hikari.channels.ChannelType][source]#

The channel types that can be selected in this menu.

abstract set_channel_types(value, /)[source]#

Set the valid channel types for this menu.

Parameters:
valuetyping.Sequence[hikari.channels.ChannelType]

The valid channel types for this menu.

Returns:
SelectMenuBuilder

The builder object to enable chained calls.

class hikari.api.special_endpoints.CommandBuilder[source]#

Bases: abc.ABC

Interface of a command builder used when bulk creating commands over REST.

abstract property default_member_permissions: hikari.undefined.UndefinedType | hikari.permissions.Permissions | int[source]#

Member permissions necessary to utilize this command by default.

If 0, then it will be available for all members. Note that this doesn’t affect administrators of the guild and overwrites.

abstract property id: hikari.undefined.UndefinedOr[hikari.snowflakes.Snowflake][source]#

ID of this command.

abstract property is_dm_enabled: hikari.undefined.UndefinedOr[bool][source]#

Whether this command is enabled in DMs with the bot.

Only applicable to globally-scoped commands.

abstract property is_nsfw: hikari.undefined.UndefinedOr[bool][source]#

Whether this command age-restricted.

abstract property name: str[source]#

Name to set for this command.

Warning

This should match the regex ^[-_p{L}p{N}p{sc=Deva}p{sc=Thai}]{1,32}$ in Unicode mode and must be lowercase.

abstract property name_localizations: Mapping[hikari.locales.Locale | str, str][source]#

Name localizations set for this command.

abstract property type: hikari.commands.CommandType[source]#

Type of this command.

abstract build(entity_factory, /)[source]#

Build a JSON object from this builder.

Parameters:
entity_factoryhikari.api.entity_factory.EntityFactory

The entity factory to use to serialize entities within this builder.

Returns:
typing.MutableMapping[str, typing.Any]

The built json object representation of this builder.

abstract async create(rest, application, /, *, guild=undefined.UNDEFINED)[source]#

Create this command through a REST call.

Parameters:
resthikari.api.rest.RESTClient

The REST client to use to make this request.

applicationhikari.snowflakes.SnowflakeishOr[hikari.guilds.PartialApplication]

The application to create this command for.

Other Parameters:
guildhikari.undefined.UndefinedOr[hikari.snowflakes.SnowflakeishOr[hikari.guilds.PartialGuild]]

The guild to create this command for.

If left undefined then this command will be declared globally.

Returns:
hikari.commands.PartialCommand

The created command.

abstract set_default_member_permissions(default_member_permissions, /)[source]#

Set the member permissions necessary to utilize this command by default.

Parameters:
default_member_permissionshikari.undefined.UndefinedOr[bool]

The default member permissions to utilize this command by default.

If 0, then it will be available for all members. Note that this doesn’t affect administrators of the guild and overwrites.

Returns:
CommandBuilder

Object of this command builder.

abstract set_id(id_, /)[source]#

Set the ID of this command.

Parameters:
id_hikari.undefined.UndefinedOr[hikari.snowflakes.Snowflake]

The ID to set for this command.

Returns:
CommandBuilder

Object of this command builder to allow for chained calls.

abstract set_is_dm_enabled(state, /)[source]#

Set whether this command will be enabled in DMs with the bot.

Parameters:
statehikari.undefined.UndefinedOr[bool]

Whether this command is enabled in DMs with the bot.

Returns:
CommandBuilder

Object of this command builder to allow for chained calls.

abstract set_is_nsfw(state, /)[source]#

Set whether this command will be age-restricted.

Parameters:
statehikari.undefined.UndefinedOr[bool]

Whether this command is age-restricted.

Returns:
CommandBuilder

Object of this command builder for chained calls.

abstract set_name(name, /)[source]#

Set the name of this command.

Parameters:
namestr

The name to set for this command.

Returns:
CommandBuilder

Object of this command builder to allow for chained calls.

abstract set_name_localizations(name_localizations, /)[source]#

Set the name localizations for this command.

Parameters:
name_localizationstyping.Mapping[typing.Union[hikari.locales.Locale, str], str]

The name localizations to set for this command.

Returns:
CommandBuilder

Object of this command builder.

class hikari.api.special_endpoints.ComponentBuilder[source]#

Bases: abc.ABC

Base class for all component builder classes.

abstract property type: int | hikari.components.ComponentType[source]#

Type of component this builder represents.

abstract build()[source]#

Build a JSON object from this builder.

Returns:
typing.MutableMapping[str, typing.Any]

The built json object representation of this builder.

class hikari.api.special_endpoints.ContextMenuCommandBuilder[source]#

Bases: CommandBuilder

ContextMenuCommandBuilder.

abstract async create(rest, application, /, *, guild=undefined.UNDEFINED)[source]#

Create this command through a REST call.

This is a shorthand for calling hikari.api.rest.RESTClient.create_context_menu_command with the builder’s information.

Parameters:
resthikari.api.rest.RESTClient

The REST client to use to make this request.

applicationhikari.snowflakes.SnowflakeishOr[hikari.guilds.PartialApplication]

The application to create this command for.

Other Parameters:
guildhikari.undefined.UndefinedOr[hikari.snowflakes.SnowflakeishOr[hikari.guilds.PartialGuild]]

The guild to create this command for.

If left undefined then this command will be declared globally.

Returns:
hikari.commands.ContextMenuCommand

The created command.

class hikari.api.special_endpoints.GuildBuilder[source]#

Bases: abc.ABC

Result type of hikari.api.rest.RESTClient.guild_builder.

This is used to create a guild in a tidy way using the HTTP API, since the logic behind creating a guild on an API level is somewhat confusing and detailed.

Note

If you call add_role, the default roles provided by Discord will be created. This also applies to the add_ functions for text channels/voice channels/categories.

Note

Functions that return a hikari.snowflakes.Snowflake do not provide the final ID that the object will have once the API call is made. The returned IDs are only able to be used to re-reference particular objects while building the guild format to allow for the creation of channels within categories, and to provide permission overwrites.

Examples

Creating an empty guild:

guild = await rest.guild_builder("My Server!").create()

Creating a guild with an icon:

from hikari.files import WebResourceStream

guild_builder = rest.guild_builder("My Server!")
guild_builder.icon = WebResourceStream("cat.png", "http://...")
guild = await guild_builder.create()

Adding roles to your guild:

from hikari.permissions import Permissions

guild_builder = rest.guild_builder("My Server!")

everyone_role_id = guild_builder.add_role("@everyone")
admin_role_id = guild_builder.add_role("Admins", permissions=Permissions.ADMINISTRATOR)

await guild_builder.create()

Warning

The first role must always be the @everyone role.

Adding a text channel to your guild:

guild_builder = rest.guild_builder("My Server!")

category_id = guild_builder.add_category("My safe place")
channel_id = guild_builder.add_text_channel("general", parent_id=category_id)

await guild_builder.create()
abstract property default_message_notifications: hikari.undefined.UndefinedOr[hikari.guilds.GuildMessageNotificationsLevel][source]#

Default message notification level that can be overwritten.

If not overridden, this will use the Discord default level.

abstract property explicit_content_filter_level: hikari.undefined.UndefinedOr[hikari.guilds.GuildExplicitContentFilterLevel][source]#

Explicit content filter level that can be overwritten.

If not overridden, this will use the Discord default level.

abstract property icon: hikari.undefined.UndefinedOr[hikari.files.Resourceish][source]#

Guild icon to use that can be overwritten.

If not overridden, the guild will not have an icon.

abstract property name: str[source]#

Name of the guild to create.

abstract property verification_level: hikari.undefined.UndefinedOr[hikari.guilds.GuildVerificationLevel | int][source]#

Verification level required to join the guild.

abstract add_category(name, /, *, position=undefined.UNDEFINED, permission_overwrites=undefined.UNDEFINED)[source]#

Create a category channel.

Parameters:
namestr

The channels name. Must be between 2 and 1000 characters.

Other Parameters:
positionhikari.undefined.UndefinedOr[int]

If provided, the position of the category.

permission_overwriteshikari.undefined.UndefinedOr[typing.Sequence[hikari.channels.PermissionOverwrite]]

If provided, the permission overwrites for the category.

Returns:
hikari.snowflakes.Snowflake

The dummy ID for this channel that can be used temporarily to refer to this object while designing the guild layout.

When the guild is created, this will be replaced with a different ID.

abstract add_role(name, /, *, permissions=undefined.UNDEFINED, color=undefined.UNDEFINED, colour=undefined.UNDEFINED, hoist=undefined.UNDEFINED, mentionable=undefined.UNDEFINED, position=undefined.UNDEFINED)[source]#

Create a role.

Warning

The first role you create must always be the @everyone role.

Parameters:
namestr

The role’s name.

Other Parameters:
permissionshikari.undefined.UndefinedOr[hikari.permissions.Permissions]

If provided, the permissions for the role.

colorhikari.undefined.UndefinedOr[hikari.colors.Colorish]

If provided, the role’s color.

colourhikari.undefined.UndefinedOr[hikari.colors.Colorish]

An alias for color.

hoisthikari.undefined.UndefinedOr[bool]

If provided, whether to hoist the role.

mentionablehikari.undefined.UndefinedOr[bool]

If provided, whether to make the role mentionable.

Returns:
hikari.snowflakes.Snowflake

The dummy ID for this role that can be used temporarily to refer to this object while designing the guild layout.

When the guild is created, this will be replaced with a different ID.

Raises:
ValueError

If you are defining the first role, but did not name it @everyone.

TypeError

If you specify both color and colour together or if you try to specify color, colour, hoisted, mentionable or position for the @everyone role.

abstract add_stage_channel(name, /, *, parent_id=undefined.UNDEFINED, bitrate=undefined.UNDEFINED, position=undefined.UNDEFINED, permission_overwrites=undefined.UNDEFINED, region, user_limit=undefined.UNDEFINED)[source]#

Create a stage channel.

Parameters:
namestr

The channels name. Must be between 2 and 1000 characters.

Other Parameters:
positionhikari.undefined.UndefinedOr[int]

If provided, the position of the channel (relative to the category, if any).

user_limithikari.undefined.UndefinedOr[int]

If provided, the maximum users in the channel at once. Must be between 0 and 99 with 0 meaning no limit.

bitratehikari.undefined.UndefinedOr[int]

If provided, the bitrate for the channel. Must be between 8000 and 96000 or 8000 and 128000 for VIP servers.

permission_overwriteshikari.undefined.UndefinedOr[typing.Sequence[hikari.channels.PermissionOverwrite]]

If provided, the permission overwrites for the channel.

regionhikari.undefined.UndefinedOr[typing.Union[hikari.voices.VoiceRegion, str]]

If provided, the voice region to for this channel. Passing None here will set it to “auto” mode where the used region will be decided based on the first person who connects to it when it’s empty.

parent_idhikari.undefined.UndefinedOr[hikari.snowflakes.Snowflake]

The ID of the category to create the channel under.

Returns:
hikari.snowflakes.Snowflake

The dummy ID for this channel that can be used temporarily to refer to this object while designing the guild layout.

When the guild is created, this will be replaced with a different ID.

abstract add_text_channel(name, /, *, parent_id=undefined.UNDEFINED, topic=undefined.UNDEFINED, rate_limit_per_user=undefined.UNDEFINED, position=undefined.UNDEFINED, permission_overwrites=undefined.UNDEFINED, nsfw=undefined.UNDEFINED)[source]#

Create a text channel.

Parameters:
namestr

The channels name. Must be between 2 and 1000 characters.

Other Parameters:
positionhikari.undefined.UndefinedOr[int]

If provided, the position of the channel (relative to the category, if any).

topichikari.undefined.UndefinedOr[str]

If provided, the channels topic. Maximum 1024 characters.

nsfwhikari.undefined.UndefinedOr[bool]

If provided, whether to mark the channel as NSFW.

rate_limit_per_userhikari.undefined.UndefinedOr[int]

If provided, the amount of seconds a user has to wait before being able to send another message in the channel. Maximum 21600 seconds.

permission_overwriteshikari.undefined.UndefinedOr[typing.Sequence[hikari.channels.PermissionOverwrite]]

If provided, the permission overwrites for the channel.

parent_idhikari.undefined.UndefinedOr[hikari.snowflakes.Snowflake]

The ID of the category to create the channel under.

Returns:
hikari.snowflakes.Snowflake

The dummy ID for this channel that can be used temporarily to refer to this object while designing the guild layout.

When the guild is created, this will be replaced with a different ID.

abstract add_voice_channel(name, /, *, parent_id=undefined.UNDEFINED, bitrate=undefined.UNDEFINED, video_quality_mode=undefined.UNDEFINED, position=undefined.UNDEFINED, permission_overwrites=undefined.UNDEFINED, region, user_limit=undefined.UNDEFINED)[source]#

Create a voice channel.

Parameters:
namestr

The channels name. Must be between 2 and 1000 characters.

Other Parameters:
positionhikari.undefined.UndefinedOr[int]

If provided, the position of the channel (relative to the category, if any).

user_limithikari.undefined.UndefinedOr[int]

If provided, the maximum users in the channel at once. Must be between 0 and 99 with 0 meaning no limit.

bitratehikari.undefined.UndefinedOr[int]

If provided, the bitrate for the channel. Must be between 8000 and 96000 or 8000 and 128000 for VIP servers.

video_quality_modehikari.undefined.UndefinedOr[typing.Union[hikari.channels.VideoQualityMode, int]]

If provided, the new video quality mode for the channel.

permission_overwriteshikari.undefined.UndefinedOr[typing.Sequence[hikari.channels.PermissionOverwrite]]

If provided, the permission overwrites for the channel.

regionhikari.undefined.UndefinedOr[typing.Union[hikari.voices.VoiceRegion, str]]

If provided, the voice region to for this channel. Passing None here will set it to “auto” mode where the used region will be decided based on the first person who connects to it when it’s empty.

parent_idhikari.undefined.UndefinedOr[hikari.snowflakes.Snowflake]

The ID of the category to create the channel under.

Returns:
hikari.snowflakes.Snowflake

The dummy ID for this channel that can be used temporarily to refer to this object while designing the guild layout.

When the guild is created, this will be replaced with a different ID.

abstract async create()[source]#

Send the request to Discord to create the guild.

The application user will be added to this guild as soon as it is created. All IDs that were provided when building this guild will become invalid and will be replaced with real IDs.

Returns:
hikari.guilds.RESTGuild

The created guild.

Raises:
hikari.errors.BadRequestError

If any values set in the guild builder are invalid.

hikari.errors.UnauthorizedError

If you are unauthorized to make the request (invalid/missing token).

hikari.errors.ForbiddenError

If you are already in 10 guilds.

hikari.errors.InternalServerError

If an internal error occurs on Discord while handling the request.

class hikari.api.special_endpoints.InteractionAutocompleteBuilder[source]#

Bases: InteractionResponseBuilder, abc.ABC

Interface of an autocomplete interaction response builder.

abstract property choices: Sequence[AutocompleteChoiceBuilder][source]#

Autocomplete choices.

abstract set_choices(choices, /)[source]#

Set autocomplete choices.

Parameters:
choicestyping.Sequence[AutocompleteChoiceBuilder]

The choices to set.

Returns:
InteractionAutocompleteBuilder

Object of this builder.

class hikari.api.special_endpoints.InteractionDeferredBuilder[source]#

Bases: InteractionResponseBuilder, abc.ABC

Interface of a deferred message interaction response builder.

abstract property flags: hikari.undefined.UndefinedType | int | hikari.messages.MessageFlag[source]#

Message flags this response should have.

Note

As of writing the only message flags which can be set here are hikari.messages.MessageFlag.EPHEMERAL, hikari.messages.MessageFlag.SUPPRESS_NOTIFICATIONS and hikari.messages.MessageFlag.SUPRESS_EMBEDS.

abstract property type: hikari.interactions.base_interactions.DeferredResponseTypesT[source]#

Type of this response.

abstract set_flags(flags, /)[source]#

Set message flags for this response.

Note

As of writing, the only message flags which can be set are hikari.messages.MessageFlag.EPHEMERAL hikari.messages.MessageFlag.SUPPRESS_NOTIFICATIONS and hikari.messages.MessageFlag.SUPRESS_EMBEDS.

Parameters:
flagstyping.Union[hikari.undefined.UndefinedType, int, hikari.messages.MessageFlag]

The message flags to set for this response.

Returns:
InteractionMessageBuilder

Object of this builder.

class hikari.api.special_endpoints.InteractionMessageBuilder[source]#

Bases: InteractionResponseBuilder, abc.ABC

Interface of an interaction message response builder used within REST servers.

This can be returned by the listener registered to hikari.api.interaction_server.InteractionServer as a response to the interaction create.

abstract property attachments: hikari.undefined.UndefinedNoneOr[Sequence[hikari.files.Resourceish]][source]#

Sequence of up to 10 attachments to send with the message.

abstract property components: hikari.undefined.UndefinedOr[Sequence[ComponentBuilder]][source]#

Sequence of up to 5 component builders to send in this response.

abstract property content: hikari.undefined.UndefinedOr[str][source]#

Response’s message content.

abstract property embeds: hikari.undefined.UndefinedOr[Sequence[hikari.embeds.Embed]][source]#

Sequence of up to 10 of the embeds included in this response.

abstract property flags: hikari.undefined.UndefinedType | int | hikari.messages.MessageFlag[source]#

Message flags this response should have.

Note

As of writing the only message flags which can be set here are hikari.messages.MessageFlag.EPHEMERAL, hikari.messages.MessageFlag.SUPPRESS_NOTIFICATIONS and hikari.messages.MessageFlag.SUPRESS_EMBEDS.

abstract property is_tts: hikari.undefined.UndefinedOr[bool][source]#

Whether this response’s content should be treated as text-to-speech.

abstract property mentions_everyone: hikari.undefined.UndefinedOr[bool][source]#

Whether @everyone and @here mentions should be enabled for this response.

abstract property role_mentions: hikari.undefined.UndefinedOr[hikari.snowflakes.SnowflakeishSequence[hikari.guilds.PartialRole] | bool][source]#

Whether and what role mentions should be enabled for this response.

Either a sequence of object/IDs of the roles mentions should be enabled for, False or hikari.undefined.UNDEFINED to disallow any role mentions or True to allow all role mentions.

abstract property type: hikari.interactions.base_interactions.MessageResponseTypesT[source]#

Type of this response.

abstract property user_mentions: hikari.undefined.UndefinedOr[hikari.snowflakes.SnowflakeishSequence[hikari.users.PartialUser] | bool][source]#

Whether and what user mentions should be enabled for this response.

Either a sequence of object/IDs of the users mentions should be enabled for, False or hikari.undefined.UNDEFINED to disallow any user mentions or True to allow all user mentions.

abstract add_attachment(attachment, /)[source]#

Add an attachment to this response.

Parameters:
attachmenthikari.files.Resourceish

The attachment to add.

Returns:
InteractionMessageBuilder

Object of this builder.

abstract add_component(component, /)[source]#

Add a component to this response.

Parameters:
componentComponentBuilder

The component builder to add to this response.

Returns:
InteractionMessageBuilder

Object of this builder.

abstract add_embed(embed, /)[source]#

Add an embed to this response.

Parameters:
embedhikari.embeds.Embed

Object of the embed to add to this response.

Returns:
InteractionMessageBuilder

Object of this builder to allow for chained calls.

abstract clear_attachments(/)[source]#

Clear attachments for this response.

This is only useful for message update responses, where you might want to remove all existing attachments.

Returns:
InteractionMessageBuilder

Object of this builder.

abstract set_content(content, /)[source]#

Set the response’s message content.

Parameters:
contenthikari.undefined.UndefinedOr[str]

The message content to set for this response.

Returns:
InteractionMessageBuilder

Object of this builder to allow for chained calls.

abstract set_flags(flags, /)[source]#

Set message flags for this response.

Note

As of writing, the only message flags which can be set is hikari.messages.MessageFlag.EPHEMERAL and hikari.messages.MessageFlag.SUPPRESS_NOTIFICATIONS..

Parameters:
flagstyping.Union[hikari.undefined.UndefinedType, int, hikari.messages.MessageFlag]

The message flags to set for this response.

Returns:
InteractionMessageBuilder

Object of this builder to allow for chained calls.

abstract set_mentions_everyone(mentions=undefined.UNDEFINED, /)[source]#

Set whether this response should be able to mention @everyone/@here.

Parameters:
mentionshikari.undefined.UndefinedOr[bool]

Whether this response should be able to mention @everyone/@here.

Returns:
InteractionMessageBuilder

Object of this builder to allow for chained calls.

abstract set_role_mentions(mentions=undefined.UNDEFINED, /)[source]#

Set whether and what role mentions should be possible for this response.

Parameters:
mentionshikari.undefined.UndefinedOr[typing.Union[hikari.snowflakes.SnowflakeishSequence[hikari.users.PartialUser], bool]]

Either a sequence of object/IDs of the roles mentions should be enabled for, False or hikari.undefined.UNDEFINED to disallow any role mentions or True to allow all role mentions.

Returns:
InteractionMessageBuilder

Object of this builder to allow for chained calls.

abstract set_tts(tts, /)[source]#

Set whether this response should trigger text-to-speech processing.

Parameters:
ttsbool

Whether this response should trigger text-to-speech processing.

Returns:
InteractionMessageBuilder

Object of this builder to allow for chained calls.

abstract set_user_mentions(mentions=undefined.UNDEFINED, /)[source]#

Set whether and what user mentions should be possible for this response.

Parameters:
mentionshikari.undefined.UndefinedOr[typing.Union[hikari.snowflakes.SnowflakeishSequence[hikari.users.PartialUser], bool]]

Either a sequence of object/IDs of the users mentions should be enabled for, False or hikari.undefined.UNDEFINED to disallow any user mentions or True to allow all user mentions.

Returns:
InteractionMessageBuilder

Object of this builder to allow for chained calls.

class hikari.api.special_endpoints.InteractionModalBuilder[source]#

Bases: InteractionResponseBuilder, abc.ABC

Interface of an interaction modal response builder used within REST servers.

This can be returned by the listener registered to hikari.api.interaction_server.InteractionServer as a response to the interaction create.

abstract property components: hikari.undefined.UndefinedOr[Sequence[ComponentBuilder]][source]#

Sequence of component builders to send in this modal.

abstract property custom_id: str[source]#

Developer set custom ID used for identifying interactions with this modal.

abstract property title: str[source]#

Title that will show up in the modal.

abstract property type: Literal[hikari.interactions.base_interactions.ResponseType.MODAL][source]#

Type of this response.

abstract add_component(component, /)[source]#

Add a component to this modal.

Parameters:
componentComponentBuilder

The component builder to add to this modal.

abstract set_custom_id(custom_id, /)[source]#

Set the custom ID used for identifying interactions with this modal.

Parameters:
custom_idstr

The developer set custom ID used for identifying interactions with this modal.

abstract set_title(title, /)[source]#

Set the title that will show up in the modal.

Parameters:
titlestr

The title that will show up in the modal.

class hikari.api.special_endpoints.InteractionResponseBuilder[source]#

Bases: abc.ABC

Base class for all interaction response builders used in the interaction server.

abstract property type: int | hikari.interactions.base_interactions.ResponseType[source]#

Type of this response.

abstract build(entity_factory, /)[source]#

Build a JSON object from this builder.

Parameters:
entity_factoryhikari.api.entity_factory.EntityFactory

The entity factory to use to serialize entities within this builder.

Returns:
typing.Tuple[typing.MutableMapping[str, typing.Any], typing.Sequence[files.Resource[Files.AsyncReader]]

A tuple of the built json object representation of this builder and a sequence of up to 10 files to send with the response.

class hikari.api.special_endpoints.InteractiveButtonBuilder[source]#

Bases: ButtonBuilder, abc.ABC

Builder interface for interactive buttons.

abstract property custom_id: str[source]#

Developer set custom ID used for identifying interactions with this button.

abstract set_custom_id(custom_id, /)[source]#

Set the custom ID used for identifying this button.

Parameters:
custom_idstr

Developer set custom ID used for identifying this button.

Returns:
InteractiveButtonBuilder

The builder object to enable chained calls.

class hikari.api.special_endpoints.LinkButtonBuilder[source]#

Bases: ButtonBuilder, abc.ABC

Builder interface for link buttons.

abstract property url: str[source]#

URL this button should link to when pressed.

class hikari.api.special_endpoints.MessageActionRowBuilder[source]#

Bases: ComponentBuilder, abc.ABC

Builder class for action row components.

abstract property components: Sequence[ComponentBuilder][source]#

Sequence of the component builders registered within this action row.

abstract property type: Literal[hikari.components.ComponentType.ACTION_ROW][source]#

Type of component this builder represents.

abstract add_channel_menu(custom_id, /, *, channel_types=(), placeholder=undefined.UNDEFINED, min_values=0, max_values=1, is_disabled=False)[source]#

Add a channel select menu component to this action row builder.

Parameters:
custom_idstr

A developer-defined custom identifier used to identify which menu triggered component interactions.

channel_typestyping.Sequence[hikari.channels.ChannelType]

The channel types this select menu should allow.

If left as an empty sequence then there will be no channel type restriction.

placeholderhikari.undefined.UndefinedOr[str]

Placeholder text to show when no entries have been selected.

min_valuesint

The minimum amount of entries which need to be selected.

max_valuesint

The maximum amount of entries which can be selected.

is_disabledbool

Whether this select menu should be marked as disabled.

Returns:
ActionRowBuilder

The action row builder to enable chained calls.

Raises:
ValueError

If an invalid select menu type is passed.

abstract add_component(component, /)[source]#

Add a component to this action row builder.

Warning

It is generally better to use ActionRowBuilder.add_button and ActionRowBuilder.add_select_menu to add your component to the builder. Those methods utilize this one.

Parameters:
componentComponentBuilder

The component builder to add to the action row.

Returns:
ActionRowBuilder

The builder object to enable chained calls.

abstract add_interactive_button(style, custom_id, /, *, emoji=undefined.UNDEFINED, label=undefined.UNDEFINED, is_disabled=False)[source]#

Add an interactive button component to this action row builder.

Either emoji or label (exclusively) must be provided to be the button’s displayed label.

Parameters:
stylehikari.messages.InteractiveButtonTypesT

The button’s style.

custom_idstr

The developer-defined custom identifier used to identify which button triggered component interactions.

emojityping.Union[hikari.snowflakes.Snowflakeish, hikari.emojis.Emoji, str, hikari.undefined.UndefinedType]

The button’s display emoji.

labelhikari.undefined.UndefinedOr[str]

The button’s display label.

is_disabledbool

Whether the button should be marked as disabled.

Returns:
ActionRowBuilder

The action row builder to enable chained calls.

Add a link button component to this action row builder.

Either emoji or label (exclusively) must be provided to be the button’s displayed label.

Parameters:
urlstr

The URL the link button should redirect to.

emojityping.Union[hikari.snowflakes.Snowflakeish, hikari.emojis.Emoji, str, hikari.undefined.UndefinedType]

The button’s display emoji.

labelhikari.undefined.UndefinedOr[str]

The button’s display label.

is_disabledbool

Whether the button should be marked as disabled.

Returns:
ActionRowBuilder

The action row builder to enable chained calls.

abstract add_select_menu(type_, custom_id, /, *, placeholder=undefined.UNDEFINED, min_values=0, max_values=1, is_disabled=False)[source]#

Add a select menu component to this action row builder.

For channel select menus and text select menus see MessageActionRowBuilder.add_channel_menu and MessageActionRowBuilder.add_text_menu.

Parameters:
type_typing.Union[hikari.components.ComponentType, int]

The type for the select menu.

custom_idstr

A developer-defined custom identifier used to identify which menu triggered component interactions.

placeholderhikari.undefined.UndefinedOr[str]

Placeholder text to show when no entries have been selected.

min_valuesint

The minimum amount of entries which need to be selected.

max_valuesint

The maximum amount of entries which can be selected.

is_disabledbool

Whether this select menu should be marked as disabled.

Returns:
ActionRowBuilder

The action row builder to enable chained calls.

Raises:
ValueError

If an invalid select menu type is passed.

abstract add_text_menu(custom_id, /, *, placeholder=undefined.UNDEFINED, min_values=0, max_values=1, is_disabled=False)[source]#

Add a select menu component to this action row builder.

Parameters:
custom_idstr

A developer-defined custom identifier used to identify which menu triggered component interactions.

placeholderhikari.undefined.UndefinedOr[str]

Placeholder text to show when no entries have been selected.

min_valuesint

The minimum amount of entries which need to be selected.

max_valuesint

The maximum amount of entries which can be selected.

is_disabledbool

Whether this select menu should be marked as disabled.

Returns:
TextSelectMenuBuilder

The text select menu builder.

TextSelectMenuBuilder.add_option should be called to add options to the returned builder then TextSelectMenuBuilder.parent can be used to return to this action row while chaining calls.

Raises:
ValueError

If an invalid select menu type is passed.

class hikari.api.special_endpoints.ModalActionRowBuilder[source]#

Bases: ComponentBuilder, abc.ABC

Builder class for modal action row components.

abstract property components: Sequence[ComponentBuilder][source]#

Sequence of the component builders registered within this action row.

abstract property type: Literal[hikari.components.ComponentType.ACTION_ROW][source]#

Type of component this builder represents.

abstract add_component(component, /)[source]#

Add a component to this action row builder.

Warning

It is generally better to use ActionRowBuilder.add_button and ActionRowBuilder.add_select_menu to add your component to the builder. Those methods utilize this one.

Parameters:
componentComponentBuilder

The component builder to add to the action row.

Returns:
ActionRowBuilder

The builder object to enable chained calls.

abstract add_text_input(custom_id, label, /, *, style=components_.TextInputStyle.SHORT, placeholder=undefined.UNDEFINED, value=undefined.UNDEFINED, required=True, min_length=0, max_length=4000)[source]#

Add a text input component to this action row builder.

Parameters:
custom_idstr

Developer set custom ID used for identifying this text input.

labelstr

Label above this text input.

stylehikari.components.TextInputStyle

The text input’s style.

placeholderhikari.undefined.UndefinedOr[str]

Placeholder text to display when the text input is empty.

valuehikari.undefined.UndefinedOr[str]

Default text to pre-fill the field with.

requiredbool

Whether text must be supplied for this text input.

min_lengthint

Minimum length the input text can be.

This can be greater than or equal to 0 and less than or equal to 4000.

max_lengthint

Maximum length the input text can be.

This can be greater than or equal to 1 and less than or equal to 4000.

Returns:
ModalActionRowBuilder

The modal action row builder to enable call chaining.

class hikari.api.special_endpoints.SelectMenuBuilder[source]#

Bases: ComponentBuilder, abc.ABC

Builder class for a select menu.

abstract property custom_id: str[source]#

Developer set custom ID used for identifying interactions with this menu.

abstract property is_disabled: bool[source]#

Whether the select menu should be marked as disabled.

abstract property max_values: int[source]#

Maximum number of options which can be chosen.

Defaults to 1. Must be greater than or equal to SelectMenuBuilder.min_values and less than or equal to 25.

abstract property min_values: int[source]#

Minimum number of options which must be chosen.

Defaults to 1. Must be less than or equal to SelectMenuBuilder.max_values and greater than or equal to 0.

abstract property placeholder: hikari.undefined.UndefinedOr[str][source]#

Placeholder text to display when no options are selected.

abstract set_custom_id(custom_id, /)[source]#

Set the custom ID used for identifying this menu.

Parameters:
custom_idstr

Developer set custom ID used for identifying this menu.

Returns:
SelectMenuBuilder

The builder object to enable chained calls.

abstract set_is_disabled(state, /)[source]#

Set whether this option is disabled.

Defaults to False.

Parameters:
statebool

Whether this option is disabled.

Returns:
SelectMenuBuilder

The builder object to enable chained calls.

abstract set_max_values(value, /)[source]#

Set the maximum amount of options which can be selected for this menu.

Note

This defaults to 1 if not set and must be less than or equal to 25 and greater than or equal to SelectMenuBuilder.min_values.

Parameters:
valueint

The maximum amount of options which can selected for this menu.

Returns:
SelectMenuBuilder

The builder object to enable chained calls.

abstract set_min_values(value, /)[source]#

Set the minimum amount of options which need to be selected for this menu.

Note

This defaults to 1 if not set and must be greater than or equal to 0 and less than or equal to SelectMenuBuilder.max_values.

Parameters:
valueint

The minimum amount of options which need to be selected for this menu.

Returns:
SelectMenuBuilder

The builder object to enable chained calls.

abstract set_placeholder(value, /)[source]#

Set place-holder text to be shown when no option is selected.

Parameters:
valuehikari.undefined.UndefinedOr[str]

Place-holder text to be displayed when no option is selected. Max 100 characters.

Returns:
SelectMenuBuilder

The builder object to enable chained calls.

class hikari.api.special_endpoints.SelectOptionBuilder[source]#

Bases: abc.ABC

Builder class for select menu options.

abstract property description: hikari.undefined.UndefinedOr[str][source]#

Description of the option, max 100 characters.

abstract property emoji: hikari.snowflakes.Snowflakeish | hikari.emojis.Emoji | str | hikari.undefined.UndefinedType[source]#

Emoji which should appear on this option.

abstract property is_default: bool[source]#

Whether this option should be marked as selected by default.

abstract property label: str[source]#

User-facing name of the option, max 100 characters.

abstract property value: str[source]#

Developer-defined value of the option, max 100 characters.

abstract build()[source]#

Build a JSON object from this builder.

Returns:
typing.MutableMapping[str, typing.Any]

The built json object representation of this builder.

abstract set_description(value, /)[source]#

Set the option’s description.

Parameters:
valuehikari.undefined.UndefinedOr[str]

Description to set for this option. This can be up to 100 characters long.

Returns:
SelectOptionBuilder

The builder object to enable chained calls.

abstract set_emoji(emoji, /)[source]#

Set the emoji to display on this option.

Parameters:
emojityping.Union[hikari.snowflakes.Snowflakeish, hikari.emojis.Emoji, str, hikari.undefined.UndefinedType]

Object, ID or raw string of the emoji which should be displayed on this option.

Returns:
SelectOptionBuilder

The builder object to enable chained calls.

abstract set_is_default(state, /)[source]#

Set whether this option should be selected by default.

Parameters:
statebool

Whether this option should be selected by default.

Returns:
SelectOptionBuilder

The builder object to enable chained calls.

abstract set_label(label, /)[source]#

Set the option’s label.

Parameters:
labelstr

Label to set for this option. This can be up to 100 characters long.

Returns:
SelectOptionBuilder

The builder object to enable chained calls.

abstract set_value(value, /)[source]#

Set the option’s value.

Parameters:
valuestr

Value to set for this option. This can be up to 100 characters long.

Returns:
SelectOptionBuilder

The builder object to enable chained calls.

class hikari.api.special_endpoints.SlashCommandBuilder[source]#

Bases: CommandBuilder

SlashCommandBuilder.

abstract property description: str[source]#

Command’s description.

Warning

This should be inclusively between 1-100 characters in length.

abstract property description_localizations: Mapping[hikari.locales.Locale | str, str][source]#

Command’s localised descriptions.

abstract property options: Sequence[hikari.commands.CommandOption][source]#

Sequence of up to 25 of the options set for this command.

abstract add_option(option)[source]#

Add an option to this command.

Note

A command can have up to 25 options.

Parameters:
optionhikari.commands.CommandOption

The option to add to this command.

Returns:
SlashCommandBuilder

Object of this command builder to allow for chained calls.

abstract async create(rest, application, /, *, guild=undefined.UNDEFINED)[source]#

Create this command through a REST call.

This is a shorthand for calling hikari.api.rest.RESTClient.create_slash_command with the builder’s information.

Parameters:
resthikari.api.rest.RESTClient

The REST client to use to make this request.

applicationhikari.snowflakes.SnowflakeishOr[hikari.guilds.PartialApplication]

The application to create this command for.

Other Parameters:
guildhikari.undefined.UndefinedOr[hikari.snowflakes.SnowflakeishOr[hikari.guilds.PartialGuild]]

The guild to create this command for.

If left undefined then this command will be declared globally.

Returns:
hikari.commands.SlashCommand

The created command.

abstract set_description(description, /)[source]#

Set the description for this command.

Parameters:
descriptionstr

The description to set for this command.

Returns:
SlashCommandBuilder

Object of this command builder.

abstract set_description_localizations(description_localizations, /)[source]#

Set the localised descriptions for this command.

Parameters:
description_localizationstyping.Mapping[typing.Union[hikari.locales.Locale, str], str]

The description localizations to set for this command.

Returns:
SlashCommandBuilder

Object of this command builder.

class hikari.api.special_endpoints.TextInputBuilder[source]#

Bases: ComponentBuilder, abc.ABC

Builder class for text inputs components.

abstract property custom_id: str[source]#

Developer set custom ID used for identifying this text input.

Note

This custom_id is never used in component interaction events. It is meant to be used purely for resolving components modal interactions.

abstract property is_required: bool[source]#

Whether this text input is required to be filled-in.

abstract property label: str[source]#

Label above this text input.

abstract property max_length: int[source]#

Maximum length the text should have.

abstract property min_length: int[source]#

Minimum length the text should have.

abstract property placeholder: hikari.undefined.UndefinedOr[str][source]#

Placeholder text for when the text input is empty.

abstract property style: hikari.components.TextInputStyle[source]#

Style to use for the text input.

abstract property type: Literal[hikari.components.ComponentType.TEXT_INPUT][source]#

Type of component this builder represents.

abstract property value: hikari.undefined.UndefinedOr[str][source]#

Pre-filled text that will be sent if the user does not write anything.

abstract set_custom_id(custom_id, /)[source]#

Set the custom ID used for identifying this text input.

Parameters:
custom_idstr

Developer set custom ID used for identifying this text input.

Returns:
TextInputBuilder

The builder object to enable chained calls.

abstract set_label(label, /)[source]#

Set the label above this text input.

Parameters:
labelstr

Label above this text input.

Returns:
TextInputBuilder

The builder object to enable chained calls.

abstract set_max_length(max_length, /)[source]#

Set the maximum length the text should have.

Parameters:
max_lengthint

The maximum length the text should have.

Returns:
TextInputBuilder

The builder object to enable chained calls.

abstract set_min_length(min_length, /)[source]#

Set the minimum length the text should have.

Parameters:
min_lengthint

The minimum length the text should have.

Returns:
TextInputBuilder

The builder object to enable chained calls.

abstract set_placeholder(placeholder, /)[source]#

Set the placeholder text for when the text input is empty.

Parameters:
placeholderhikari.undefined.UndefinedOr[str]

Placeholder text that will disappear when the user types anything.

Returns:
TextInputBuilder

The builder object to enable chained calls.

abstract set_required(required, /)[source]#

Set whether this text input is required to be filled-in.

Parameters:
requiredbool

Whether this text input is required to be filled-in.

Returns:
TextInputBuilder

The builder object to enable chained calls.

abstract set_style(style, /)[source]#

Set the style to use for the text input.

Parameters:
styletyping.Union[hikari.modal_interactions.TextInputStyle, int]

Style to use for the text input.

Returns:
TextInputBuilder

The builder object to enable chained calls.

abstract set_value(value, /)[source]#

Pre-filled text that will be sent if the user does not write anything.

Parameters:
valuehikari.undefined.UndefinedOr[str]

Pre-filled text that will be sent if the user does not write anything.

Returns:
TextInputBuilder

The builder object to enable chained calls.

class hikari.api.special_endpoints.TextSelectMenuBuilder[source]#

Bases: SelectMenuBuilder, abc.ABC, Generic[_ParentT]

Builder class for a text select menu.

abstract property options: Sequence[SelectOptionBuilder][source]#

Sequence of the options set for this select menu.

abstract property parent: _ParentT[source]#

Parent object which initialised this builder.

abstract add_option(label, value, /, *, description=undefined.UNDEFINED, emoji=undefined.UNDEFINED, is_default=False)[source]#

Add an option to this menu.

Parameters:
labelstr

The user-facing name of this option, max 100 characters.

valuestr

The developer defined value of this option, max 100 characters.

descriptionhikari.undefined.UndefinedOr[str]

The option’s description.

This can be up to 100 characters long.

emojityping.Union[hikari.snowflakes.Snowflakeish, hikari.emojis.Emoji, str, hikari.undefined.UndefinedType]

The option’s display emoji.

is_defaultbool

Whether this option should be selected by default.

Returns:
TextSelectMenuBuilder

The select menu builder to enable call chaining.

class hikari.api.special_endpoints.TypingIndicator[source]#

Bases: abc.ABC

Result type of hikari.api.rest.RESTClient.trigger_typing.

This is an object that can either be awaited like a coroutine to trigger the typing indicator once, or an async context manager to keep triggering the typing indicator repeatedly until the context finishes.

Note

This is a helper class that is used by hikari.api.rest.RESTClient. You should only ever need to use instances of this class that are produced by that API.