Serenity

https://docs.rs/serenity/latest/serenity/
Admin
Serenity is a Rust library for building Discord bots with support for event handling, caching, and...
Tokens:182,317
Snippets:2,390
Trust Score:9.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### Usage Examples for Mentionable

Source: https://docs.rs/serenity/latest/serenity/model/mention/trait.Mentionable.html

Examples demonstrating how to use the mention method in message creation and string formatting.

```rust
use serenity::model::mention::Mentionable;
async fn greet(
    ctx: Context,
    member: Member,
    to_channel: GuildChannel,
    rules_channel: ChannelId,
) -> Result<(), Error> {
    let builder = CreateMessage::new().content(format!(
        "Hi {member}, welcome to the server! \
        Please refer to {rules} for our code of conduct, \
        and enjoy your stay.",
        member = member.mention(),
        rules = rules_channel.mention(),
    ));
    to_channel.id.send_message(ctx, builder).await?;
    Ok(())
}
```

```rust
use serenity::model::mention::Mentionable;
let user = UserId::new(1);
let channel = ChannelId::new(2);
let role = RoleId::new(3);
assert_eq!(
    "<@1> <#2> <@&3>",
    format!("{} {} {}", user.mention(), channel.mention(), role.mention(),),
)
```

--------------------------------

### Client::start

Source: https://docs.rs/serenity/latest/serenity/client/struct.Client.html

Starts the client connection with a single shard.

```APIDOC
## pub async fn start(&mut self) -> Result<()>

### Description
Establish the connection and start listening for events. This method is intended for bots in less than 2500 guilds.

### Errors
- Returns a ClientError::Shutdown when all shards have shutdown due to an error.
```

--------------------------------

### Start a Client with autosharding

Source: https://docs.rs/serenity/latest/serenity/client/struct.Client.html

Automatically determines the required number of shards from the Discord API and starts them.

```rust
use serenity::Client;

let token = std::env::var("DISCORD_TOKEN")?;
let mut client = Client::builder(&token, GatewayIntents::default()).await?;

if let Err(why) = client.start_autosharded().await {
    println!("Err with client: {:?}", why);
}
```

--------------------------------

### Start a Client with single shard

Source: https://docs.rs/serenity/latest/serenity/client/struct.Client.html

Initializes and starts a client with a single shard. Suitable for bots in fewer than 2500 guilds.

```rust
use serenity::Client;

let token = std::env::var("DISCORD_TOKEN")?;
let mut client = Client::builder(&token, GatewayIntents::default()).await?;

if let Err(why) = client.start().await {
    println!("Err with client: {:?}", why);
}
```

--------------------------------

### Start Shards

Source: https://docs.rs/serenity/latest/serenity/client/struct.Client.html

Initializes a specified number of shards for the client.

```rust
if let Err(why) = client.start_shards(8).await {
    println!("Err with client: {:?}", why);
}
```

--------------------------------

### Client::start

Source: https://docs.rs/serenity/latest/serenity/client/struct.Client.html

Starts the client, initializing the WebSocket connection and beginning event processing.

```APIDOC
## Client::start

### Description
Starts the client, which initializes the WebSocket connection and begins dispatching events to configured handlers.

### Signature
`async fn start(&mut self) -> Result<(), Error>`

### Returns
- **Result<(), Error>** - Returns Ok(()) on success, or an Error if the connection fails.
```

--------------------------------

### Creating an RwLock

Source: https://docs.rs/serenity/latest/serenity/prelude/struct.RwLock.html

Examples of initializing an RwLock using standard and constant constructors.

```rust
use tokio::sync::RwLock;

let lock = RwLock::new(5);
```

```rust
use tokio::sync::RwLock;

let lock = RwLock::with_max_readers(5, 1024);
```

```rust
use tokio::sync::RwLock;

static LOCK: RwLock<i32> = RwLock::const_new(5);
```

```rust
use tokio::sync::RwLock;

static LOCK: RwLock<i32> = RwLock::const_with_max_readers(5, 1024);
```

--------------------------------

### Client::start_shards

Source: https://docs.rs/serenity/latest/serenity/client/struct.Client.html

Starts all shards within a single process.

```APIDOC
## pub async fn start_shards(&mut self, total_shards: u32) -> Result<()>

### Description
Establish sharded connections and start listening for events. This will create and handle all shards within this single process.

### Parameters
- **total_shards** (u32) - Required - The total number of shards to manage.
```

--------------------------------

### Configure the StandardFramework

Source: https://docs.rs/serenity/latest/serenity/framework/standard/struct.StandardFramework.html

Example of setting up the framework with a custom prefix and whitespace handling within a Client.

```rust
use serenity::framework::standard::{Configuration, StandardFramework};
use serenity::Client;

let framework = StandardFramework::new();
framework.configure(Configuration::new().with_whitespace(true).prefix("~"));

let token = std::env::var("DISCORD_TOKEN")?;
let mut client = Client::builder(&token, GatewayIntents::default())
    .event_handler(Handler)
    .framework(framework)
    .await?;
```

--------------------------------

### Client::start_shard

Source: https://docs.rs/serenity/latest/serenity/client/struct.Client.html

Starts a specific shard by ID.

```APIDOC
## pub async fn start_shard(&mut self, shard: u32, shards: u32) -> Result<()>

### Description
Establish a sharded connection and start listening for events. This creates a single shard by ID.

### Parameters
- **shard** (u32) - Required - The ID of the shard to start.
- **shards** (u32) - Required - The total number of shards.

### Errors
- Returns a ClientError::Shutdown when all shards have shutdown due to an error.
```

--------------------------------

### Start all shards in a single process

Source: https://docs.rs/serenity/latest/serenity/client/struct.Client.html

Starts a specified total number of shards within the current process.

```rust
use serenity::Client;

let token = std::env::var("DISCORD_TOKEN")?;
let mut client = Client::builder(&token, GatewayIntents::default()).await?;
```

--------------------------------

### Client::start_autosharded

Source: https://docs.rs/serenity/latest/serenity/client/struct.Client.html

