hikari.api.special_endpoints

Special additional endpoints used by the REST API.

Module Contents

class hikari.api.special_endpoints.TypingIndicator

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.

class hikari.api.special_endpoints.GuildBuilder

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 name: str

Name of the guild to create.

abstract property default_message_notifications: hikari.undefined.UndefinedOr[hikari.guilds.GuildMessageNotificationsLevel]

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]

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]

Guild icon to use that can be overwritten.

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

abstract property verification_level: hikari.undefined.UndefinedOr[Union[hikari.guilds.GuildVerificationLevel, int]]

Verification level required to join the guild.

abstract async create()

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.

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

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_category(name, /, *, position=undefined.UNDEFINED, permission_overwrites=undefined.UNDEFINED)

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_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)

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)

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 add_stage_channel(name, /, *, parent_id=undefined.UNDEFINED, bitrate=undefined.UNDEFINED, position=undefined.UNDEFINED, permission_overwrites=undefined.UNDEFINED, region, user_limit=undefined.UNDEFINED)

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.

class hikari.api.special_endpoints.InteractionResponseBuilder

Bases: abc.ABC

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

abstract property type: Union[int, hikari.interactions.base_interactions.ResponseType]

Type of this response.

abstract build(entity_factory, /)

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

Bases: InteractionResponseBuilder, abc.ABC

Interface of a deferred message interaction response builder.

abstract property type: hikari.interactions.base_interactions.DeferredResponseTypesT

Type of this response.

abstract property flags: Union[hikari.undefined.UndefinedType, int, hikari.messages.MessageFlag]

Message flags this response should have.

Note

As of writing the only message flag which can be set here is hikari.messages.MessageFlag.EPHEMERAL.

abstract set_flags(flags, /)

Set message flags for this response.

Note

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

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

Bases: InteractionResponseBuilder, abc.ABC

Interface of an autocomplete interaction response builder.

abstract property choices: Sequence[hikari.commands.CommandChoice]

Autocomplete choices.

abstract set_choices(choices, /)

Set autocomplete choices.

Returns

InteractionAutocompleteBuilder

Object of this builder.

class hikari.api.special_endpoints.InteractionMessageBuilder

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 type: hikari.interactions.base_interactions.MessageResponseTypesT

Type of this response.

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

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

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

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

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

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

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

Response’s message content.

abstract property flags: Union[hikari.undefined.UndefinedType, int, hikari.messages.MessageFlag]

Message flags this response should have.

Note

As of writing the only message flag which can be set here is hikari.messages.MessageFlag.EPHEMERAL.

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

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

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

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

abstract property role_mentions: hikari.undefined.UndefinedOr[Union[hikari.snowflakes.SnowflakeishSequence[hikari.guilds.PartialRole], bool]]

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 user_mentions: hikari.undefined.UndefinedOr[Union[hikari.snowflakes.SnowflakeishSequence[hikari.users.PartialUser], bool]]

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 clear_attachments(/)

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 add_attachment(attachment, /)

Add an attachment to this response.

Parameters

attachmenthikari.files.Resourceish

The attachment to add.

Returns

InteractionMessageBuilder

Object of this builder.

abstract add_component(component, /)

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, /)

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 set_content(content, /)

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, /)

Set message flags for this response.

Note

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

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_tts(tts, /)

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_mentions_everyone(mentions=undefined.UNDEFINED, /)

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, /)

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_user_mentions(mentions=undefined.UNDEFINED, /)

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

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 type: Literal[hikari.interactions.base_interactions.ResponseType.MODAL]

Type of this response.

abstract property title: str

Title that will show up in the modal.

abstract property custom_id: str

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

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

Sequence of component builders to send in this modal.

abstract set_title(title, /)

Set the title that will show up in the modal.

Parameters

titlebuiltins.str

The title that will show up in the modal.

abstract set_custom_id(custom_id, /)

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

Parameters

custom_idbuiltins.str

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

abstract add_component(component, /)

Add a component to this modal.

Parameters

componentComponentBuilder

The component builder to add to this modal.

class hikari.api.special_endpoints.CommandBuilder

Bases: abc.ABC

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

abstract property name: str

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 type: hikari.commands.CommandType

Type of this command.

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

ID of this command.

