Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/Kraigie/nostrum
Elixir Discord Library
https://github.com/Kraigie/nostrum
bot discord discord-api discord-bot discordapp elixir library nostrum
Last synced: about 2 months ago
JSON representation
Elixir Discord Library
- Host: GitHub
- URL: https://github.com/Kraigie/nostrum
- Owner: Kraigie
- License: mit
- Created: 2016-08-26T21:18:34.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2024-05-01T22:15:32.000Z (7 months ago)
- Last Synced: 2024-05-02T02:39:45.025Z (7 months ago)
- Topics: bot, discord, discord-api, discord-bot, discordapp, elixir, library, nostrum
- Language: Elixir
- Homepage: https://kraigie.github.io/nostrum/
- Size: 65.5 MB
- Stars: 574
- Watchers: 13
- Forks: 122
- Open Issues: 34
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- discord-api-libs - nostrum - Elixir Discord Library (Libraries / Elixir)
- awesome-discord - Nostrum
- awesome-discord-bot-tools - Nostrum - An Elixir library for the Discord API. (Libraries / Elixir)
- awesome-discord-bot-tools - Nostrum - An Elixir library for the Discord API. (Libraries / Elixir)
README
# Nostrum
[](https://github.com/Kraigie/nostrum/actions)
[](https://discord.gg/2Bgn8nW)
[](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.
- Support for multi-node distribution of caches and internal state.
- Listening and sending voice data, with helpers for common functionality.
- Automatic, configurable maintenance of local caches of Discord data, with
extensive query support and cache swapping 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/.
Edit or create your config file at `/config/config.exs`. To run Nostrum you
need the following two fields:
```elixir
config :nostrum,
token: "666" # The token of your bot as a string
```
> **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 `[:nostrum, :gateway_intents]`
configuration key.
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 started in some fashion to capture events. See
[here](https://github.com/Kraigie/nostrum/blob/master/examples/event_consumer.ex)
for a full example.
```elixir
defmodule ExampleConsumer do
use Nostrum.Consumer
alias Nostrum.Api
def handle_event({:MESSAGE_CREATE, msg, _ws_state}) do
case msg.content do
"ping!" ->
Api.create_message(msg.channel_id, "I copy and pasted this code")
_ ->
:ignore
end
end
end
```
You should start this under a supervisor or application:
```elixir
defmodule MyApp.Application do
use Application
def start(_type, _args) do
children = [ExampleConsumer]
Supervisor.start_link(children, strategy: :one_for_one)
end
end
```
For testing, you can start it from `iex`:
```elixir
iex()> ExampleConsumer.start_link()
{:ok, #PID<0.208.0>}
```
## Getting Help
If you need help, visit `#elixir_nostrum` on the unofficial Discord API guild!
[](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)