Starts the client using automatically determined sharding.

```APIDOC
## pub async fn start_autosharded(&mut self) -> Result<()>

### Description
Establish the connection(s) and start listening for events. This will retrieve an automatically determined number of shards to use from the Discord API.

### Errors
- Returns a ClientError::Shutdown when all shards have shutdown due to an error.
```

--------------------------------

### Initialize ShardManager

Source: https://docs.rs/serenity/latest/serenity/gateway/struct.ShardManager.html

Example of manually initializing a ShardManager with specific shard configurations and framework integration.

```rust
use std::env;
use std::sync::{Arc, OnceLock};

use serenity::client::{EventHandler, RawEventHandler};
use serenity::framework::{Framework, StandardFramework};
use serenity::gateway::{ShardManager, ShardManagerOptions};
use serenity::http::Http;
use serenity::model::gateway::GatewayIntents;
use serenity::prelude::*;
use tokio::sync::{Mutex, RwLock};

struct Handler;

impl EventHandler for Handler {}
impl RawEventHandler for Handler {}

let ws_url = Arc::new(Mutex::new(http.get_gateway().await?.url));
let data = Arc::new(RwLock::new(TypeMap::new()));
let event_handler = Arc::new(Handler) as Arc<dyn EventHandler>;
let framework = Arc::new(StandardFramework::new()) as Arc<dyn Framework + 'static>;

ShardManager::new(ShardManagerOptions {
    data,
    event_handlers: vec![event_handler],
    raw_event_handlers: vec![],
    framework: Arc::new(OnceLock::from(framework)),
    // the shard index to start initiating from
    shard_index: 0,
    // the number of shards to initiate (this initiates 0, 1, and 2)
    shard_init: 3,
    // the total number of shards in use
    shard_total: 5,
    ws_url,
    intents: GatewayIntents::non_privileged(),
    presence: None,
});
```

--------------------------------

### Using plain with exec_help

Source: https://docs.rs/serenity/latest/serenity/framework/standard/help_commands/fn.plain.html

Example of integrating the plain help command within a custom help function using the help macro.

```rust
use std::collections::HashSet;
use std::hash::BuildHasher;

use serenity::framework::standard::help_commands::*;
use serenity::framework::standard::macros::help;
use serenity::framework::standard::{
    Args,
    CommandGroup,
    CommandResult,
    HelpOptions,
    StandardFramework,
};
use serenity::model::prelude::*;

#[help]
async fn my_help(
    context: &Context,
    msg: &Message,
    args: Args,
    help_options: &'static HelpOptions,
    groups: &[&'static CommandGroup],
    owners: HashSet<UserId>,
) -> CommandResult {
    let _ = plain(context, msg, args, &help_options, groups, owners).await?;
    Ok(())
}

let framework = StandardFramework::new().help(&MY_HELP);
```

--------------------------------

### Create channel permission

Source: https://docs.rs/serenity/latest/serenity/model/channel/struct.GuildChannel.html

Example of creating a permission overwrite for a channel.

```rust
channel.create_permission(&http, overwrite).await?;
```

--------------------------------

### Create Global Commands

Source: https://docs.rs/serenity/latest/serenity/model/application/struct.Command.html

Examples demonstrating how to register global slash commands using the CreateCommand builder.

```rust
use serenity::builder::CreateCommand;
use serenity::model::application::Command;
use serenity::model::id::ApplicationId;

let builder = CreateCommand::new("ping").description("A simple ping command");
let _ = Command::create_global_command(&http, builder).await;
```

```rust
use serenity::builder::{CreateCommand, CreateCommandOption as CreateOption};
use serenity::model::application::{Command, CommandOptionType};
use serenity::model::id::ApplicationId;

let builder =
    CreateCommand::new("echo").description("Makes the bot send a message").add_option(
        CreateOption::new(CommandOptionType::String, "message", "The message to send")
            .required(true),
    );
let _ = Command::create_global_command(&http, builder).await;
```

--------------------------------

### Basic Group Macro Usage

Source: https://docs.rs/serenity/latest/serenity/framework/standard/macros/attr.group.html

Example showing the definition of commands and their organization into groups and sub-groups.

```rust
use command_attr::{command, group};


#[command]
fn bar() -> CommandResult {
    println!("baz");

    Ok(())
}

#[command]
fn answer_to_life() -> CommandResult {
    println!("42");

    Ok(())
}

#[group]
// All sub-groups must own at least one prefix.
#[prefix = "baz"]
#[commands(answer_to_life)]
struct Baz;

#[group]
#[commands(bar)]
// Case does not matter; the names will be all uppercased.
#[sub_groups(baz)]
struct Foo;
```

--------------------------------

### Localize Command Name

Source: https://docs.rs/serenity/latest/serenity/builder/struct.CreateCommand.html

Example of setting a primary name and localized variants for a command.

```rust
.name("birthday")
.name_localized("zh-CN", "生日")
.name_localized("el", "γενέθλια")
```

--------------------------------

### Typing::start

Source: https://docs.rs/serenity/latest/serenity/http/struct.Typing.html

Starts a typing indicator in the specified channel for an indefinite period.

```APIDOC
## pub fn start(http: Arc<Http>, channel_id: ChannelId) -> Self

### Description
Starts typing in the specified Channel for an indefinite period of time. Returns a Typing object which can be used to stop the indicator.

### Parameters
- **http** (Arc<Http>) - The HTTP client instance.
- **channel_id** (ChannelId) - The ID of the channel to start typing in.

### Errors
Returns an Error::Http if there is an error during the request.
```

--------------------------------

### Edit channel settings

Source: https://docs.rs/serenity/latest/serenity/model/channel/struct.GuildChannel.html

Example of updating a voice channel's name and bitrate.

```rust
let builder = EditChannel::new().name("test").bitrate(86400);
channel.edit(&http, builder).await;
```

--------------------------------

### CreateEmbed Timestamp Example

Source: https://docs.rs/serenity/latest/serenity/builder/struct.CreateEmbed.html

