In this tutorial, we will look at a simple way to add custom functionality to a Discord server using a bot written in Rust. We will first register a bot with Discord, then go about how to create a Serenity application that will later run on Shuttle. Finally, we will make the bot do something useful, writing some Rust code to get information from an external service.

The full code can be found in this repository.

​
Registering our bot

Before we start making our bot, we need to register it for Discord. We do that by going to https://discord.com/developers/applications and creating a new application.

The application process is also used for adding functionality to Discord but we will be only using the bot offering. Fill in the basic details and you should get to the following screen:

You want to copy the Application ID and have it handy, because we will use it to add our bot to a test server.

Next, we want to create a bot. You can set its public username here:

You want to click the reset token and copy this value (we will use it in a later step). This value represents the username and password as a single value that Discord uses to authenticate that our server is the one controlling the bot. You want to keep this value secret.

To add the bot to the server we will test on, we can use the following URL (replace <application_id> in the URL with the ID you copied beforehand):

https://discord.com/oauth2/authorize?client_id=<application_id>&scope=bot&permissions=8

Here, we create it with permissions=8 so that it can do everything on the server. If you are adding to another server, select only the permissions it needs.

We now have a bot on our server:

Oh, they’re offline 😢

​
Getting a bot online

At this moment, our bot is not running because there is no code. We will have to write it and run it before we can start interacting with it.

​
Serenity

Serenity is a library for writing Discord bots (and communicating with the Discord API).

If you don’t have Shuttle yet, you can install it with cargo install cargo-shuttle. Afterwards, run the following in an empty directory:

shuttle init --template serenity

After running it you, should see the following generated in src/main.rs:

src/main.rs
use anyhow::Context as _;
use serenity::async_trait;
use serenity::model::channel::Message;
use serenity::model::gateway::Ready;
use serenity::prelude::*;
use shuttle_runtime::SecretStore;
use tracing::{error, info};

struct Bot;

#[async_trait]
impl EventHandler for Bot {
    async fn message(&self, ctx: Context, msg: Message) {
        if msg.content == "!hello" {
            if let Err(e) = msg.channel_id.say(&ctx.http, "world!").await {
                error!("Error sending message: {:?}", e);
            }
        }
    }

    async fn ready(&self, _: Context, ready: Ready) {
        info!("{} is connected!", ready.user.name);
    }
}

#[shuttle_runtime::main]
async fn serenity(
    #[shuttle_runtime::Secrets] secrets: SecretStore,
) -> shuttle_serenity::ShuttleSerenity {
    // Get the discord token set in `Secrets.toml`
    let token = secrets.get("DISCORD_TOKEN").context("'DISCORD_TOKEN' was not found")?;

    // Set gateway intents, which decides what events the bot will be notified about
    let intents = GatewayIntents::GUILD_MESSAGES | GatewayIntents::MESSAGE_CONTENT;

    let client = Client::builder(&token, intents)
        .event_handler(Bot)
        .await
        .expect("Err creating client");

    Ok(client.into())
}

​
Building an interaction for our bot

We want to call our bot when chatting in a text channel. Discord enables this with slash commands.

Slash commands can be server-specific (servers are named as guilds in Discords API documentation) or application specific (across all servers the bot is in). For testing, we will only enable it on a single guild/server. This is because the application-wide commands can take an hour to fully register whereas the guild/server specific ones are instant, so we can test the new commands immediately.

You can copy the guild ID by right-clicking on the icon of the server and click Copy Server ID (you will need developer mode enabled to do this):

Now that we have the information for setup, we can start writing our bot and its commands.

We will first get rid of the async fn message hook as we won’t be using it in this example, and then configure the gateway intents to not use any, as we won’t be needing them.

src/main.rs
    // Set gateway intents, which decides what events the bot will be notified about.
    // Here we don't need any intents so empty
    let intents = GatewayIntents::empty();

In the ready hook we will call set_commands to register a command with Discord. Here we register a hello command with a description and no parameters (Discord refers to these as options).

src/main.rs
#[async_trait]
impl EventHandler for Bot {
    async fn ready(&self, ctx: Context, ready: Ready) {
        info!("{} is connected!", ready.user.name);

        // We are going to move the guild ID to the Secrets.toml file later.
        let guild_id = GuildId::new(*your guild id*);

        // We are creating a vector with commands
        // and registering them on the server with the guild ID we have set.
        let commands = vec![CreateCommand::new("hello").description("Say hello")];
        let commands = guild_id.set_commands(&ctx.http, commands).await.unwrap();

        info!("Registered commands: {:#?}", commands);
    }
}

If you are working on a larger command application, poise (which builds on Serenity) might be better suited.

With our command registered, we will now add a hook for when these commands are called using interaction_create.

src/main.rs
#[async_trait]
impl EventHandler for Bot {
    async fn ready(&self, ctx: Context, ready: Ready) {
        // ...
    }

