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

serenity

serenity logo

Serenity is a Rust library for the Discord API.

View the [examples] on how to use serenity's API. To make a bot with slash commands or text commands, see the poise framework built on top of serenity. To send and receive data from voice channels, see the songbird library.

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 std::env;

use serenity::async_trait; use serenity::prelude::*; use serenity::model::channel::Message; use serenity::framework::standard::macros::{command, group}; use serenity::framework::standard::{StandardFramework, CommandResult};

[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 intents = GatewayIntents::non_privileged() | GatewayIntents::MESSAGE_CONTENT;
let mut client = Client::builder(token, intents)
    .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.11" tokio = { version = "1.21.2", features = ["macros", "rt-multi-thread"] }

MSRV Policy

Serenity's minimum supported Rust version (MSRV) is Rust 1.53.

We opt to keep MSRV stable on the current branch. This means it will remain unchanged between minor releases. Occasionally, dependencies may violate SemVer and update their own MSRV in a breaking way. As a result, pinning their versions will become necessary to successfully build Serenity using an older Rust release. (NOTE: This is currently the case; building using Rust 1.53 requires pinning dashmap = "=5.2.0", indexmap = "=1.8.2", and time = "=0.3.9". If the simd_json feature is enabled, you must additionally pin halfbrown = "=0.1.12" and value-trait = "=0.2.10". Without dependency pinning, the de facto MSRV is Rust 1.59.)

The next branch tracks the latest Rust release as its MSRV. This allows for swift development as new languages features are stabilized, and reduces technical debt in the long run. When a new major release is cut, the MSRV on current will be updated to that of next, and we will commit to supporting that MSRV until the following major release.

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.11"

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 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", "chrono", "client", "framework", "gateway", "http", "model", "standard_framework", "utils", "rustls_backend", ] version = "0.11"

Dependencies

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

Hosting

If you want a quick and easy way to host your bot, you can use shuttle, a Rust-native cloud development platform that allows deploying Serenity bots for free.

Projects extending Serenity