Demonstrates how to set a timestamp on an embed using a parsed string.

```rust
let timestamp: Timestamp = "2004-06-08T16:04:23Z".parse().expect("Invalid timestamp!");
let embed = CreateEmbed::new().title("hello").timestamp(timestamp);
```

--------------------------------

### FromIterator Implementation Examples

Source: https://docs.rs/serenity/latest/serenity/framework/standard/type.CommandResult.html

Shows how FromIterator collects Results into a container, stopping at the first Err encountered.

```rust
let v = vec![1, 2];
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32|
    x.checked_add(1).ok_or("Overflow!")
).collect();
assert_eq!(res, Ok(vec![2, 3]));
```

```rust
let v = vec![1, 2, 0];
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32|
    x.checked_sub(1).ok_or("Underflow!")
).collect();
assert_eq!(res, Err("Underflow!"));
```

```rust
let v = vec![3, 2, 1, 10];
let mut shared = 0;
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32| {
    shared += x;
    x.checked_sub(2).ok_or("Underflow!")
}).collect();
assert_eq!(res, Err("Underflow!"));
assert_eq!(shared, 6);
```

--------------------------------

### Allocating with a custom allocator

Source: https://docs.rs/serenity/latest/serenity/framework/standard/type.CommandError.html

Examples of using new_in and try_new_in with the allocator API.

```rust
#![feature(allocator_api)]

use std::alloc::System;

let five = Box::new_in(5, System);
```

```rust
#![feature(allocator_api)]

use std::alloc::System;
```

--------------------------------

### Set Localized Option Description

Source: https://docs.rs/serenity/latest/serenity/builder/struct.CreateCommandOption.html

Example of setting a primary description and a localized description for a command option.

```rust
.description("Wish a friend a happy birthday")
.description_localized("zh-CN", "祝你朋友生日快乐")
```

--------------------------------

### Generated static command instances

Source: https://docs.rs/serenity/latest/serenity/framework/standard/macros/attr.command.html

Example of the static instances generated by the macro for a command named 'foo'.

```rust
pub static FOO_COMMAND_OPTIONS: CommandOptions = CommandOptions { ... };
pub static FOO_COMMAND: Command = Command { options: FOO_COMMAND_OPTIONS, ... };
```

--------------------------------

### Result::is_ok_and Implementation

Source: https://docs.rs/serenity/latest/serenity/framework/standard/type.CommandResult.html

Example of checking if a Result is Ok and matches a predicate.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.is_ok_and(|x| x > 1), true);

let x: Result<u32, &str> = Ok(0);
assert_eq!(x.is_ok_and(|x| x > 1), false);

let x: Result<u32, &str> = Err("hey");
assert_eq!(x.is_ok_and(|x| x > 1), false);

let x: Result<String, &str> = Ok("ownership".to_string());
assert_eq!(x.as_ref().is_ok_and(|x| x.len() > 1), true);
println!("still alive {:?}", x);
```

--------------------------------

### Create Formatted Content

Source: https://docs.rs/serenity/latest/serenity/utils/enum.ContentModifier.html

Example of creating a Content type with bold and italic formatting applied to a string.

```rust
use serenity::utils::Content;
use serenity::utils::ContentModifier::{Bold, Italic};
let content: Content = Bold + Italic + "text";
```

--------------------------------

### get

Source: https://docs.rs/serenity/latest/serenity/model/invite/struct.Invite.html

Gets information about an invite by its code.

```APIDOC
## get

### Description
Retrieves information about an invite using its unique code.

### Signature
`pub async fn get(http: impl AsRef<Http>, code: &str, member_counts: bool, expiration: bool, event_id: Option<ScheduledEventId>) -> Result<Invite>`

### Arguments
- **code** (&str) - The invite code.
- **member_counts** (bool) - Whether to include current member counts.
- **expiration** (bool) - Whether to include expiration information.
- **event_id** (Option<ScheduledEventId>) - Optional server event ID.