abstract property default_member_permissions: Union[hikari.undefined.UndefinedType, hikari.permissions.Permissions, int]

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 is_dm_enabled: hikari.undefined.UndefinedOr[bool]

Whether this command is enabled in DMs with the bot.

Only applicable to globally-scoped commands.

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

Whether this command age-restricted.

abstract property name_localizations: Mapping[Union[hikari.locales.Locale, str], str]

Name localizations set for this command.

abstract set_id(id_, /)

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_default_member_permissions(default_member_permissions, /)

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_is_dm_enabled(state, /)

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, /)

Set whether this command will be age-restricted.

Parameters

statehikari.undefined.UndefinedOr[builtins.bool]

Whether this command is age-restricted.

Returns

CommandBuilder

Object of this command builder for chained calls.

abstract set_name_localizations(name_localizations, /)

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.

abstract build(entity_factory, /)

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)

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.

class hikari.api.special_endpoints.SlashCommandBuilder

Bases: CommandBuilder

SlashCommandBuilder.

abstract property description: str

Command’s description.

Warning

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

abstract property description_localizations: Mapping[Union[hikari.locales.Locale, str], str]

Command’s localised descriptions.

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

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

abstract set_description_localizations(description_localizations, /)

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

CommandBuilder

Object of this command builder.

abstract add_option(option)

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

CommandBuilder

Object of this command builder to allow for chained calls.

abstract async create(rest, application, /, *, guild=undefined.UNDEFINED)

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.

class hikari.api.special_endpoints.ContextMenuCommandBuilder

Bases: CommandBuilder

ContextMenuCommandBuilder.

abstract async create(rest, application, /, *, guild=undefined.UNDEFINED)

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

Bases: abc.ABC

Base class for all component builder classes.

abstract build()

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

Bases: ComponentBuilder, abc.ABC, Generic[_ContainerT]

Builder class for a message button component.

abstract property style: Union[hikari.components.ButtonStyle, int]

Button’s style.

abstract property emoji: Union[hikari.snowflakes.Snowflakeish, hikari.emojis.Emoji, str, hikari.undefined.UndefinedType]

Emoji which should appear on this button.

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

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 is_disabled: bool

Whether the button should be marked as disabled.

abstract set_emoji(emoji, /)

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_label(label, /)

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.

abstract set_is_disabled(state, /)

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 add_to_container()

Add this button to the container component it belongs to.

This is used as the finalising call during chained calls.

Returns

_ContainerT

The container component that owns this button.

class hikari.api.special_endpoints.LinkButtonBuilder

Bases: ButtonBuilder[_ContainerT], abc.ABC

Builder interface for link buttons.

abstract property url: str

URL this button should link to when pressed.

class hikari.api.special_endpoints.InteractiveButtonBuilder

Bases: ButtonBuilder[_ContainerT], abc.ABC

Builder interface for interactive buttons.

abstract property custom_id: str

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

class hikari.api.special_endpoints.SelectOptionBuilder

Bases: ComponentBuilder, abc.ABC, Generic[_SelectMenuBuilderT]

Builder class for select menu options.

abstract property label: str

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

abstract property value: str

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

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

Description of the option, max 100 characters.

abstract property emoji: Union[hikari.snowflakes.Snowflakeish, hikari.emojis.Emoji, str, hikari.undefined.UndefinedType]

Emoji which should appear on this option.

abstract property is_default: bool

Whether this option should be marked as selected by default.

abstract set_description(value, /)

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, /)

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, /)

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 add_to_menu()

Add this option to the menu component it belongs to.

This is used as the finalising call during chained calls.

Returns

_SelectMenuBuilderT

The menu component that owns this button.

class hikari.api.special_endpoints.SelectMenuBuilder

Bases: ComponentBuilder, abc.ABC, Generic[_ContainerT]

Builder class for select menu options.

abstract property custom_id: str

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

abstract property is_disabled: bool

Whether the select menu should be marked as disabled.

abstract property options: Sequence[SelectOptionBuilder[_SelectMenuBuilderT]]

Sequence of the options set for this select menu.

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

Placeholder text to display when no options are selected.

abstract property min_values: int

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 max_values: int

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 add_option(label, value, /)

Add an option to this menu.

Note

Setup should be finalised by calling add_to_menu in the builder returned.

Parameters

labelstr

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

valuestr

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

Returns

SelectOptionBuilder[SelectMenuBuilder]

