31 releases

new 0.5.13 Mar 10, 2019
0.5.11 Nov 12, 2018
0.5.5 Jul 25, 2018
0.5.1 Jan 31, 2018
0.1.0 Nov 30, 2016

#181 in Network programming

Download history 268/week @ 2018-11-25 104/week @ 2018-12-02 148/week @ 2018-12-09 168/week @ 2018-12-16 303/week @ 2018-12-23 92/week @ 2018-12-30 156/week @ 2019-01-06 133/week @ 2019-01-13 78/week @ 2019-01-20 77/week @ 2019-01-27 88/week @ 2019-02-03 61/week @ 2019-02-10 120/week @ 2019-02-17 104/week @ 2019-02-24 192/week @ 2019-03-03

552 downloads per month
Used in 2 crates

ISC license

20K SLoC

ci-badge docs-badge guild-badge crates.io version rust 1.31.1+ badge


serenity logo

Serenity is a Rust library for the Discord API.

View the examples on how to make and structure a bot.

Serenity supports bot login via the use of Client::new.

You may also check your tokens prior to login via the use of validate_token.

Once logged in, you may add handlers to your client to dispatch Events, by implementing the handlers in a trait, such as EventHandler::message. This will cause your handler to be called when a Event::MessageCreate is received. Each handler is given a Context, giving information about the event. See the client's module-level documentation.

The Shard is transparently handled by the library, removing unnecessary complexity. Sharded connections are automatically handled for you. See the gateway's documentation for more information.

A Cache is also provided for you. This will be updated automatically for you as data is received from the Discord API via events. When calling a method on a Context, the cache will first be searched for relevant data to avoid unnecessary HTTP requests to the Discord API. For more information, see the cache's module-level documentation.

Note that - although this documentation will try to be as up-to-date and accurate as possible - Discord hosts official documentation. If you need to be sure that some information piece is accurate, refer to their docs.

Example Bot

A basic ping-pong bot looks like:

#[macro_use] extern crate serenity;

use serenity::client::Client;
use serenity::prelude::EventHandler;
use serenity::framework::standard::StandardFramework;
use std::env;

struct Handler;

impl EventHandler for Handler {}

fn main() {
    // Login with a bot token from the environment
    let mut client = Client::new(&env::var("DISCORD_TOKEN").expect("token"), Handler)
        .expect("Error creating client");
        .configure(|c| c.prefix("~")) // set the bot's prefix to "~"
        .cmd("ping", ping));

    // start listening for events by starting a single shard
    if let Err(why) = client.start() {
        println!("An error occurred while running the client: {:?}", why);

command!(ping(_context, message) {
    let _ = message.reply("Pong!");

Full Examples

Full examples, detailing and explaining usage of the basic functionality of the library, can be found in the examples directory.


Add the following to your Cargo.toml file:

serenity = "0.5"

and to the top of your main.rs:

#[macro_use] extern crate serenity;

Serenity supports a minimum of Rust 1.31.1.


Features can be enabled or disabled by configuring the library through Cargo.toml:

default-features = false
features = ["pick", "your", "feature", "names", "here"]
version = "0.5"

The default features are: builder, cache, client, framework, gateway, http, model, standard_framework, and utils.

The following is a full list of features:

  • builder: The builders used in conjunction with models' methods.
  • cache: The cache will store information about guilds, channels, users, and other data, to avoid performing REST requests. If you are low on RAM, do not enable this.
  • client: A manager for shards and event handlers, abstracting away the work of handling shard events and updating the cache, if enabled.
  • framework: Enables the framework, which is a utility to allow simple command parsing, before/after command execution, prefix setting, and more.
  • gateway: A Shard, used as a higher-level interface for communicating with the Discord gateway over a WebSocket client.
  • http: Functions providing a wrapper over Discord's REST API at a low enough level that optional parameters can be provided at will via a JsonMap.
  • model: Method implementations for models, acting as helper methods over the HTTP functions.
  • standard_framework: A standard, default implementation of the Framework
  • utils: Utility functions for common use cases by users.
  • voice: Enables compilation of voice support, so that voice channels can be connected to and audio can be sent/received.

If you want all of the default features except for cache for example, you can list all but that:

default-features = false
features = [
version = "0.5"


Serenity requires the following system dependencies:

  • openssl


The following dependencies all require the voice feature to be enabled in your Cargo.toml:

  • libsodium (Arch: community/libsodium)
  • opus (Arch: extra/opus)


  • ffmpeg (Arch: extra/ffmpeg)


  • youtube-dl (Arch: community/youtube-dl)

Building the voice-feature on Windows can be done by following these instructions: https://github.com/serenity-rs/serenity/wiki/Voice-on-Windows

Related Projects


~95K SLoC