# Nostrum

[![Build Status](](
[![Join Discord](](

An [Elixir]( library for the Discord API.

It is highly recommended to check out the
[documentation]( first. It includes all of the
information listed here and more.

## Installation

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

def deps do
  [{:nostrum, "~> 0.4"}]

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

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

Documentation for master can be found at

Edit or create your config file at `/config/config.exs`. To run Nostrum you
need the following two fields:

config :nostrum,
  token: "666" # The token of your bot as a string

For more information about the differences between dev and stable as well as
additional config parameters, please see the

## Example Usage
The below module needs to be started in some fashion to capture events. See
for a full example.

defmodule ExampleConsumer do
  use Nostrum.Consumer

  alias Nostrum.Api

  def start_link do

  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")
      _ ->

  # Default event handler, if you don't include this, your consumer WILL crash if
  # you don't have a method definition for each event type.
  def handle_event(_event) do

Although it's recommended to run under a supervisor, you could start it from `iex`.
  iex()> ExampleConsumer.start
  {:ok, #PID<0.208.0>}

## Getting Help

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

[![Discord API](](

## License