+1
Daily
5,658
stars
674
forks
25
watchers
2,553
prs
1,031
issues
87
releases
README
[![ci-badge][]][ci] [![docs-badge][]][docs] [![guild-badge][]][guild] [![crates.io version]][crates.io link] [![rust-version-badge]][rust-version-link]
serenity
![serenity logo][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.
Note that - although this documentation will try to be as up-to-date and
accurate as possible - Discord hosts [official documentation][discord docs]. If
you need to be sure that some information piece is accurate, refer to their
docs.
Installation
Run:
cargo add serenity
Or add the following to your Cargo.toml file:
toml
[dependencies]
serenity = "0.12"
tokio = { version = "1.21.2", features = ["macros", "rt-multi-thread"] }
Usage
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][gateway docs] 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][cache docs].
A basic ping-pong bot looks like:
rust,ignore
use std::env;
use serenity::async_trait;
use serenity::model::channel::Message;
use serenity::prelude::;
struct Handler;
[async_trait]
impl EventHandler for Handler {
async fn message(&self, ctx: Context, msg: Message) {
if msg.content == "!ping" {
if let Err(why) = msg.channel_id.say(&ctx.http, "Pong!").await {
println!("Error sending message: {why:?}");
}
}
}
}
[tokio::main]
async fn main() {
// Login with a bot token from the environment
let token = env::var("DISCORD_TOKEN").expect("Expected a token in the environment");
// Set gateway intents, which decides what events the bot will be notified about
let intents = GatewayIntents::GUILD_MESSAGES
| GatewayIntents::DIRECT_MESSAGES
| GatewayIntents::MESSAGE_CONTENT;
// Create a new instance of the Client, logging in as a bot.
let mut client =
Client::builder(&token, intents).event_handler(Handler).awaiTop issues
#1462The slash commands wrapper needs to become more declarative17 comments · 2021-08-07#2396Transform some model enums back to structs for forwards compatibility6 comments · 2023-04-22#3580[Feature request] Support "target_id" in guild.audit_logs()5 comments · 2026-07-14#3558`HttpError::UnsuccessfulRequest` missing useful info and repeats info5 comments · 2026-05-19#3534Timestamp should truncate to milliseconds4 comments · 2026-04-10#2056Better synchronize model types with Discord API documentation 4 comments · 2022-07-19#3557Multiple vulnerabilities with the current version of `tokio-tungstenite`3 comments · 2026-05-19#3356Tracking issue for reducing future sizes2 comments · 2025-04-27
Discussions
#3494Standardize on jiff as a Timestamp backend1 comments · 2026-02-20#3480Handle user joing voice channel1 comments · 2026-02-01#3423Allow converting a Timestamp back into a snowflake ID1 comments · 2025-09-20#3411New version release?0 comments · 2025-08-28#3122Using the cache to get deleted / updated message info1 comments · 2025-02-20#3007Is there a reason why some methods take ownership instead of just borrowing?1 comments · 2024-10-29#2980using retrieve endpoint using postman1 comments · 2024-09-27#2951Implementation of Poll routes1 comments · 2024-08-21
Latest release
v0.12.5 v0.12.5 2025-12-20This compiles all of the changes that had accumulated since the prior release, and, unless another minor release is warranted, constitutes as the last release for the 0.12.x series. We also extend our heartfelt thanks to [@jamesbt365], who passed away a few months ago. We deeply appreciate his code contributions, which started back in 2023, as well as his social contributions for helping people with using Serenity, Songbird, and Poise, on Github and/or Discord. We were saddened to hear that he's no longer with us, but we hope he rests well. Thanks to the following for their contrib