### Errors
- Returns `Error::Http` if the invite is invalid.
- Returns `Error::Json` if deserialization fails.
```

--------------------------------

### Calculate User Permissions

Source: https://docs.rs/serenity/latest/serenity/model/channel/struct.GuildChannel.html

Example of calculating permissions for a user who sent a message within a channel.

```rust
#[serenity::async_trait]
impl EventHandler for Handler {
    async fn message(&self, context: Context, msg: Message) {
        let channel = match context.cache.channel(msg.channel_id) {
            Some(channel) => channel,
            None => return,
        };
```

--------------------------------

### Initiate and stop typing in a channel

Source: https://docs.rs/serenity/latest/serenity/http/struct.Typing.html

Demonstrates how to start a typing indicator for a long-running process and stop it once the process completes.

```rust
let channel_id = ChannelId::new(7);
// Initiate typing (assuming `http` is bound)
let typing = Typing::start(Arc::new(http), channel_id);

// Run some long-running process
long_process();

// Stop typing
typing.stop();
```

--------------------------------

### Create an Http instance with custom configuration

Source: https://docs.rs/serenity/latest/serenity/http/struct.HttpBuilder.html

Demonstrates initializing an Http client with a proxy and disabling the internal rate limiter.

```rust
let http =
    HttpBuilder::new("token").proxy("http://127.0.0.1:3000").ratelimiter_disabled(true).build();
```

--------------------------------

### Configure a Client with StandardFramework

Source: https://docs.rs/serenity/latest/serenity/framework/index.html

Shows how to define commands, group them, and attach the framework to a Serenity client.

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

#[command]
async fn about(ctx: &Context, msg: &Message) -> CommandResult {
    msg.channel_id.say(&ctx.http, "A simple test bot").await?;

    Ok(())
}

#[command]
async fn ping(ctx: &Context, msg: &Message) -> CommandResult {
    msg.channel_id.say(&ctx.http, "pong!").await?;

    Ok(())
}

#[group]
#[commands(about, ping)]
struct General;

struct Handler;

impl EventHandler for Handler {}

let token = std::env::var("DISCORD_TOKEN")?;

let framework = StandardFramework::new()
    // The `#[group]` (and similarly, `#[command]`) macro generates static instances
    // containing any options you gave it. For instance, the group `name` and its `commands`.
    // Their identifiers, names you can use to refer to these instances in code, are an
    // all-uppercased version of the `name` with a `_GROUP` suffix appended at the end.
    .group(&GENERAL_GROUP);

framework.configure(Configuration::new().prefix("~"));

let mut client = Client::builder(&token, GatewayIntents::default())
    .event_handler(Handler)
    .framework(framework)
    .await?;
```

--------------------------------

### Start Shard Range

Source: https://docs.rs/serenity/latest/serenity/client/struct.Client.html

Initializes a specific range of shards for a bot, useful when managing a subset of total shards.

```rust
use serenity::Client;

let token = std::env::var("DISCORD_TOKEN")?;
let mut client = Client::builder(&token, GatewayIntents::default()).await?;

if let Err(why) = client.start_shard_range(4..7, 10).await {
    println!("Err with client: {:?}", why);
}
```

--------------------------------

### Start a specific shard

Source: https://docs.rs/serenity/latest/serenity/client/struct.Client.html

Starts a specific shard ID out of a total number of shards. Useful for manual sharding control.

```rust
use serenity::Client;

let token = std::env::var("DISCORD_TOKEN")?;
let mut client = Client::builder(&token, GatewayIntents::default()).await?;

if let Err(why) = client.start_shard(3, 5).await {
    println!("Err with client: {:?}", why);
}
```

```rust
use serenity::Client;

let token = std::env::var("DISCORD_TOKEN")?;
let mut client = Client::builder(&token, GatewayIntents::default()).await?;

if let Err(why) = client.start_shard(0, 1).await {
    println!("Err with client: {:?}", why);
}
```

--------------------------------

### Set user status

Source: https://docs.rs/serenity/latest/serenity/client/struct.Context.html

Examples of setting the current user's status using various status methods.

```rust
#[serenity::async_trait]
impl EventHandler for Handler {
    async fn message(&self, ctx: Context, msg: Message) {
        if msg.content == "!online" {
            ctx.online();
        }
    }
}
```

```rust
#[serenity::async_trait]
impl EventHandler for Handler {
    async fn message(&self, ctx: Context, msg: Message) {
        if msg.content == "!idle" {
            ctx.idle();
        }
    }
}
```

```rust
#[serenity::async_trait]
impl EventHandler for Handler {
    async fn message(&self, ctx: Context, msg: Message) {
        if msg.content == "!dnd" {
            ctx.dnd();
        }
    }
}
```

```rust
#[serenity::async_trait]
impl EventHandler for Handler {
    async fn message(&self, ctx: Context, msg: Message) {
        if msg.content == "!invisible" {
            ctx.invisible();
        }
    }
}
```

--------------------------------

### Set Localized Option Name

Source: https://docs.rs/serenity/latest/serenity/builder/struct.CreateCommandOption.html

Example of setting a primary name and a localized name for a command option.

```rust
.name("age")
.name_localized("zh-CN", "岁数")
```

--------------------------------

### Access route reset time

Source: https://docs.rs/serenity/latest/serenity/http/struct.Ratelimiter.html

Example demonstrating how to retrieve and print the reset time for a specific channel route.

```rust
use serenity::http::Route;

let routes = http.ratelimiter.unwrap().routes();
let reader = routes.read().await;

let channel_id = ChannelId::new(7);
let route = Route::Channel {
    channel_id,
};
if let Some(route) = reader.get(&route.ratelimiting_bucket()) {
    if let Some(reset) = route.lock().await.reset() {
        println!("Reset time at: {:?}", reset);
    }
}
```

--------------------------------

### Configure BucketBuilder with delay action and ratelimits

Source: https://docs.rs/serenity/latest/serenity/framework/standard/buckets/struct.BucketBuilder.html

Demonstrates setting up a command bucket with a custom delay action and ratelimit configuration.

```rust
use serenity::framework::standard::macros::{command, group};
use serenity::framework::standard::{BucketBuilder, Configuration, CommandResult, StandardFramework};
use serenity::model::channel::Message;
use serenity::prelude::*;

#[command]
#[bucket = "example_bucket"]
async fn example_command(ctx: &Context, msg: &Message) -> CommandResult {
    msg.reply(ctx, "Example message, You can only repeat this once every 10 seconds").await?;

    Ok(())
}

async fn example_overuse_response(ctx: &Context, msg: &Message) {
    msg.reply(ctx, "I told you that you can't call this command less than every 10 seconds!").await.unwrap();
}

#[group]
#[commands(example_command)]
struct General;

let token = std::env::var("DISCORD_TOKEN")?;

let framework = StandardFramework::new()
    .bucket("example_bucket", BucketBuilder::default()
        // We initialise the bucket with the function we want to run
        .delay_action(|ctx, msg| {
            Box::pin(example_overuse_response(ctx, msg))
        })
        .delay(10) // We set the delay to 10 seconds
        .await_ratelimits(1) // We override the default behavior so that the function actually gets run
    )
    .await
    .group(&GENERAL_GROUP);

framework.configure(Configuration::new().prefix("~"));

let mut client = Client::builder(&token, GatewayIntents::default())
.framework(framework)
.await?;

client.start().await?;
```

--------------------------------

### channels

Source: https://docs.rs/serenity/latest/serenity/model/guild/struct.Guild.html

Gets all of the guild’s channels.

```APIDOC
## pub async fn channels(&self, http: impl AsRef<Http>) -> Result<HashMap<ChannelId, GuildChannel>>

### Description
Gets all of the guild’s channels over the REST API.
```

--------------------------------

### get_ban

Source: https://docs.rs/serenity/latest/serenity/model/guild/struct.Guild.html

Gets a user’s ban from the guild.

```APIDOC
## pub async fn get_ban(&self, cache_http: impl CacheHttp, user_id: UserId) -> Result<Option<Ban>>

### Description
Gets a user’s ban from the guild.
```

--------------------------------

### bans

Source: https://docs.rs/serenity/latest/serenity/model/guild/struct.Guild.html

Gets a list of the guild’s bans.

```APIDOC
## pub async fn bans(&self, cache_http: impl CacheHttp, target: Option<UserPagination>, limit: Option<u8>) -> Result<Vec<Ban>>

### Description
Gets a list of the guild’s bans, with additional options and filtering.
```

--------------------------------

### initialize

Source: https://docs.rs/serenity/latest/serenity/gateway/struct.Shard.html

Initializes a new WebSocket client.

```APIDOC
## initialize()

### Description
Initializes a new WebSocket client and sets the shard stage accordingly.
```

--------------------------------

### fn init

Source: https://docs.rs/serenity/latest/serenity/framework/standard/struct.StandardFramework.html

Initializes the framework with a client. This method is called directly after the Client is created.

```APIDOC
## fn init(&mut self, client: &Client)

### Description
Initializes the framework instance using the provided client.

### Parameters
- **client** (&Client) - The client instance used for initialization.
```

--------------------------------

### Initialize Cache with Settings

Source: https://docs.rs/serenity/latest/serenity/cache/struct.Cache.html

Create a new cache instance with custom configuration settings.

```rust
use serenity::cache::{Cache, Settings};

let mut settings = Settings::default();
settings.max_messages = 10;

let cache = Cache::new_with_settings(settings);
```

--------------------------------

### Get raw arguments

Source: https://docs.rs/serenity/latest/serenity/framework/standard/struct.Args.html

Returns an iterator over all unmodified arguments.

```rust
use serenity::framework::standard::{Args, Delimiter};

let args = Args::new("Harry Hermione Ronald", &[Delimiter::Single(' ')]);

let protagonists = args.raw().collect::<Vec<&str>>().join(", ");

assert_eq!(protagonists, "Harry, Hermione, Ronald");
```

--------------------------------

### Create and execute a modal

Source: https://docs.rs/serenity/latest/serenity/utils/struct.CreateQuickModal.html

Demonstrates initializing a modal with fields, setting a timeout, and awaiting the user response.

```rust
let modal = CreateQuickModal::new("About you")
    .timeout(std::time::Duration::from_secs(600))
    .short_field("First name")
    .short_field("Last name")
    .paragraph_field("Hobbies and interests");
let response = interaction.quick_modal(ctx, modal).await?;
let inputs = response.unwrap().inputs;
let (first_name, last_name, hobbies) = (&inputs[0], &inputs[1], &inputs[2]);
```

--------------------------------

### Create an invite with builder

Source: https://docs.rs/serenity/latest/serenity/builder/struct.CreateInvite.html

Demonstrates initializing a builder with specific max age and max uses constraints.

```rust
use serenity::builder::CreateInvite;
let builder = CreateInvite::new().max_age(3600).max_uses(10);
let creation = channel.create_invite(&context, builder).await?;
```

--------------------------------

### Create a Channel with Permissions

Source: https://docs.rs/serenity/latest/serenity/builder/struct.CreateChannel.html

Demonstrates how to initialize a new channel builder with a name and apply specific permission overwrites before creating the channel in a guild.

```rust
use serenity::builder::CreateChannel;
use serenity::model::channel::{PermissionOverwrite, PermissionOverwriteType};
use serenity::model::id::UserId;
use serenity::model::permissions::Permissions;

// Assuming a guild has already been bound.
let permissions = vec![PermissionOverwrite {
    allow: Permissions::VIEW_CHANNEL,
    deny: Permissions::SEND_TTS_MESSAGES,
    kind: PermissionOverwriteType::Member(UserId::new(1234)),
}];

let builder = CreateChannel::new("my_new_cool_channel").permissions(permissions);
guild.create_channel(&http, builder).await?;
```

--------------------------------

### Configure Allowed Mentions

Source: https://docs.rs/serenity/latest/serenity/builder/struct.CreateAllowedMentions.html

Examples demonstrating how to use the CreateAllowedMentions builder to restrict or allow specific mentions in messages.

```rust
use serenity::builder::CreateAllowedMentions as Am;

// Mention only the user 110372470472613888
m.allowed_mentions(Am::new().users(vec![110372470472613888]));

// Mention all users and the role 182894738100322304
m.allowed_mentions(Am::new().all_users(true).roles(vec![182894738100322304]));

// Mention all roles and nothing else
m.allowed_mentions(Am::new().all_roles(true));

// Mention all roles and users, but not everyone
m.allowed_mentions(Am::new().all_users(true).all_roles(true));

// Mention everyone and the users 182891574139682816, 110372470472613888
m.allowed_mentions(
    Am::new().everyone(true).users(vec![182891574139682816, 110372470472613888]),
);

// Mention everyone and the message author.
m.allowed_mentions(Am::new().everyone(true).users(vec![msg.author.id]));
```

--------------------------------

### Result::is_err Implementation

Source: https://docs.rs/serenity/latest/serenity/framework/standard/type.CommandResult.html

Example of checking if a Result is Err.

```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_err(), false);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_err(), true);
```

--------------------------------

### Result::is_ok Implementation

Source: https://docs.rs/serenity/latest/serenity/framework/standard/type.CommandResult.html

Example of checking if a Result is Ok.

```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_ok(), true);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_ok(), false);
```

--------------------------------

### Client::builder

Source: https://docs.rs/serenity/latest/serenity/client/struct.Client.html

Initializes a new Client instance with the provided token and gateway intents.

```APIDOC
## Client::builder

