serenity-rs /serenity

A Rust library for the Discord API.

★ 5,658⑂ 674👁 25⑃ 2,553● 1,031▤ 87
RustISCCreated 2016-11-06discord.gg/serenity-rs
Download: v0.12.5v0.12.5 ↓0.12.52025-12-20
+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).awai

Top issues

Discussions

Latest release

v0.12.5 v0.12.5 2025-12-20
This 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

Snapshot: 2026-11-16T09:23:14Z · Data license Apache-2.0 · JSON