Skip to content

Interactions

Lunibee provides typed interaction classes for every Discord interaction type. All interactions share a common base with lifecycle methods for replying, deferring, and following up.

import {
CommandInteraction,
ComponentInteraction,
ModalSubmitInteraction,
AutocompleteInteraction,
Interaction,
} from "lunibee";
Property Type Description
id string Interaction snowflake ID.
applicationId string The application’s ID.
token string Interaction token (valid for 15 minutes).
guildId string | undefined Guild ID if the interaction happened in a server.
channelId string | undefined Channel ID.
user User | null The user who triggered the interaction.
member GuildMember | null The guild member who triggered it (null outside a guild).
type number Interaction type.
data InteractionData The raw interaction payload.
replied / deferred boolean Whether the initial response was sent or deferred.
entitlements readonly APIEntitlement[] What the user (and guild) own from your SKUs; hasEntitlement(skuId) checks for an active one.
Method Description
reply(options) Sends the initial response. Accepts a string or content, embeds, components, ephemeral, files, poll. Throws if the interaction was already acknowledged.
deferReply(options?) Acknowledges immediately, showing a loading state. Throws if already acknowledged.
editReply(options) Edits the initial response (after reply or deferReply; throws before).
deleteReply() Deletes the initial response (throws before acknowledging).
update(options) Edits the message a component is on, as the initial response.
followUp(options) Sends a follow-up message.

Use type guard methods on the base Interaction to narrow to the correct subtype. Besides the four below there are isCommand() (any application command), isContextMenuCommand(), isUserContextMenuCommand(), isMessageContextMenuCommand(), and for components isButton(), isStringSelectMenu(), isUserSelectMenu(), isRoleSelectMenu(), isMentionableSelectMenu(), isChannelSelectMenu() and isAnySelectMenu(). isChatInputCommand() is false for context-menu commands.

client.on("interactionCreate", async (interaction) => {
if (interaction.isChatInputCommand()) {
// CommandInteraction
} else if (interaction.isMessageComponent()) {
// ComponentInteraction
} else if (interaction.isModalSubmit()) {
// ModalSubmitInteraction
} else if (interaction.isAutocomplete()) {
// AutocompleteInteraction
}
});

Triggered when a user runs a slash command (/commandname).

Property Type Description
commandName string Name of the slash command.
options CommandOptions Typed option resolver.
client.on("interactionCreate", async (interaction) => {
if (!interaction.isChatInputCommand()) return;
const { commandName, options } = interaction;
if (commandName === "ban") {
const target = options.getUser("target", true);
const reason = options.getString("reason") ?? "No reason provided";
// ...
}
});
Method Returns Description
getString(name, required?) string | null Gets a string option.
getInteger(name, required?) number | null Gets an integer option.
getNumber(name, required?) number | null Gets a float option.
getBoolean(name, required?) boolean | null Gets a boolean option.
getUser(name, required?) object | null Gets the resolved user data.
getChannel(name, required?) object | null Gets the resolved channel data.
getRole(name, required?) object | null Gets the resolved role data.
getMentionable(name, required?) object | null Gets the resolved user or role data.
getAttachment(name, required?) object | null Gets the attachment data.
getFocused(full?) value or option Autocomplete: the focused option’s value, or the whole option with true. Throws when none is focused.
raw readonly APIInteractionDataOption[] The raw option list.
getSubcommand(required?) string | null Gets the subcommand name.
getSubcommandGroup(required?) string | null Gets the subcommand group name.

When required = true, the method throws a TypeError if the option is missing (or its resolved data is). An option of a different type counts as missing.

client.on("interactionCreate", async (interaction) => {
if (!interaction.isChatInputCommand()) return;
if (interaction.commandName === "userinfo") {
await interaction.deferReply();
const user = interaction.options.getUser("target") ?? interaction.user;
const embed = new CreateEmbed()
.setTitle(`User Info: ${(user as any).username}`)
.addFields({ name: "ID", value: (user as any).id });
await interaction.editReply({ embeds: [embed] });
}
});

ContextMenuCommandInteraction — User and Message Commands

Section titled “ContextMenuCommandInteraction — User and Message Commands”

A CommandInteraction for a right-click command (isContextMenuCommand()). It adds targetId (the user or message ID), targetUser (User \| null), targetMember (GuildMember \| null, in a guild) and targetMessage (Message \| null).


ComponentInteraction — Buttons & Select Menus

Section titled “ComponentInteraction — Buttons & Select Menus”

Triggered when a user clicks a button or chooses a select menu option.

Property Type Description
customId string The customId set on the component.
componentType number Component type (2 = Button, 3 = String Select, etc.).
values string[] Selected values (only for select menus).
messageId string | undefined The ID of the message the component is on.
Method Description
update(options) Updates the originating message instead of sending a new reply.
deferUpdate(options?) Defers without showing a loading state (for components).
client.on("interactionCreate", async (interaction) => {
if (!interaction.isMessageComponent()) return;
if (interaction.customId === "btn_confirm") {
await interaction.update({ content: "✅ Confirmed!", components: [] });
}
if (interaction.customId === "select_color") {
const colors = interaction.values; // e.g. ["red", "blue"]
await interaction.reply({ content: `You selected: ${colors.join(", ")}`, ephemeral: true });
}
});

ModalSubmitInteraction — Modal Submissions

Section titled “ModalSubmitInteraction — Modal Submissions”

Triggered when a user submits a modal form.