### Description
Creates a new Client builder instance to configure authentication and gateway intents.

### Signature
`Client::builder(token: impl AsRef<str>, intents: GatewayIntents) -> ClientBuilder`

### Parameters
- **token** (impl AsRef<str>) - Required - The bot token used for authentication.
- **intents** (GatewayIntents) - Required - The gateway intents to subscribe to.
```

--------------------------------

### Set guild icon using EditGuild

Source: https://docs.rs/serenity/latest/serenity/builder/struct.EditGuild.html

Example demonstrating how to use CreateAttachment to read an image and apply it as a guild icon via the EditGuild builder.

```rust
let icon = CreateAttachment::path("./guild_icon.png").await?;

// assuming a `guild` has already been bound
let builder = EditGuild::new().icon(Some(&icon));
guild.edit(&http, builder).await?;
```

--------------------------------

### Result::transpose Implementation

Source: https://docs.rs/serenity/latest/serenity/framework/standard/type.CommandResult.html

Example of transposing a Result of an Option.

```rust
#[derive(Debug, Eq, PartialEq)]
struct SomeErr;

let x: Result<Option<i32>, SomeErr> = Ok(Some(5));
let y: Option<Result<i32, SomeErr>> = Some(Ok(5));
assert_eq!(x.transpose(), y);
```

--------------------------------

### automod_rules

Source: https://docs.rs/serenity/latest/serenity/model/guild/struct.PartialGuild.html

Gets all auto moderation rules of this guild via HTTP.

```APIDOC
## pub async fn automod_rules(self, http: impl AsRef<Http>) -> Result<Vec<Rule>>

