Kord Extensions Help

Interactions

To give users richer ways to interact with your bot (when compared to sending messages), Discord provides a system known as Interactions. This system is designed to allow for public and private responses to rich Interaction types.

Interactions are an important concept to understand, as they will make up the bulk of user-triggered actions that your bot needs to deal with.

Interactions 101

Your bot receives an Interaction in response to one of the following actions taken on Discord:

When an Interaction is received from Discord, Kord will fire an event that extends InteractionCreateEvent. These events provide an interaction property, allowing you to respond directly to the Interaction.

When responding to an Interaction, your response may be one of the following main types:

  • Ephemeral, meaning only the user that triggered the Interaction is able to see the response.

  • Public, meaning everyone with access to the current channel is able to see the response and the user that triggered the Interaction.

Unexpected Interaction Behaviors

Internally, Discord's Interaction system is a bit of a mess. While it is technically possible to work with the Interaction API directly via some of the objects exposed by Kord Extensions (especially via the Unsafe Module), the built-in abstractions are provided to lower the risk of unexpected behavior.

Known instances of unexpected behavior include:

  • Responding to an Interaction using the wrong response type, after an initial response has been made. Even though the API technically allows you to respond using mixed response types, Discord will often ignore the type you provided if you aren't consistent.

  • Responding to an ephemeral Interaction after editing the initial response, which may result in a public response in some situations.

Additionally, as the Interaction system is internally implemented using Discord's webhook system, changes that Discord makes to how webhook messages work may also affect your Interactions.

For example, a 2023 change to webhook permissions was made because slash command responses were able to mention @everyone when they otherwise shouldn't be able to. In this instance, Discord normalized webhook permissions to match those of the user who created the webhook. This fixed the problem with slash commands but limited the emoji that may be sent using a webhook to those from guilds the webhook creator is present on.

Interaction Context Types

Discord supports two main types of Interaction response — ephemeral and public. Ephemeral responses are only visible to the user that triggered the Interaction, whereas public responses are visible to everyone that has access to the current channel.

Because Discord's Interactions can behave strangely if they aren't used how Discord expects them to be, Kord Extensions provides specific context types that help you to avoid unexpected behaviors. These types expect you to work with one of the main Interaction types, warning you when you attempt to do something that might not do what you expect.

These context types inherit the InteractionContext type, and are split by Interaction response types:

  • EphemeralInteractionContext for ephemeral Interaction responses.

  • PublicInteractionContext for public Interaction responses.

These types provide an identical API surface, allowing you to respond to Interactions easily without accidentally specifying the wrong type of response. The InteractionContext type takes several generic type parameters, with the following used in the tables below:

Builders

Name

Receiver

Description

edit

InteractionResponseModifyBuilder

Edit the first Interaction response, regardless of whether (or how many times) this Interaction has been responded to. May be called before a response has been sent, as the first Interaction response is always a "bot is thinking" message until this function (or one of the response functions) is called.

respond

FollowupMessageCreateBuilder

Respond to the Interaction with a follow-up matching the current Interaction response type.

respondOpposite

FollowupMessageCreateBuilder

Respond to the Interaction with a follow-up with the opposite type to the current Interaction response type. While Discord's API allows you to do this, it will rarely do what you expect. This function is provided only for advanced use-cases that need it.

Paginator Builders

editingPaginator

PaginatorBuilder

Convenience function, allowing you to easily create a button-based paginator by editing the first response to this Interaction. The following parameters are supported:

  • defaultGroup = "" - The default paginator group.

  • locale = null - The locale to use for this paginator's buttons. In a command or component context, you'll want to provide the result of getLocale() here.

Note: This will not send the paginator automatically. You'll need to call the send function on this function's return value to send it.

For more information on paginators (and the paginator builder), see the dedicated documentation.

respondingPaginator

PaginatorBuilder

Convenience function, allowing you to easily create a button-based paginator in an Interaction follow-up message. The following parameters are supported:

  • defaultGroup = "" - The default paginator group.

  • locale = null - The locale to use for this paginator's buttons. In a command or component context, you'll want to provide the result of getLocale() here.

Note: This will not send the paginator automatically. You'll need to call the send function on this function's return value to send it.

For more information on paginators (and the paginator builder), see the dedicated documentation.

Properties

Name

Type

Description

interactionResponse

ResponseBehavior

The current Interaction response object that this context is working with.

Last modified: 20 November 2024
ExtensionsCommands