ci-badge docs-badge guild-badge ![crates.io version] ![rust 1.48.0+ badge]

serenity

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::builder].

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 [Event]s, 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:

```rust,ignore use serenity::async_trait; use serenity::client::{Client, Context, EventHandler}; use serenity::model::channel::Message; use serenity::framework::standard::{ StandardFramework, CommandResult, macros::{ command, group } };

use std::env;

[group]

[commands(ping)]

struct General;

struct Handler;

[async_trait]

impl EventHandler for Handler {}

[tokio::main]

async fn main() { let framework = StandardFramework::new() .configure(|c| c.prefix("~")) // set the bot's prefix to "~" .group(&GENERAL_GROUP);

// Login with a bot token from the environment
let token = env::var("DISCORD_TOKEN").expect("token");
let mut client = Client::builder(token)
    .event_handler(Handler)
    .framework(framework)
    .await
    .expect("Error creating client");

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

}

[command]

async fn ping(ctx: &Context, msg: &Message) -> CommandResult { msg.reply(ctx, "Pong!").await?;

Ok(())

} ```

Full Examples

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

Installation

Add the following to your Cargo.toml file:

toml [dependencies] serenity = "0.10"

Serenity supports a minimum of Rust 1.48.

Features

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

toml [dependencies.serenity] default-features = false features = ["pick", "your", "feature", "names", "here"] version = "0.10"

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

There are these alternative default features, they require to set default-features = false:

If you are unsure which to pick, use the default features by not setting default-features = false.

The following is a full list of features:

Serenity offers two TLS-backends, rustls_backend by default, you need to pick one if you do not use the default features:

If you need to use tokio version 0.2 use the backends below:

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

toml [dependencies.serenity] default-features = false features = [ "builder", "client", "framework", "gateway", "http", "model", "standard_framework", "utils", "rustls_backend", ] version = "0.10"

Dependencies

If you use the native_tls_backend and you are not developing on macOS or Windows, you will need:

Projects extending Serenity