The behaviour for your bot module.

A bot module declares its application commands and implements callbacks for whatever it wants to react to. Every callback is optional, and each call runs in its own supervised process.

defmodule MyBot do
  use Lingo.Bot

  command "ping", "Responds with pong"

  command "ban", "Ban a user",
    default_member_permissions: Lingo.Permissions.from_list([:ban_members]),
    options: [
      user(:target, "Who to ban", required: true),
      string(:reason, "Why")
    ]

  @impl true
  def handle_command("ping", ctx), do: reply!(ctx, "Pong!")

  def handle_command("ban", ctx) do
    Lingo.Api.Ban.create(ctx.guild_id, option(ctx, :target), reason: option(ctx, :reason))
    ephemeral!(ctx, "Banned.")
  end

  @impl true
  def handle_component("vote:" <> choice, ctx), do: update!(ctx, "You voted #{choice}")

  @impl true
  def handle_event(:message_create, %{content: "hello"} = msg),
    do: Lingo.Api.Message.create(msg.channel_id, "Hello back!")
end

use Lingo.Bot imports the declaration macros from Lingo.Bot.Commands, the option builders from Lingo.Bot.Options and the functions of Lingo.Context. If your module calls a function of its own with the same name, such as get_user/2, leave that one out:

use Lingo.Bot
import Lingo.Context, except: [get_user: 2]

You only write the clauses you care about: anything that matches none of them is ignored (an unknown command is logged). When you don't implement handle_component/2 or handle_modal/2 at all, those interactions reach handle_event/2 as :interaction_create instead.

Starting

use Lingo.Bot gives your module child_spec/1 and start_link/1, so it goes straight into a supervision tree:

children = [
  {MyBot, token: System.fetch_env!("BOT_TOKEN"), intents: [:guilds, :guild_messages]}
]

Options:

• :token (required) - the bot token
• :name - names this bot, for Lingo.with_bot/2; defaults to the module. Lets one module run as several bots.
• :intents - gateway intents, as atoms or a bitfield (default [:guilds, :guild_messages])
• :register_commands - registers the declared commands once all shards are ready: :global, {:guild, id} or {:guilds, ids} (default false). Lingo.register_commands/1 does it on demand.
• :cache - which resources to cache and their policies; nothing is cached by default. See Lingo.Cache.
• :sharding - :count (default :auto); :ids, the shards this node runs (needs :count); :auto_reshard, true (checks hourly) or an interval in ms, to reshard when Discord recommends more shards. See Lingo.Gateway.
• :endpoint - receives interactions and webhook events over HTTP; see Lingo.Endpoint
• :gateway - false to run without a gateway connection (see Lingo.Endpoint), or :encoding (:json, the default, or :etf), :compression (:zlib, the default, :zstd on OTP 28+, or :none) and :session_store, a Lingo.Gateway.SessionStore module or {module, opts} to resume sessions after a restart
• :presence - the initial :status, :text and :activity
• :rate_limit - :max_wait, the longest an API call waits on rate limits in ms (default :infinity, see Lingo.with_max_wait/2)
• :rest - :base_url, to send API calls through a REST proxy that handles rate limits for every node and process, such as "http://proxy.internal/api/v10" (default Discord's API). Each node still follows the limits the proxy's answers carry, but stops sharing them with the other nodes, which the proxy does.