    async fn interaction_create(&self, ctx: Context, interaction: Interaction) {
        if let Interaction::Command(command) = interaction {
            let response_content = match command.data.name.as_str() {
                "hello" => "hello".to_owned(),
                command => unreachable!("Unknown command: {}", command),
            };

            let data = CreateInteractionResponseMessage::new().content(response_content);
            let builder = CreateInteractionResponse::Message(data);

            if let Err(why) = command.create_response(&ctx.http, builder).await {
                println!("Cannot respond to slash command: {why}");
            }
        }
    }
}

​
Trying it out

Now with the code written we can test it locally. Before we do that we have to authenticate the bot with Discord. We do this with the value we got from “Reset Token” on the bot screen in one of the previous steps. To register a secret with Shuttle we create a Secrets.toml file with a key value pair:

Secrets.toml
DISCORD_TOKEN="your discord token"

Now we can run our bot and test the hello command:

shuttle run

We should see that our bot now displays as online:

When typing, we should see our command come up with its description:

Our bot should respond with “hello” to our command:

Wow! Let’s make our bot do something a little more useful.

​
Making the bot do something

There are public APIs that can be used for getting information on a variety of topics.

For this demo, we are going to build a bot that gives a forecast for a location. I used the AccuWeather API for this demo. If you are following this tutorial 1:1 you can go and register an application to get an access key. If you are using a different API this is still the sort of process you would follow.

To get a forecast using the API requires two requests:

  1. Get a location ID for a named location
  2. Get the forecast at the location ID

The API requires making network requests and it returns a JSON response. We can make the requests with cargo add reqwest -F json and deserialize the results to structures using serde, with cargo add serde. We will then have a function that chains the two requests together and deserializes the forecast to a readable result.

You can skip some of the boilerplate by using direct access on untyped values. But we will opt for the better strongly typed structured approach.

Here we type some of the structures returned by the API and add #[derive(Deserialize)] so they can be decoded from JSON. All the keys are in PascalCase so we use the #[serde(rename_all = "PascalCase")] helper attribute to stay aligned with Rust standards. Some are completely different from the Rust field name so we use #[serde(alias = ...)] on the field to set its matching JSON representation.

src/weather.rs
use serde::Deserialize;
use std::fmt::Display;

#[derive(Deserialize, Debug)]
#[serde(rename_all = "PascalCase")]
pub struct Location {
    key: String,
    localized_name: String,
    country: Country,
}

impl Display for Location {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}, {}", self.localized_name, self.country.id)
    }
}

#[derive(Deserialize, Debug)]
pub struct Country {
    #[serde(alias = "ID")]
    pub id: String,
}

#[derive(Deserialize, Debug)]
#[serde(rename_all = "PascalCase")]
pub struct Forecast {
    pub headline: Headline,
}

#[derive(Deserialize, Debug)]
pub struct Headline {
    #[serde(alias = "Text")]
    pub overview: String,
}

The above skips a lot of the fields returned by the API, only opting for the ones we will use in this demo. If you wanted to type all the fields you could try the new type from JSON feature in rust-analyzer to avoid having to write as much.

Our location request call also fails if the search we put in returns no places. We will create an intermediate type that represents this case and implements std::error::Error:

src/weather.rs
#[derive(Debug)]
pub struct CouldNotFindLocation {
    place: String,
}

impl Display for CouldNotFindLocation {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "Could not find location '{}'", self.place)
    }
}

impl std::error::Error for CouldNotFindLocation {}

Now with all the types written, we create a new async function that, given a place and a client, will return the forecast along with the location:

src/weather.rs
use reqwest::Client;

pub async fn get_forecast(
    place: &str,
    api_key: &str,
    client: &Client,
) -> Result<(Location, Forecast), Box<dyn std::error::Error>> {
    // Endpoints we will use
    const LOCATION_REQUEST: &str = "http://dataservice.accuweather.com/locations/v1/cities/search";
    const DAY_REQUEST: &str = "http://dataservice.accuweather.com/forecasts/v1/daily/1day/";

    // The URL to call combined with our API_KEY and the place (via the q search parameter)
    let url = format!("{}?apikey={}&q={}", LOCATION_REQUEST, api_key, place);
    // Make the request we will call
    let request = client.get(url).build().unwrap();
    // Execute the request and await a JSON result that will be converted to a
    // vector of locations
    let resp = client
        .execute(request)
        .await?
        .json::<Vec<Location>>()
        .await?;

    // Get the first location. If empty respond with the above declared
    // `CouldNotFindLocation` error type
    let first_location = resp
        .into_iter()
        .next()
        .ok_or_else(|| CouldNotFindLocation {
            place: place.to_owned(),
        })?;

    // Now have the location combine the key/identifier with the URL
    let url = format!("{}{}?apikey={}", DAY_REQUEST, first_location.key, api_key);

    let request = client.get(url).build().unwrap();
    let forecast = client
        .execute(request)
        .await?
        .json::<Forecast>()
        .await?;

    // Combine the location with the forecast
    Ok((first_location, forecast))
}

