Supervisor for a bot along with all its associated components.

Usage

In your supervisor tree, write:

bot_options = %{
  consumer: MyBot.Consumer,
  # This is an example and includes privileged intents, but
  # should provide a useful set of intents for bots. Feel
  # free to adjust this as you see fit.
  intents: [
    :direct_messages,
    :guild_bans,
    :guild_members,
    :guild_message_reactions,
    :guild_messages,
    :guilds,
    :message_content
  ],
  wrapped_token: fn -> System.fetch_env!("BOT_TOKEN") end,
}
children = [
  {Nostrum.Bot, bot_options}
]

See bot_options/0 for which options you can configure here. You may also configure supervisor_options/0, which allow you to customize the options we start the Supervisor with by defining your child in the form {Nostrum.Bot, {bot_options, supervisor_options}}, but the default supervisor_options/0 should suit most needs.

Migration guide

If you are still using the old way of deploying nostrum, please do the following:

1. Remove the :nostrum, :token configuration option. nostrum will then assume that you are starting it as part of your own supervision tree, and automatic startup via the application is disabled.

2. Remove your consumer from your application supervisor tree.

3. In your supervisor tree, add the bot_options described above, and add Nostrum.Bot to your supervisor tree as described above. For the :intents setting, cut the value you previously had in your config.exs and use it here. Do the same with :num_shards, renaming it to :shards on the bot_options map. You can then remove the old config values.

4. In your consumer, change use Nostrum.Consumer to @behaviour Nostrum.Consumer.

5. In your consumer, add a default event handling clause for unmatched events at the end of the module, such as:

  def handle_event(_), do: :ok

Multiple Bots

Nostrum allows you to start multiple bots under your supervision tree. If you are calling a function that interacts with an API specific to a bot - Rest, Cache, Voice, etc. - nostrum needs to determine which bot to call it for. It does this with a bot Registry and process dictionaries so that you don't have to pass an additional argument to every function.

Inside the handle_event/1 callback in your consumer, the calling process already has the context of the bot that generated the event for any API calls that follow.

If you have a single bot running and need to call an API asynchronously, i.e. not as a response to a gateway event in your consumer, nostrum will automatically determine the bot.

However, if you have multiple bots running and you need to make unprompted bot calls, you will need to assist nostrum by setting the process's context in one of three ways:

• Nostrum.Bot.with_bot(MyBot, fn -> ... end) to wrap the API function calls
• use Nostrum.Bot, name: MyBot at the top of the module where the API-calling functions are defined
• Nostrum.Bot.set_bot_name(MyBot) dynamically before each API call

You are free to call API functions from newly-spawned tasks as nostrum will search the process dictionaries of a few generations of calling processes to find the bot context.

Note that, unless explicitly configured otherwise (see bot_options/0), nostrum uses the user ID from the bot's token as the bot name. If you wish to dynamically determine the user ID from the token, use Nostrum.Token.decode_token!/1.