### Description
Gets all auto moderation `Rule`s of this guild via HTTP. Requires the Manage Guild permission.

### Errors
Returns `Error::Http` if the guild is unavailable.
```

--------------------------------

### start_shard_range

Source: https://docs.rs/serenity/latest/serenity/client/struct.Client.html

Establishes a range of sharded connections and starts listening for events. This method dispatches events to registered handlers and manages all shards within the specified range in the current process.

```APIDOC
## pub async fn start_shard_range(&mut self, range: Range<u32>, total_shards: u32) -> Result<()>

### Description
Establish a range of sharded connections and start listening for events. This will start receiving events and dispatch them to your registered handlers. This will create and handle all shards within a given range within this single process.

### Parameters
- **range** (Range<u32>) - Required - The range of shards to start.
- **total_shards** (u32) - Required - The total number of shards being used by the bot.

### Errors
- Returns a `ClientError::Shutdown` when all shards have shutdown due to an error.
```

--------------------------------

### messages

Source: https://docs.rs/serenity/latest/serenity/model/channel/struct.GuildChannel.html

Gets a collection of messages from the channel based on the provided builder.

```APIDOC
## pub async fn messages(&self, cache_http: impl CacheHttp, builder: GetMessages) -> Result<Vec<Message>>

### Description
Retrieves messages from the channel. If the user lacks Read Message History permission, returns an empty Vec.

### Parameters
- **cache_http** (impl CacheHttp) - Required - The cache or HTTP client.
- **builder** (GetMessages) - Required - The builder to configure message retrieval.
```

--------------------------------

### Retrieve Guild from Cache

Source: https://docs.rs/serenity/latest/serenity/cache/struct.Cache.html

Get a reference to a cached guild by its ID.

```rust
// assuming the cache is in scope, e.g. via `Context`
if let Some(guild) = cache.guild(7) {
    println!("Guild name: {}", guild.name);
};
```

--------------------------------

### Iterate over arguments

Source: https://docs.rs/serenity/latest/serenity/framework/standard/struct.Args.html

Iterates over all available arguments starting from the current offset.

```rust
use serenity::framework::standard::{Args, Delimiter};

let mut args = Args::new("4 2", &[Delimiter::Single(' ')]);

for arg in args.iter::<u32>() {
    // Zero troubles, zero worries.
    let arg = arg.unwrap_or(0);
    assert!(arg % 2 == 0);
}

assert!(args.is_empty());
```

--------------------------------

### activity

Source: https://docs.rs/serenity/latest/serenity/client/struct.ClientBuilder.html

Sets the initial activity for the bot's presence.

```APIDOC
## pub fn activity(self, activity: ActivityData) -> Self

### Description
Sets the initial activity.

### Parameters
- **activity** (ActivityData) - Required - The activity data to set.
```

--------------------------------

### Checking Result Status

Source: https://docs.rs/serenity/latest/serenity/type.Result.html

Examples of checking if a Result is Ok or Err.

```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_ok(), true);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_ok(), false);
```

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.is_ok_and(|x| x > 1), true);

let x: Result<u32, &str> = Ok(0);
assert_eq!(x.is_ok_and(|x| x > 1), false);

let x: Result<u32, &str> = Err("hey");
assert_eq!(x.is_ok_and(|x| x > 1), false);

let x: Result<String, &str> = Ok("ownership".to_string());
assert_eq!(x.as_ref().is_ok_and(|x| x.len() > 1), true);
println!("still alive {:?}", x);
```

```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_err(), false);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_err(), true);
```

--------------------------------

### create

Source: https://docs.rs/serenity/latest/serenity/model/invite/struct.Invite.html

Creates an invite for the given channel. Requires the Create Instant Invite permission.

