Repository files navigation

Serenity is a Rust library for the Discord API.

View theexamples on how to use serenity's API. To make a bot with slash commands or textcommands, see thepoise framework built on top of serenity.To send and receive data from voice channels, see thesongbird library.

Serenity supports bot login via the use ofClient::builder.

You may also check your tokens prior to login via the use ofvalidate_token.

Once logged in, you may add handlers to your client to dispatchEvents,by implementing the handlers in a trait, such asEventHandler::message.This will cause your handler to be called when aEvent::MessageCreate isreceived. Each handler is given aContext, giving information about theevent. See theclient's module-level documentation.

TheShard is transparently handled by the library, removingunnecessary complexity. Sharded connections are automatically handled foryou. See thegateway's documentation for more information.

ACache is also provided for you. This will be updated automatically foryou as data is received from the Discord API via events. When calling amethod on aContext, the cache will first be searched for relevant datato avoid unnecessary HTTP requests to the Discord API. For more information,see thecache's module-level documentation.

Note that - although this documentation will try to be as up-to-date andaccurate as possible - Discord hostsofficial documentation. Ifyou need to be sure that some information piece is accurate, refer to theirdocs.

A basic ping-pong bot looks like:

use std::env;use serenity::async_trait;use serenity::model::channel::Message;use serenity::prelude::*;structHandler;#[async_trait]implEventHandlerforHandler{asyncfnmessage(&self,ctx:Context,msg:Message){if msg.content =="!ping"{ifletErr(why) = msg.channel_id.say(&ctx.http,"Pong!").await{println!("Error sending message: {why:?}");}}}}#[tokio::main]asyncfnmain(){// Login with a bot token from the environmentlet token = env::var("DISCORD_TOKEN").expect("Expected a token in the environment");// Set gateway intents, which decides what events the bot will be notified aboutlet intents =GatewayIntents::GUILD_MESSAGES        |GatewayIntents::DIRECT_MESSAGES        |GatewayIntents::MESSAGE_CONTENT;// Create a new instance of the Client, logging in as a bot.letmut client =Client::builder(&token, intents).event_handler(Handler).await.expect("Err creating client");// Start listening for events by starting a single shardifletErr(why) = client.start().await{println!("Client error: {why:?}");}}

Full examples, detailing and explaining usage of the basic functionality of thelibrary, can be found in theexamples directory.

Add the following to yourCargo.toml file:

[dependencies]serenity ="0.12"tokio = {version ="1.21.2",features = ["macros","rt-multi-thread"] }

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

We opt to keep MSRV stable on thecurrent branch. This means it will remainunchanged between minor releases. Occasionally, dependencies may violate SemVerand update their own MSRV in a breaking way. As a result, pinning theirversions will become necessary to successfully build Serenity using an olderRust release.

Thenext branch tracks the latest Rust release as its MSRV. This allows forswift development as new languages features are stabilized, and reducestechnical debt in the long run. When a new major release is cut, the MSRV oncurrent will be updated to that ofnext, and we will commit to supportingthat MSRV until the following major release.

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

[dependencies.serenity]default-features =falsefeatures = ["pick","your","feature","names","here"]version ="0.12"

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

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

• default_native_tls: Usesnative_tls_backend instead of the defaultrustls_backend.
• default_no_backend: Excludes the default backend, pick your own backend instead.

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

The following is a full list of features:

• builder: The builders used in conjunction with models' methods.
• cache: The cache will store information about guilds, channels, users, andother data, to avoid performing REST requests. If you are low on RAM, do notenable this.
• collector: A collector awaits events, such as receiving a message from a user or reactions on a message, and allows for responding to the events in a convenient fashion. Collectors can be configured to enforce certain criteria the events must meet.
• client: A manager for shards and event handlers, abstracting away thework of handling shard events and updating the cache, if enabled.
• framework: Enables the framework, which is a utility to allow simplecommand parsing, before/after command execution, prefix setting, and more.
• gateway: A Shard, used as a higher-level interface for communicating withthe Discord gateway over a WebSocket client.
• http: Functions providing a wrapper over Discord's REST API at a lowenough level that optional parameters can be provided at will via a JsonMap.
• model: Method implementations for models, acting as helper methods overthe HTTP functions.
• standard_framework: A standard, default implementation of the Framework.NOTE: Deprecated as of v0.12.1. Using thepoise framework is recommended instead.
• utils: Utility functions for common use cases by users.
• voice: Enables registering a voice plugin to the client, which will handle actual voice connections from Discord.lavalink-rs orSongbird are recommended voice plugins.
• default_native_tls: Default features but usingnative_tls_backendinstead ofrustls_backend.
• tokio_task_builder: Enables tokio'stracing feature and usestokio::task::Builder to spawn tasks with names ifRUSTFLAGS="--cfg tokio_unstable" is set.
• unstable_discord_api: Enables features of the Discord API that do not have a stable interface. The features might not have official documentation or are subject to change.
• simd_json: Enables SIMD accelerated JSON parsing and rendering for API calls, if supported on the target CPU architecture.
• temp_cache: Enables temporary caching in functions that retrieve data via the HTTP API.
• chrono: Uses thechrono crate to represent timestamps. If disabled, thetime crate is used instead.
• interactions_endpoint: Enables tools related to Discord's Interactions Endpoint URL feature

To enable all parts of the codebase, use the"full" feature.

For possibly more up-to-date information, check the Cargo.toml.

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

• rustls_backend: Uses Rustls for all platforms, a pure RustTLS implementation.
• native_tls_backend: Uses SChannel on Windows, Secure Transport on macOS,and OpenSSL on other platforms.

If you want all of the default features except forcache for example, you canlist all but that:

[dependencies.serenity]default-features =falsefeatures = ["builder","chrono","client","framework","gateway","http","model","standard_framework","utils","rustls_backend",]version ="0.12"

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

• openssl

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

• lavalink-rs: An interface toLavalink andAndesite, an audio sending node based onLavaplayer
• Songbird: An async Rust library for the Discord voice API.
• Poise: Experimental command framework, with advanced features like edit tracking, single function slash and prefix commands and flexible argument parsing.