Option builder object.

abstract set_is_disabled(state, /)

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_placeholder(value, /)

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.

abstract set_min_values(value, /)

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_max_values(value, /)

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 add_to_container()

Finalise this builder by adding it to its parent container component.

Returns

_ContainerT

The parent container component builder.

class hikari.api.special_endpoints.TextInputBuilder

Bases: ComponentBuilder, abc.ABC, Generic[_ContainerT]

Builder class for text inputs components.

abstract property custom_id: str

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 label: str

Label above this text input.

abstract property style: hikari.components.TextInputStyle

Style to use for the text input.

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

Placeholder text for when the text input is empty.

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

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

abstract property required: hikari.undefined.UndefinedOr[bool]

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

abstract property min_length: hikari.undefined.UndefinedOr[int]

Minimum length the text should have.

abstract property max_length: hikari.undefined.UndefinedOr[int]

Maximum length the text should have.

abstract set_style(style, /)

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_custom_id(custom_id, /)

Set the developer set custom ID used for identifying this text input.

Parameters

custom_idbuiltins.str

Developer set custom ID used for identifying this text input.

Returns

TextInputBuilder

The builder object to enable chained calls.

abstract set_label(label, /)

Set the label above this text input.

Parameters

labelbuiltins.str

Label above this text input.

Returns

TextInputBuilder

The builder object to enable chained calls.

abstract set_placeholder(placeholder, /)

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

Parameters

placeholderbuiltins.str:

Placeholder text that will disappear when the user types anything.

Returns

TextInputBuilder

The builder object to enable chained calls.

abstract set_value(value, /)

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

Parameters

valuebuiltins.str

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

Returns

TextInputBuilder

The builder object to enable chained calls.

abstract set_required(required, /)

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

Parameters

requiredbuiltins.bool

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

Returns

TextInputBuilder

The builder object to enable chained calls.

abstract set_min_length(min_length, /)

Set the minimum length the text should have.

Parameters

min_lengthbuiltins.int

The minimum length the text should have.

Returns

TextInputBuilder

The builder object to enable chained calls.

abstract set_max_length(max_length, /)

Set the maximum length the text should have.

Parameters

max_lengthbuiltins.int

The maximum length the text should have.

Returns

TextInputBuilder

The builder object to enable chained calls.

abstract add_to_container()

Finalise this builder by adding it to its parent container component.

Returns

_ContainerT

The parent container component builder.

class hikari.api.special_endpoints.MessageActionRowBuilder

Bases: ComponentBuilder, abc.ABC

Builder class for action row components.

abstract property components: Sequence[ComponentBuilder]

Sequence of the component builders registered within this action row.

abstract add_component(component, /)

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_button(style, custom_id, /)

abstract add_button(style: Literal[hikari.components.ButtonStyle.LINK, 5], url: str, /) → LinkButtonBuilder[_T]

abstract add_button(style: Union[int, hikari.components.ButtonStyle], url_or_custom_id: str, /) → Union[LinkButtonBuilder[_T], InteractiveButtonBuilder[_T]]

Add a button component to this action row builder.

Parameters

styletyping.Union[int, hikari.messages.ButtonStyle]

The button’s style.

url_or_custom_idstr

For interactive button styles this is a developer-defined custom identifier used to identify which button triggered component interactions.

For Link button styles this is the URL the link button should redirect to.

Returns

typing.Union[LinkButtonBuilder[Self], InteractiveButtonBuilder[Self]]

Button builder object. ButtonBuilder.add_to_container should be called to finalise the component.

abstract add_select_menu(custom_id, /)

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.

Returns

SelectMenuBuilder[Self]

Select menu builder object. SelectMenuBuilder.add_to_container should be called to finalise the component.

class hikari.api.special_endpoints.ModalActionRowBuilder

Bases: ComponentBuilder, abc.ABC

Builder class for modal action row components.

abstract property components: Sequence[ComponentBuilder]

Sequence of the component builders registered within this action row.

abstract add_component(component, /)

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)

Add a text input component to this action row builder.

Parameters

custom_idbuiltins.str

Developer set custom ID used for identifying this text input.

labelbuiltins.str

Label above this text input.

Returns

TextInputBuilder[Self]

Text input builder object. TextInputBuilder.add_to_container should be called to finalise the component.