Property Type Description
customId string The customId set on the modal.
Method Description
getInputValue(customId) The submitted text of a text input, or undefined.
getRequiredInputValue(customId) The same, but throws a TypeError when the input is missing.
if (!interaction.isModalSubmit()) return;
const value = interaction.getRequiredInputValue("field_custom_id");
client.on("interactionCreate", async (interaction) => {
if (!interaction.isModalSubmit()) return;
if (interaction.customId === "feedback_modal") {
const subject = interaction.getRequiredInputValue("subject");
const body = interaction.getRequiredInputValue("body");
await interaction.reply({
content: `📨 Feedback received!\n**${subject}**\n${body}`,
ephemeral: true,
});
}
});

AutocompleteInteraction — Live Suggestions

Section titled “AutocompleteInteraction — Live Suggestions”

Triggered as a user types in a slash command option with autocomplete: true.

[!IMPORTANT] Autocomplete interactions cannot use reply(). Use respond() to send choices.

Property Type Description
commandName string The slash command name.
options CommandOptions Resolved options (use getFocused for the active field).
focusedOption { name, value, type } | undefined The option the user is typing in.

Sends up to 25 autocomplete choice objects:

// inside `if (interaction.isAutocomplete()) { … }`
if (!interaction.isAutocomplete()) return;
await interaction.respond([
{ name: "Option A", value: "a" },
{ name: "Option B", value: "b" },
]);
client.on("interactionCreate", async (interaction) => {
if (!interaction.isAutocomplete()) return;
const focused = interaction.options.getFocused(true);
if (focused.name === "tag") {
const tags = ["typescript", "javascript", "bun", "discord"];
const filtered = tags.filter(t => t.startsWith(String(focused.value ?? "").toLowerCase()));
await interaction.respond(filtered.map(t => ({ name: t, value: t })));
}
});

Any non-autocomplete interaction can show a modal as its initial response:

client.on("interactionCreate", async (interaction) => {
if (!interaction.isChatInputCommand() || interaction.commandName !== "report") return;
const modal = new CreateModal()
.setCustomId("report_modal")
.setTitle("Report a User")
.addComponents(
new CreateActionRow<CreateTextInput>().addComponents(
new CreateTextInput()
.setCustomId("reason")
.setLabel("Reason")
.setStyle(TextInputType.Paragraph)
.setRequired(true),
),
);
await interaction.showModal(modal);
});
Member Description
fetchReply() Fetches the original response (after acknowledging).
editFollowUp(id, options) / deleteFollowUp(id) Edit or delete a follow-up message.
user / member Invoking user, and member inside a guild (null otherwise).
createdTimestamp / expiresAt / isExpired Token lifetime (15 minutes).

Only one initial response can be sent; concurrent reply/defer/update calls throw instead of racing, and a failed acknowledgement can be retried. { ephemeral: true } works on replies, edits and follow-ups.

  • deferReply(options) also takes { ephemeral: true } (a boolean still works).
  • showModal(modal) takes a CreateModal directly, so no .toJSON() or cast is needed.
  • awaitModalSubmit({ time, customId?, filter? }) waits for this user to submit a modal and returns the ModalSubmitInteraction. time is required.
  • reply, editReply, followUp and update accept files: [{ name, data, contentType? }].
  • interaction.member can act on itself (kick(), timeout()…), as can other members from the client.
  • ComponentInteraction.messageId: the ID of the message the component is on.
  • options.getMentionableType(name): "user", "role" or null, for mentionable options.
await interaction.showModal(
new CreateModal().setCustomId("report").setTitle("Report")
.addTextInputs(new CreateTextInput().setCustomId("why").setLabel("What happened?").setStyle(TextInputType.Paragraph)),
);
const submitted = await interaction.awaitModalSubmit({ time: 5 * 60_000, customId: "report" });
await submitted.reply({ content: "Thanks!", ephemeral: true });

The created message in one request (0.2.2)

Section titled “The created message in one request (0.2.2)”

reply(), update(), deferReply() and deferUpdate() accept withResponse: true. Discord then returns the message with the acknowledgement, so there is no second request to fetchReply():

const message = await interaction.reply({ content: "Pick one", components: [row], withResponse: true });
const collector = message?.createComponentCollector({ time: 60_000 });
const placeholder = await interaction.deferReply({ ephemeral: true, withResponse: true }); // the "thinking…" message
const updated = await componentInteraction.update({ content: "Saved", withResponse: true });

The result is a Message, or null if Discord sent no message. Without withResponse the methods behave exactly as before. fetchReply() still works.

reply(), deferReply() and the other response methods build an InteractionResponse for you. Build one directly only when answering Discord’s HTTP interactions endpoint yourself, where the response is the HTTP body:

Member Description
new InteractionResponse(type, data?) A callback of type (Discord’s InteractionCallbackType) with optional message data.
InteractionResponse.message(options) Type 4: reply with a message.
InteractionResponse.defer(ephemeral?) Type 5: acknowledge now, edit the reply later.
InteractionResponse.pong() Type 1: answer a ping.
withResponse Ask Discord to return the created message (?with_response=true).
toJSON() The callback body.

createInteraction(client, data) turns a raw interaction payload into the matching class (CommandInteraction, ComponentInteraction, ModalSubmitInteraction, AutocompleteInteraction…). Client calls it for every INTERACTION_CREATE; use it when you receive interactions some other way, such as over HTTP.