![crates.io version] ![rust 1.35.0+ badge] ![crates.io version] ![rust 1.35.0+ badge]
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 [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.
A basic ping-pong bot looks like:
```rust,ignore use serenity::client::Client; use serenity::model::channel::Message; use serenity::prelude::{EventHandler, Context}; use serenity::framework::standard::{ StandardFramework, CommandResult, macros::{ command, group } };
group!({ name: "general", options: {}, commands: [ping], });
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("DISCORDTOKEN").expect("token"), Handler) .expect("Error creating client"); client.withframework(StandardFramework::new() .configure(|c| c.prefix("~")) // set the bot's prefix to "~" .group(&GENERAL_GROUP));
// start listening for events by starting a single shard
if let Err(why) = client.start() {
println!("An error occurred while running the client: {:?}", why);
}
}
fn ping(ctx: &mut Context, msg: &Message) -> CommandResult { msg.reply(ctx, "Pong!")?;
Ok(())
}
```
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:
toml
[dependencies]
serenity = "0.6"
Serenity supports a minimum of Rust 1.35.
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.6"
The default features are: builder, cache, client, framework, gateway,
http, model, standard_framework, utils, and rustls_backend.
The following is a full list of features:
native_tls_backend
instead of rustls_backend.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",
"client",
"framework",
"gateway",
"http",
"model",
"standard_framework",
"utils",
"rustls_backend",
]
version = "0.6"
If you use the native_tls_backend and you are not developing on macOS or Windows, you will need:
If you want to use voice, Serenity will attempt to build these for you:
community/libsodium)extra/opus)In case the automated building fails, you may report it to us, but installing should fix it.
Voice + ffmpeg:
extra/ffmpeg)Voice + youtube-dl:
community/youtube-dl)