nostrum

KO | EN

gitlite — search

#hacktoberfest #react #typescript #go #golang #android #machine-learning #rust #docker #java #cli #awesome-list #openai #mcp

(★ 724)

Elixir Discord Library

File Explorer

Download Latest Version (.zip)

- - docs.yml
  - test_and_lint.yml
- dependabot.yml
- - 2_minutes_hate.png
  - Collect_All_5.png
  - democracy_manifest.png
  - introducing_apple.png
  - it_has_been_x_days.psd
  - lost_his_chance.png
  - mission_control.png
  - testing_in_prod.png
  - use_nostrum.png
- - 0_10_0_release.png
  - 0_11_0_release.png
  - 0_6_0_release.png
  - 0_6_1_release.png
  - 0_7_0_forum_boogaloo.png
  - 0_7_0_release.png
  - 0_7_0_release_party.png
  - 0_7_0_worldwide_distribution.png
  - 0_8_0_release.png
  - 0_8_0_teaser.png
  - 0_9_0_release.png
  - 0_9_0_teaser.png
  - 0_9_1_release.png
- icon.png
- icon.psd
- README.md
- guild_cache_bench.exs
- member_cache_bench.exs
- README.md
- .credo.exs
- config.exs
- audio_player_example.ex
- cache.ex
- event_consumer.ex
- - gateway_compression.md
  - manual_sharding.md
  - multi_node.md
  - pluggable_caching.md
- - buttons.png
  - channel_types.png
  - danger_button.png
  - emoji_button.png
  - primary_button.png
  - secondary_button.png
  - select_menu.png
  - success_button.png
- - api.cheatmd
  - telemetry.cheatmd
  - voice.cheatmd
- - event_handling.md
  - state.md
  - voice.md
- - api.md
  - application_commands.md
  - gateway_intents.md
  - intro.md
- - api.ex
  - application.ex
  - bot.ex
  - constants.ex
  - consumer.ex
  - consumer_group.ex
  - dummy.ex
  - locale.ex
  - permission.ex
  - shard.ex
  - snowflake.ex
  - state_machine_translator.ex
  - telemetry_shim.ex
  - token.ex
  - util.ex
  - voice.ex
- nostrum_message_cache_qlc.erl
- README.md
- - api_server.ex
  - consumer_group_test.exs
  - locale_test.exs
  - noop_consumer.ex
  - permission_test.exs
  - snowflake_test.exs
  - token_test.exs
- example_embed.ex
- stubs.ex
- test_helper.exs
.dialyzer_ignore.exs
.formatter.exs
.gitignore
CONTRIBUTING.md
LICENSE
mix.exs
mix.lock
README.md

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Nostrum

[![Build Status](https://github.com/Kraigie/nostrum/workflows/Test%20&%20Lint/badge.svg)](https://github.com/Kraigie/nostrum/actions)
[![Join Discord](https://img.shields.io/badge/discord-join-7289DA.svg)](https://discord.gg/2Bgn8nW)
[![hex.pm](https://img.shields.io/hexpm/v/nostrum.svg)](https://hex.pm/packages/nostrum/)

An [Elixir](http://elixir-lang.org/) library for the Discord API. nostrum
supports the following:

- Clean REST API implementation and ratelimiting.
- Documented structs and abstractions over API objects.
- Automatic, configurable maintenance of local caches of Discord data, with
  cache swapping functionality.
- Ability to run multiple bots.
- Support for multi-node distribution of caches and internal state, including
  live migration of bots between nodes.
- Listening and sending voice data, with helpers for common functionality.

It is highly recommended to check out the [release
documentation](https://hexdocs.pm/nostrum/) first. It includes all of the
information listed here and more. **This README is for the master branch**,
which includes recent developments and may be unstable. If you want to live on
the edge regardless, you can check the [pre-release
documentation](https://kraigie.github.io/nostrum/).

## Installation

It is recommended to use a **stable** release by specifying a published
version from Hex:

```elixir
def deps do
  [{:nostrum, "~> 0.10"}]
end
```

For stable installations, documentation can be found at
https://hexdocs.pm/nostrum. However, if you want the latest changes and help
test the library, you can also install directly from GitHub:

```elixir
def deps do
  [{:nostrum, github: "Kraigie/nostrum"}]
end
```

Documentation for master can be found at https://kraigie.github.io/nostrum/.

See the [intro guide (master)](https://kraigie.github.io/nostrum/intro.html) or
the [intro guide for the stable release](https://hexdocs.pm/nostrum/intro.html)
to learn how to get started with your bot.

> **Note:** Due to Discord API changes, _in order to receive message content_ (e.g.
for non-slash commands or moderation tools), you need to have the "Message
Content Intent" enabled on your [Bot's application
settings](https://discord.com/developers/applications/), and the
`:message_content` intent specified in the `:intents` bot option.

For more information about the differences between dev and stable as well as
additional config parameters, please see the
[documentation](https://kraigie.github.io/nostrum/).

## Example Usage
The below module needs to be defined and configured as your bot's consumer to capture 
events. See [here](https://github.com/Kraigie/nostrum/blob/master/examples/event_consumer.ex)
for a full example.

```elixir
defmodule ExampleConsumer do
  @behaviour Nostrum.Consumer

alias Nostrum.Api.Message

def handle_event({:MESSAGE_CREATE, msg, _ws_state}) do
    case msg.content do
      "ping!" ->
        Message.create(msg.channel_id, "I copy and pasted this code")
      _ ->
        :ignore
    end
  end
end
```

You can define and start your bot under your application supervision tree:

```elixir
defmodule MyApp.Application do
  use Application

def start(_type, _args) do
    bot_options = %{
      consumer: ExampleConsumer,
      intents: [:direct_messages, :guild_messages, :message_content],
      wrapped_token: fn -> System.fetch_env!("BOT_TOKEN") end
    }

children = [{Nostrum.Bot, bot_options}]
    Supervisor.start_link(children, strategy: :one_for_one)
  end
end
```

You may also start bots dynamically at runtime from `iex`:

```elixir
iex()> bot_options = %{
...()>   consumer: ExampleConsumer,
...()>   intents: [:direct_messages, :guild_messages, :message_content],
...()>   wrapped_token: fn -> System.fetch_env!("BOT_TOKEN") end
...()> }
iex()> Supervisor.start_link([{Nostrum.Bot, bot_options}], strategy: :one_for_one)
{:ok, #PID<0.208.0>}
```

## Getting Help

If you need help, visit `#elixir_nostrum` on the unofficial Discord API guild!

[![Discord API](https://discord.com/api/guilds/81384788765712384/embed.png?style=banner3)](https://discord.gg/2Bgn8nW)

## Testimonials

> my first choice is always nostrum
> 
> **- big nutty, javascript developer**

> i would feed my baby the latest nostrum release
>
> **- also big nutty**

> i've used nostrum for 6 years and i have never been let down. [...]
>
> **- Broman, Discord API Expert**

## License
[MIT](https://opensource.org/licenses/MIT)

nostrum

File Explorer

Today's picks

Was this content helpful?

Recent Feedback

nostrum

File Explorer

Today's picks

Was this content helpful?

Recent Feedback

Download README