```APIDOC
## create

### Description
Creates an invite for the specified channel. Requires the 'Create Instant Invite' permission.

### Signature
`pub async fn create(cache_http: impl CacheHttp, channel_id: impl Into<ChannelId>, builder: CreateInvite<'_>) -> Result<RichInvite>`

### Errors
- Returns `ModelError::InvalidPermissions` if the cache is enabled and the user lacks permission.
- Returns `Error::Http` if the request fails or data is invalid.
```

--------------------------------

### Result::flatten Implementation

Source: https://docs.rs/serenity/latest/serenity/framework/standard/type.CommandResult.html

Examples of flattening nested Result types.

```rust
let x: Result<Result<&'static str, u32>, u32> = Ok(Ok("hello"));
assert_eq!(Ok("hello"), x.flatten());

let x: Result<Result<&'static str, u32>, u32> = Ok(Err(6));
assert_eq!(Err(6), x.flatten());

let x: Result<Result<&'static str, u32>, u32> = Err(6);
assert_eq!(Err(6), x.flatten());
```

```rust
let x: Result<Result<Result<&'static str, u32>, u32>, u32> = Ok(Ok(Ok("hello")));
assert_eq!(Ok(Ok("hello")), x.flatten());
assert_eq!(Ok("hello"), x.flatten().flatten());
```

--------------------------------

### automod_rule

Source: https://docs.rs/serenity/latest/serenity/model/guild/struct.PartialGuild.html

Gets an auto moderation rule of this guild by its ID via HTTP.

```APIDOC
## pub async fn automod_rule(&self, http: impl AsRef<Http>, rule_id: impl Into<RuleId>) -> Result<Rule>

### Description
Gets an auto moderation `Rule` of this guild by its ID via HTTP. Requires the Manage Guild permission.

### Errors
Returns `Error::Http` if a rule with the given ID does not exist.
```

--------------------------------

### Use Colour Presets

Source: https://docs.rs/serenity/latest/serenity/model/colour/struct.Colour.html

Create a Colour instance using a predefined constant and verify its RGB tuple.

```rust
use serenity::model::Colour;

let colour = Colour::DARK_TEAL;

assert_eq!(colour.tuple(), (17, 128, 106));
```

--------------------------------

### invites

Source: https://docs.rs/serenity/latest/serenity/model/channel/struct.GuildChannel.html

Gets all of the channel’s invites. Requires the Manage Channels permission.

```APIDOC
## pub async fn invites(&self, http: impl AsRef<Http>) -> Result<Vec<RichInvite>>

### Description
Retrieves a list of all invites for the current channel.

### Parameters
- **http** (impl AsRef<Http>) - Required - The HTTP client.
```

--------------------------------

### Retrieve Colour as a hex string

Source: https://docs.rs/serenity/latest/serenity/model/colour/type.Color.html

Get the hexadecimal string representation of the Colour.

```rust
use serenity::model::Colour;

assert_eq!(Colour::new(6573123).hex(), "644C43");
```

--------------------------------

### Parse arguments with Args

Source: https://docs.rs/serenity/latest/serenity/framework/standard/struct.Args.html

Demonstrates basic argument parsing using a specified delimiter.

```rust
use serenity::framework::standard::{Args, Delimiter};

let mut args = Args::new("hello world!", &[Delimiter::Single(' ')]); // A space is our delimiter.

// Parse our argument as a `String` and assert that it's the "hello" part of the message.
assert_eq!(args.single::<String>().unwrap(), "hello");
// Same here.
assert_eq!(args.single::<String>().unwrap(), "world!");
```

--------------------------------

### EditGuildWelcomeScreen Builder Methods

Source: https://docs.rs/serenity/latest/serenity/builder/struct.EditGuildWelcomeScreen.html

Methods available on the EditGuildWelcomeScreen builder to configure the welcome screen settings before execution.

```APIDOC
## EditGuildWelcomeScreen

### Description
A builder to edit the welcome screen of a guild. Requires the Manage Guild permission.

### Methods
- **new()** -> Self: Creates a new builder instance.
- **enabled(enabled: bool)** -> Self: Sets whether the welcome screen is enabled.
- **description(description: impl Into<String>)** -> Self: Sets the server description shown in the welcome screen.
- **add_welcome_channel(channel: CreateGuildWelcomeChannel)** -> Self: Adds a channel to the welcome screen.
- **set_welcome_channels(channels: Vec<CreateGuildWelcomeChannel>)** -> Self: Sets the list of channels linked in the welcome screen.
- **audit_log_reason(reason: &'a str)** -> Self: Sets the audit log reason for the request.
- **execute(cache_http: impl CacheHttp, ctx: GuildId)** -> Future<Output = Result<GuildWelcomeScreen>>: Executes the request to update the guild's welcome screen.
```

--------------------------------

### Get raw quoted arguments

Source: https://docs.rs/serenity/latest/serenity/framework/standard/struct.Args.html

Returns an iterator over all arguments with quotes stripped.

```rust
use serenity::framework::standard::{Args, Delimiter};

let args = Args::new("Saw \"The Mist\" \"A Quiet Place\"", &[Delimiter::Single(' ')]);

let horror_movies = args.raw_quoted().collect::<Vec<&str>>();

assert_eq!(&*horror_movies, &["Saw", "The Mist", "A Quiet Place"]);
```

--------------------------------

### before

Source: https://docs.rs/serenity/latest/serenity/framework/standard/struct.StandardFramework.html

Sets a hook to run before every command execution.

```APIDOC
## pub fn before(self, f: ...)

### Description
Specify the function to be called prior to every command’s execution. If the function returns true, the command proceeds.
```

--------------------------------

### Configure Command Prefixes

Source: https://docs.rs/serenity/latest/serenity/framework/standard/struct.Configuration.html

Sets the prefix or multiple prefixes the bot responds to. Defaults to '~'.

```rust
use serenity::framework::standard::{Configuration, StandardFramework};

let framework = StandardFramework::new();
framework.configure(Configuration::new().prefix("!"));
```

```rust
use serenity::framework::standard::{Configuration, StandardFramework};

let framework = StandardFramework::new();
framework.configure(Configuration::new().prefixes(vec!["!", ">", "+"]));
```

--------------------------------

### Manually Instantiate a Shard

Source: https://docs.rs/serenity/latest/serenity/gateway/struct.Shard.html

Demonstrates how to manually create a Shard instance for a bot. Note that this is generally discouraged as the client handles this automatically.

```rust
use std::sync::Arc;

use serenity::gateway::Shard;
use serenity::model::gateway::{GatewayIntents, ShardInfo};
use serenity::model::id::ShardId;
use tokio::sync::Mutex;
let token = std::env::var("DISCORD_BOT_TOKEN")?;
let shard_info = ShardInfo {
    id: ShardId(0),
    total: 1,
};

// retrieve the gateway response, which contains the URL to connect to
let gateway = Arc::new(Mutex::new(http.get_gateway().await?.url));
let shard = Shard::new(gateway, &token, shard_info, GatewayIntents::all(), None).await?;

// at this point, you can create a `loop`, and receive events and match
// their variants
```

--------------------------------

### create

Source: https://docs.rs/serenity/latest/serenity/model/guild/struct.Guild.html

Creates a new guild.

```APIDOC
## pub async fn create(http: impl AsRef<Http>, name: &str, icon: Option<ImageHash>) -> Result<PartialGuild>

### Description
Creates a guild with the data provided. Note: This endpoint is deprecated.
```

--------------------------------

### Result::cloned Implementation

Source: https://docs.rs/serenity/latest/serenity/framework/standard/type.CommandResult.html

Examples of using the cloned method on Result types.

```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
assert_eq!(x, Ok(&mut 12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

--------------------------------

### Implement custom help command with embeds

Source: https://docs.rs/serenity/latest/serenity/framework/standard/help_commands/index.html

Demonstrates using the with_embeds function within a custom help command macro. Requires the framework and standard_framework crate features.

```rust
use std::collections::HashSet;
use std::env;

use serenity::client::{Client, Context, EventHandler};
use serenity::framework::standard::macros::help;
use serenity::framework::standard::{
    help_commands,
    Args,
    CommandGroup,
    CommandResult,
    HelpOptions,
    StandardFramework,
};
use serenity::model::prelude::{Message, UserId};

struct Handler;

impl EventHandler for Handler {}

#[help]
async fn my_help(
    context: &Context,
    msg: &Message,
    args: Args,
    help_options: &'static HelpOptions,
    groups: &[&'static CommandGroup],
    owners: HashSet<UserId>,
) -> CommandResult {
    let _ = help_commands::with_embeds(context, msg, args, help_options, groups, owners).await;
    Ok(())
}

let framework = StandardFramework::new().help(&MY_HELP);
```

--------------------------------

### Result::copied Implementation

Source: https://docs.rs/serenity/latest/serenity/framework/standard/type.CommandResult.html

Examples of using the copied method on Result types.

```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
assert_eq!(x, Ok(&mut 12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

--------------------------------

### Create a guild using Http

Source: https://docs.rs/serenity/latest/serenity/http/struct.Http.html

Demonstrates creating a new guild with a specified name using the create_guild method.

```rust
use serenity::http::Http;
use serenity::json::json;

let map = json!({
    "name": "test",
});

let _result = http.create_guild(&map).await?;
```

--------------------------------

### Retrieve Colour as a tuple

Source: https://docs.rs/serenity/latest/serenity/model/colour/type.Color.html

Get the red, green, and blue components as a single tuple.

```rust
use serenity::model::Colour;

assert_eq!(Colour::new(6573123).tuple(), (100, 76, 67));
```

--------------------------------

### Client::builder

Source: https://docs.rs/serenity/latest/serenity/client/struct.Client.html

Creates a new Client instance with the provided token and gateway intents.

```APIDOC
## pub fn builder(token: impl AsRef<str>, intents: GatewayIntents) -> ClientBuilder

### Description
Creates a new Client instance. This is the entry point for configuring the client before starting the connection.

### Parameters
- **token** (impl AsRef<str>) - Required - The Discord bot token.
- **intents** (GatewayIntents) - Required - The gateway intents to subscribe to.
```

--------------------------------

### Leaking a Box

Source: https://docs.rs/serenity/latest/serenity/framework/standard/type.CommandError.html

Examples of consuming a Box to return a mutable reference with a static lifetime.

```rust
let x = Box::new(41);
let static_ref: &'static mut usize = Box::leak(x);
*static_ref += 1;
assert_eq!(*static_ref, 42);
```

```rust
let x = vec![1, 2, 3].into_boxed_slice();
let static_ref = Box::leak(x);
static_ref[0] = 4;
assert_eq!(*static_ref, [4, 2, 3]);
```

--------------------------------

### help

Source: https://docs.rs/serenity/latest/serenity/framework/standard/struct.StandardFramework.html

Sets the code to be executed when a user sends the help command.

```APIDOC
## pub fn help(self, h: &'static HelpCommand) -> Self

### Description
Sets what code should be executed when a user sends the help command. If a command named 'help' in a group was set, this takes precedence. This framework is deprecated and will be removed in 0.13.

### Parameters
- **h** (&'static HelpCommand) - Required - The help command configuration.
```

--------------------------------

### Creating a Ping-Pong Bot Client

Source: https://docs.rs/serenity/latest/serenity/client/struct.Client.html

Initializes a Client with an event handler to respond to '!ping' messages. Requires the 'client' and 'gateway' features.

```rust
use serenity::model::prelude::*;
use serenity::prelude::*;
use serenity::Client;

struct Handler;

#[serenity::async_trait]
impl EventHandler for Handler {
    async fn message(&self, context: Context, msg: Message) {
        if msg.content == "!ping" {
            let _ = msg.channel_id.say(&context, "Pong!");
        }
    }
}

let mut client =
    Client::builder("my token here", GatewayIntents::default()).event_handler(Handler).await?;

client.start().await?;
```

--------------------------------

### Define AuthorizingIntegrationOwner Enum

Source: https://docs.rs/serenity/latest/serenity/model/application/enum.AuthorizingIntegrationOwner.html

The core enum definition for identifying the installation context of an application.

```rust
#[non_exhaustive]
pub enum AuthorizingIntegrationOwner {
    GuildInstall(Option<GuildId>),
    UserInstall(UserId),
    Unknown(InstallationContext),
}
```

--------------------------------

### CreateSoundboard::execute

Source: https://docs.rs/serenity/latest/serenity/builder/struct.CreateSoundboard.html

Executes the creation of the soundboard sound in the guild.

```APIDOC
## Builder::execute(cache_http, ctx)

### Description
Creates a new soundboard sound in the guild using the configured builder data. Requires the 'Create Guild Expressions' permission.

### Parameters
- **cache_http** (impl CacheHttp) - Required - The cache and HTTP client interface.
- **ctx** (GuildId) - Required - The ID of the guild where the sound will be created.

### Errors
- Returns `ModelError::InvalidPermissions` if the user lacks the required permission.
- Returns `Error::Http` if the request fails or data is invalid.
```
Tokens:
Raw