Now we have a function to get the weather, given a reqwest client and a place, we can wire that into the bots logic.

​
Setting up the reqwest client

Our get_forecast requires a reqwest Client and the weather API key. We will add some fields to our bot for holding this data and initialize this in the shuttle_runtime::main function. Using the secrets feature we can get our weather API key(we will also move the guild ID to the secrets file):

src/main.rs
use anyhow::Context as _;

struct Bot {
    weather_api_key: String,
    client: reqwest::Client,
    discord_guild_id: GuildId,
}

#[shuttle_runtime::main]
async fn serenity(
    #[shuttle_runtime::Secrets] secret_store: SecretStore,
) -> shuttle_serenity::ShuttleSerenity {
    // Get the discord token set in `Secrets.toml`
    let discord_token = secret_store
        .get("DISCORD_TOKEN")
        .context("'DISCORD_TOKEN' was not found")?;

    let weather_api_key = secret_store
        .get("WEATHER_API_KEY")
        .context("'WEATHER_API_KEY' was not found")?;

    let discord_guild_id = secret_store
        .get("DISCORD_GUILD_ID")
        .context("'DISCORD_GUILD_ID' was not found")?;

    let client = get_client(
        &discord_token,
        &weather_api_key,
        discord_guild_id.parse().unwrap(),
    )
    .await;
    Ok(client.into())
}

pub async fn get_client(
    discord_token: &str,
    weather_api_key: &str,
    discord_guild_id: u64,
) -> Client {
    // Set gateway intents, which decides what events the bot will be notified about.
    // Here we don't need any intents so empty
    let intents = GatewayIntents::empty();

    Client::builder(discord_token, intents)
        .event_handler(Bot {
            weather_api_key: weather_api_key.to_owned(),
            client: reqwest::Client::new(),
            discord_guild_id: GuildId::new(discord_guild_id),
        })
        .await
        .expect("Err creating client")
}

​
Registering a /weather command

We will add our new command with a place option/parameter. Back in the ready hook, we can add an additional command alongside the existing hello command:

src/main.rs
async fn ready(&self, ctx: Context, ready: Ready) {
    info!("{} is connected!", ready.user.name);

    let commands = vec![
        CreateCommand::new("hello").description("Say hello"),
        CreateCommand::new("weather")
            .description("Display the weather")
            .add_option(
                CreateCommandOption::new(
                    serenity::all::CommandOptionType::String,
                    "place",
                    "City to lookup forecast",
                )
                .required(true)
            ),
    ];

    let commands = &self
        .discord_guild_id
        .set_commands(&ctx.http, commands)
        .await
        .unwrap();

    info!("Registered commands: {:#?}", commands);
}

Discord allows us to set the expected type and whether it is required. Here, the place needs to be a string and is required.

Now in the interaction handler, we can add a new branch to the match tree. We pull out the option/argument corresponding to place and extract its value. Because of the restrictions made when setting the option we can assume that it is well-formed (unless Discord sends a bad request) and thus the unwraps here. After we have the arguments of the command we call the get_forecast function and format the results into a string to return.

src/main.rs
mod weather;

// In the match statement in interaction_create()
"weather" => {
    let argument = command
            .data
            .options
            .iter()
            .find(|opt| opt.name == "place")
            .cloned();
        let value = argument.unwrap().value;
        let place = value.as_str().unwrap();
        let result =
            weather::get_forecast(place, &self.weather_api_key, &self.client).await;
        match result {
            Ok((location, forecast)) => {
                format!("Forecast: {} in {}", forecast.headline.overview, location)
            }
            Err(err) => {
                format!("Err: {}", err)
            }
        }
    }

​
Running

Now, we have these additional secrets we are using and we will add them to the Secrets.toml file:

# In Secrets.toml
# Existing secrets:
DISCORD_TOKEN = "***"
# New secrets
DISCORD_GUILD_ID = "***"
WEATHER_API_KEY = "***"

With the secrets added, we can run the bot:

shuttle run

While typing, we should see our command come up with the options/parameters:

Entering “Paris” as the place we get a result with a forecast:

And entering a location that isn’t registered returns an error, thanks to the error handling we added to the get_forecast function:

​
Deploying on Shuttle

With all of that setup, it is really easy to get your bot hosted and running without having to run your PC 24/7.

Just write:

shuttle deploy

And you are good to go. Easy-peasy, right?

You could now take this idea even further:

  • Use a different API, to create a bot that can return new spaceflights
  • Maybe you could use one of Shuttle’s provided databases to remember certain information about a user
  • Expand on the weather forecast idea by adding more advanced options and follow-ups to command options
  • Use the localization information to return information in other languages

Was this page helpful?

Writing a Rest HTTP Service with AxumWorking with Databases in Rust