Skip to content

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


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

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
});
}
});
  • options.getString(name, required?): Returns string | null
  • options.getInteger(name, required?): Returns number | null
  • options.getNumber(name, required?): Returns number | null
  • options.getBoolean(name, required?): Returns boolean | null
  • options.getUser(name, required?): Returns APIUser | null
  • options.getChannel(name, required?): Returns the resolved channel data or null
  • options.getRole(name, required?): Returns the resolved role data or null
  • options.getAttachment(name, required?): Returns the resolved attachment data or null
  • options.getSubcommand(required?): Returns the executed subcommand’s name, or null

With required: true a getter returns a non-null value and throws when the option is missing.


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,
});
}
});

Besides isChatInputCommand(), isMessageComponent(), isModalSubmit() and isAutocomplete(), component interactions can be narrowed by component type: isButton(), isStringSelectMenu(), isUserSelectMenu(), isRoleSelectMenu(), isMentionableSelectMenu(), isChannelSelectMenu() and isAnySelectMenu().

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,
});
}
});

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 }))
);
}
});

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.

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); // ephemeral
await 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 guild
interaction.isExpired; // tokens stop working 15 minutes after creation

{ ephemeral: true } is turned into Discord’s flag on replies, edits and follow-ups.