zephyr.discord

Send a message to a channel.

zephyr.discord.send_message(channel_id, { content = "Hello" })

Edit an existing channel message.

Omitted content, empty embeds, empty components, and empty attachments are not sent to Discord by the host builder.

Send a direct message to a user.

Respond to the current command, component, or modal interaction.

Must be called while handling an interaction-backed event.

zephyr.discord.respond({ content = "Pong", ephemeral = true })

Update the source message of the current component interaction.

Must be called while handling an interaction-backed event.

Open a modal for the current interaction.

zephyr.discord.open_modal({
  custom_id = "example:modal",
  title = "Example",
  inputs = {
    { custom_id = "subject", label = "Subject", style = "short", required = true },
  },
})

Suspend the handler until a component interaction matches a predicate.

Parks the calling handler until an incoming component (button) interaction satisfies predicate(event), then returns that interaction's payload. The matched interaction is acknowledged automatically; respond to it with edit_message/send_message using the returned ids. Returns nil if no match arrives within the timeout. The predicate runs for every candidate component, so keep it cheap and side-effect free.

local click = zephyr.discord.wait_for_component(function(e)
  return e.user_id == ctx.user_id and e.custom_id == "confirm"
end, { timeout = 30 })
if click ~= nil then
  zephyr.discord.edit_message(click.channel_id, click.message_id, { content = "Confirmed." })
end

Return the member count of a guild.

Create a text channel.

local channel_id = zephyr.discord.create_text_channel({
  guild_id = guild_id,
  name = "ticket-123",
  category_id = category_id,
})

Create a voice channel.

local channel_id = zephyr.discord.create_voice_channel({
  guild_id = guild_id,
  name = "match-42",
  permission_overwrites = {
    { kind = "member", id = user_id, allow = { "view_channel", "connect", "speak" } },
  },
})

Rename a channel.

Move a channel into (or out of) a category.

Pass nil or an empty category_id to remove the channel's category.

Delete a channel.

Set a permission overwrite on a channel.

Remove a permission overwrite from a channel.

Fetch recent messages from a channel in chronological order.

Return the voice channel a guild member is connected to.

Reads from the gateway voice-state cache. The bot requests the voice-state intent when any module declares discord:voice_states.

Return the number of users currently connected to a voice channel, excluding the bot itself.

Reads from the gateway voice-state cache. The bot requests the voice-state intent when any module declares discord:voice_states.

Kick a member from a guild.

Ban a member from a guild.

Lift a ban on a user.

Time a member out until a given timestamp.

Clear an active timeout on a member.

Assign a role to a member.

Unassign a role from a member.

Add a reaction to a message. Use to seed a reaction-role panel with its emoji.

-- React to a panel so members can click the emoji to self-assign a role.
zephyr.discord.add_reaction(channel_id, message_id, "🔔")

List a guild's roles (id, name, position, managed, color).

for _, role in ipairs(zephyr.discord.guild_roles(guild_id)) do
  print(role.name)
end

Set the bot's online status while keeping the current activity.

status accepts online, idle/away, dnd, and invisible/offline.

zephyr.discord.set_status("away")

Set or clear the bot's activity while keeping the current online status.

Pass nil to clear the activity. Activity tables accept kind (or type) as playing, listening, watching, competing, custom, or streaming; text can be provided as name, description, or state. Streaming activities also require url.

zephyr.discord.set_activity({ kind = "watching", description = "tickets" })

Set the bot's online status and activity together.

status accepts online, idle/away, dnd, and invisible/offline. activity uses the same table shape as set_activity; pass nil to clear the activity.

zephyr.discord.set_presence("dnd", { kind = "playing", name = "ranked matches" })