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
Section titled “Import”import { CommandInteraction, ComponentInteraction, ModalSubmitInteraction, AutocompleteInteraction, Interaction,} from "lunibee";import { CommandInteraction, ComponentInteraction, ModalSubmitInteraction, AutocompleteInteraction, Interaction,} from "lunibee";Common Properties (all types)
Section titled “Common Properties (all types)”| 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. |
Common Methods (all types)
Section titled “Common Methods (all types)”| 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. |
Type Guards
Section titled “Type Guards”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 }});client.on("interactionCreate", async (interaction) => { if (interaction.isChatInputCommand()) { // CommandInteraction } else if (interaction.isMessageComponent()) { // ComponentInteraction } else if (interaction.isModalSubmit()) { // ModalSubmitInteraction } else if (interaction.isAutocomplete()) { // AutocompleteInteraction }});CommandInteraction — Slash Commands
Section titled “CommandInteraction — Slash Commands”Triggered when a user runs a slash command (/commandname).
Additional Properties
Section titled “Additional Properties”| Property | Type | Description |
|---|---|---|
commandName |
string |
Name of the slash command. |
options |
CommandOptions |
Typed option resolver. |
Reading Options
Section titled “Reading Options”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"; // ... }});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"; // ... }});CommandOptions Methods
Section titled “CommandOptions Methods”| 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.
Full Example
Section titled “Full Example”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] }); }});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.
Additional Properties
Section titled “Additional Properties”| 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. |
Additional Methods
Section titled “Additional Methods”| Method | Description |
|---|---|
update(options) |
Updates the originating message instead of sending a new reply. |
deferUpdate(options?) |
Defers without showing a loading state (for components). |
Example
Section titled “Example”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 }); }});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.
Additional Properties
Section titled “Additional Properties”| Property | Type | Description |
|---|---|---|
customId |
string |
The customId set on the modal. |
Methods
Section titled “Methods”| 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. |
Reading Field Values
Section titled “Reading Field Values”if (!interaction.isModalSubmit()) return;const value = interaction.getRequiredInputValue("field_custom_id");const value = interaction.getRequiredInputValue("field_custom_id");Example
Section titled “Example”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, }); }});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(). Userespond()to send choices.
Additional Properties
Section titled “Additional Properties”| 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. |
respond(choices)
Section titled “respond(choices)”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" },]);await interaction.respond([ { name: "Option A", value: "a" }, { name: "Option B", value: "b" },]);Example
Section titled “Example”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 }))); }});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 }))); }});showModal(modal) — Opening a Modal
Section titled “showModal(modal) — Opening a Modal”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);});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().addComponents( new CreateTextInput() .setCustomId("reason") .setLabel("Reason") .setStyle(TextInputType.Paragraph) .setRequired(true), ), );
await interaction.showModal(modal);});0.2.0 Additions
Section titled “0.2.0 Additions”| 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.
0.2.1 Additions
Section titled “0.2.1 Additions”deferReply(options)also takes{ ephemeral: true }(a boolean still works).showModal(modal)takes aCreateModaldirectly, so no.toJSON()or cast is needed.awaitModalSubmit({ time, customId?, filter? })waits for this user to submit a modal and returns theModalSubmitInteraction.timeis required.reply,editReply,followUpandupdateacceptfiles: [{ name, data, contentType? }].interaction.membercan 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"ornull, 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…" messageconst 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.
InteractionResponse and createInteraction
Section titled “InteractionResponse and createInteraction”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.