Interactions & Responses
Discord Interactions provide modern, structured interfaces for user input. Lunibee offers typed structures for all interaction types with built-in response management (initial reply, deferred replies, ephemeral flags, edits, follow-ups, and modal popups).
The Interaction Lifecycle
Section titled âThe Interaction LifecycleâWhen a user triggers an interaction, Discord sends an INTERACTION_CREATE payload over the Gateway. Discord requires an initial acknowledgment within 3 seconds (either replying directly, deferring the reply, or opening a modal).
sequenceDiagram actor User participant Discord participant Lunibee
User->>Discord: Uses /ban or clicks Button Discord->>Lunibee: INTERACTION_CREATE Gateway Event alt Fast Reply (< 3 seconds) Lunibee->>Discord: interaction.reply({ content: "Done!" }) else Long Running Task (> 3 seconds) Lunibee->>Discord: interaction.deferReply() Note over Lunibee: Perform Database / Async operation Lunibee->>Discord: interaction.editReply({ content: "Operation complete!" }) else Modal Popup Lunibee->>Discord: interaction.showModal(modal) endChatInputCommandInteraction (Slash Commands)
Section titled âChatInputCommandInteraction (Slash Commands)âTriggered when a user executes a Slash Command.
import { Client, CreateEmbed, MessageFlags, User } from "lunibee";
client.on("interactionCreate", async (interaction) => { if (!interaction.isChatInputCommand()) return;
const { commandName, options } = interaction;
if (commandName === "userinfo") { // getUser() returns Discord's raw user data; wrap it in User for the helpers. const picked = options.getUser("target"); const targetUser = picked ? new User(picked) : interaction.user; if (!targetUser) return;
const embed = new CreateEmbed() .setTitle(`User Info - ${targetUser.username}`) .setThumbnail(`https://cdn.discordapp.com/avatars/${targetUser.id}/${targetUser.avatar}.png`) .addFields( { name: "User ID", value: targetUser.id, inline: true }, { name: "Bot Account", value: targetUser.bot ? "Yes" : "No", inline: true } );
await interaction.reply({ embeds: [embed], ephemeral: true, // Visible only to the command runner }); }});import { Client, CreateEmbed, MessageFlags } from "lunibee";
client.on("interactionCreate", async (interaction) => { if (!interaction.isChatInputCommand()) return;
const { commandName, options } = interaction;
if (commandName === "userinfo") { const targetUser = options.getUser("target") ?? interaction.user;
const embed = new CreateEmbed() .setTitle(`User Info - ${targetUser.username}`) .setThumbnail(`https://cdn.discordapp.com/avatars/${targetUser.id}/${targetUser.avatar}.png`) .addFields( { name: "User ID", value: targetUser.id, inline: true }, { name: "Bot Account", value: targetUser.bot ? "Yes" : "No", inline: true } );
await interaction.reply({ embeds: [embed], ephemeral: true, // Visible only to the command runner }); }});Reading Command Options
Section titled âReading Command Optionsâoptions.getString(name, required?): Returnsstring | nulloptions.getInteger(name, required?): Returnsnumber | nulloptions.getNumber(name, required?): Returnsnumber | nulloptions.getBoolean(name, required?): Returnsboolean | nulloptions.getUser(name, required?): ReturnsAPIUser | nulloptions.getChannel(name, required?): Returns the resolved channel data ornulloptions.getRole(name, required?): Returns the resolved role data ornulloptions.getAttachment(name, required?): Returns the resolved attachment data ornulloptions.getSubcommand(required?): Returns the executed subcommandâs name, ornull
With required: true a getter returns a non-null value and throws when the option is missing.
ButtonInteraction & StringSelectInteraction
Section titled âButtonInteraction & StringSelectInteractionâTriggered when a user clicks a button or selects options in a dropdown.
client.on("interactionCreate", async (interaction) => { if (!interaction.isMessageComponent()) return;
const { customId } = interaction;
// Handle Button Clicks if (customId === "btn_verify") { await interaction.deferReply({ ephemeral: true });
// Assign verified role await interaction.member?.addRole("123456789012345678");
await interaction.editReply({ content: "â
You have been verified and granted access!", }); }
// Handle Select Menu Changes if (customId === "select_color_roles") { const selectedValues = interaction.values; // string[] array of selected choice values await interaction.reply({ content: `Selected colors: ${selectedValues.join(", ")}`, ephemeral: true, }); }});client.on("interactionCreate", async (interaction) => { if (!interaction.isMessageComponent()) return;
const { customId } = interaction;
// Handle Button Clicks if (customId === "btn_verify") { await interaction.deferReply({ ephemeral: true });
// Assign verified role await interaction.member?.addRole("123456789012345678");
await interaction.editReply({ content: "â
You have been verified and granted access!", }); }
// Handle Select Menu Changes if (customId === "select_color_roles") { const selectedValues = interaction.values; // string[] array of selected choice values await interaction.reply({ content: `Selected colors: ${selectedValues.join(", ")}`, ephemeral: true, }); }});Type guards
Section titled âType guardsâBesides isChatInputCommand(), isMessageComponent(), isModalSubmit() and
isAutocomplete(), component interactions can be narrowed by component type:
isButton(), isStringSelectMenu(), isUserSelectMenu(), isRoleSelectMenu(),
isMentionableSelectMenu(), isChannelSelectMenu() and isAnySelectMenu().
ModalSubmitInteraction
Section titled âModalSubmitInteractionâTriggered when a user submits a modal popup.
client.on("interactionCreate", async (interaction) => { if (!interaction.isModalSubmit()) return;
if (interaction.customId === "modal_ticket") { const subject = interaction.getRequiredInputValue("ticket_subject"); const description = interaction.getRequiredInputValue("ticket_description");
await interaction.reply({ content: `Ticket created! **Subject:** ${subject}`, ephemeral: true, }); }});client.on("interactionCreate", async (interaction) => { if (!interaction.isModalSubmit()) return;
if (interaction.customId === "modal_ticket") { const subject = interaction.getRequiredInputValue("ticket_subject"); const description = interaction.getRequiredInputValue("ticket_description");
await interaction.reply({ content: `Ticket created! **Subject:** ${subject}`, ephemeral: true, }); }});AutocompleteInteraction
Section titled âAutocompleteInteractionâProvides live suggestions as a user types into a slash command option.
client.on("interactionCreate", async (interaction) => { if (!interaction.isAutocomplete()) return;
const focusedOption = interaction.options.getFocused(true); // { name, value }
if (focusedOption.name === "tag") { const allTags = ["javascript", "typescript", "bun", "discord", "rust"]; const typed = String(focusedOption.value ?? "").toLowerCase(); const filtered = allTags.filter(t => t.startsWith(typed));
await interaction.respond( filtered.map(tag => ({ name: tag, value: tag })) ); }});client.on("interactionCreate", async (interaction) => { if (!interaction.isAutocomplete()) return;
const focusedOption = interaction.options.getFocused(true); // { name, value }
if (focusedOption.name === "tag") { const allTags = ["javascript", "typescript", "bun", "discord", "rust"]; const typed = String(focusedOption.value ?? "").toLowerCase(); const filtered = allTags.filter(t => t.startsWith(typed));
await interaction.respond( filtered.map(tag => ({ name: tag, value: tag })) ); }});Response Methods Reference
Section titled âResponse Methods Referenceâ| Method | Description |
|---|---|
interaction.reply(options) |
Sends the initial message response (accepts content, embeds, components, ephemeral). |
interaction.deferReply(options?) |
Acknowledges the interaction immediately and displays a thinking state (ephemeral?). |
interaction.editReply(options) |
Edits the initial response (useful after deferring). |
interaction.deleteReply() |
Deletes the initial interaction response. |
interaction.followUp(options) |
Sends secondary follow-up messages linked to the interaction. |
interaction.showModal(modal) |
Pops up an interactive modal dialog for user input. |
Acknowledgement, Follow-ups and Expiry
Section titled âAcknowledgement, Follow-ups and ExpiryâAn interaction can be acknowledged once. reply, deferReply, update,
deferUpdate, showModal and autocomplete respond share one guard, so two
concurrent calls cannot both send; a failed acknowledgement can be retried.
await interaction.deferReply(true); // ephemeralawait interaction.editReply({ content: "Done" });const reply = await interaction.fetchReply();
const note = (await interaction.followUp({ content: "FYI", ephemeral: true })) as { id: string };await interaction.editFollowUp(note.id, "Updated");await interaction.deleteFollowUp(note.id);
interaction.user; // invoking User (guild or DM)interaction.member; // GuildMember, or null outside a guildinteraction.isExpired; // tokens stop working 15 minutes after creation{ ephemeral: true } is turned into Discordâs flag on replies, edits and
follow-ups.