Create a Discord Slash Bot using HarperDB Custom Functions

11 min readOct 22, 2021

Hello folks 👋!

Have you ever created a Node.js server using Express/Fastify? Have you used a service like HarperDB to store your data?

If yes, then you are in luck! HarperDB has introduced Custom Functions which helps us to use HarperDB methods to create our custom API endpoints. Custom Functions are written in Node.js and are powered by Fastify.

HarperDB Custom Functions can be used to power things like integration with third-party apps and APIs, AI, third-party authentication, defining database functionality, and serving a website.

All the things that we will cover in this tutorial are within the FREE tier of HarperDB.

If you want to review the code at any point, here is the GitHub repo .

What are we going to build?

We will build a Discord bot which responds to slash commands .

Users can say a programming joke on the discord channel using /sayjoke command. We will keep count of the number of jokes each user has posted and the jokes in a HarperDB database.

Any user can use the /top command to see who is the user who has posted the most programming jokes.

And finally, one can view the jokes posted by a particular user by using the /listjokes command.

Our bot will be able to fetch the data from the HarperDB database, perform some logic and respond to the user with the results.

A small demo of what we will be building

Prerequisites

Before starting off with this tutorial, make sure you have the following:

Node.js and npm installed
Basic JavaScript knowledge
A discord.com account
Postman or other REST API Client
A code editor like VS Code
A HarperDB Account

Installation

We need to set up our local environment first. Make sure to use node v14.17.3 to avoid errors during installation. So we will install the HarperDB package from npm using:

npm install -g harperdb

For more details and troubleshooting while installing, visit the docs .

You should be able to run HarperDB now on your local machine by running:

harperdb run

The local instance runs on port 9925 by default.

Registering our local instance

Now that our local instance is up and running, we need to register our local instance on HarperDB studio. Go ahead and sign up for a free account if you haven't already.

After login, click on Create new HarperDB cloud instance / Register User installed instance.

Now click on Register User-installed instance:

Now enter the following details for the local user instance running on localhost:9925:

the default id and password is HDB_ADMIN which can be changed later </center>

Select the free option for RAM in the next screen and add the instance in the next screen after that:

</center>

Wait for some seconds as the instance is getting registered.

Configuring the local instance

Once the local instance is registered, on the following screen, you will see various tabs. Click on the browse tab and add the schema. Let's name our schema dev:

For the discord bot, we will need 2 tables: users and jokes.

The users table will hold user information like id (of the user from discord), username (discord username), score (count of number of jokes posted).

The jokes table will hold the jokes. It will have columns: id (of the joke), joke (joke text), user_id (id of the user who posted the joke).

For now, let's create those 2 tables by clicking the + button:

users table with hash attr. as id
jokes table with hash attr. as id

Custom Functions

Now we come to the most exciting part! Custom Functions! Custom functions are powered by Fastify.

Click on the functions tab and click on Enable Custom Functions on the left.

After you have enabled HarperDB Custom Functions, you will have the option to create a project. Let's call ours: discordbot.

You can also see where the custom functions project is stored on your local machine along with the port on which it runs on (default: 9926).

Fire up the terminal now, and change directory to where the custom functions project is present.

cd ~/hdb/custom_functions

Now let's clone a function template into a folder discordbot (our custom functions project name) provided by HarperDB to get up and running quickly!

git clone https://github.com/HarperDB/harperdb-custom-functions-template.git discordbot

Open the folder discordbot in your favourite code editor to see what code the template hooked us up with!

Once you open up the folder in your code editor, you'll see it is a typical npm project.

The routes are defined in routes folder.

Helper methods are present in helpers folder.

Also, we can have a static website running by using the static folder, but we won't be doing that in this tutorial.

We can also install npm packages and use them in our code.

Discord Bot Setup

Before we write some code, let us set up our discord developer account and create our bot and invite it into a Discord server.

Before all this, I recommend you to create a discord server for testing this bot, which is pretty straight-forward . Or you can use an existing Discord server too.

Now, let's create our bot.

Go to Discord Developer Portal and click "New Application" on the top right. Give it any name and click "Create".

Next click the "Bot" button on the left sidebar and click "Add Bot". Click "Yes, do it!" when prompted.

Now, we have created our bot successfully. Later we are going to need some information which will allow us to access our bot. Please follow the following instructions to find everything we will need:

Application ID: Go to the "General Information" tab on the left. Copy the value called "Application ID".

Public Key: On the "General Information" tab, copy the value in the field called "Public Key".

Bot Token: On the "Bot" tab in the left sidebar, copy the "Token" value.

Keep these values safe for later.

Inviting our bot to our server

The bot is created but we still need to invite it into our server. Let's do that now.

Copy the following URL and replace <YOUR_APPLICATION_ID> with your application ID that you copied from Discord Developer Portal:

https://discord.com/api/oauth2/authorize?client_id=<YOUR_APPLICATION_ID>&permissions=8&scope=applications.commands%20bot

Here we are giving the bot commands permission and bot admin permissions

Open that constructed URL in a new tab, and you will see the following:

Select your server and click on Continue and then Authorize in the next screen. Now you should see your bot in your Discord server.

Now, let's finally get to some code, shall we?

Get. Set. Code.

Switch to your editor where you have opened the discordbot folder in the previous steps.

First, let's install the dependencies we will need:

npm i discord-interactions: discord-interactions contains handy discord methods to make the creation of our bot simple.
npm i nanoid: nanoid is a small uuid generator which we will use to generate unique ids for our jokes.
npm i fastify-raw-body: For verifying our bot later using discord-interactions, we need access to the raw request body. As Fastify doesn't support this by default, we will use fastify-raw-body.

Open the examples.js file and delete all the routes present. We will add our routes one by one. Your file should look like below:

"use strict";


// eslint-disable-next-line no-unused-vars,require-await
module.exports = async (server, { hdbCore, logger }) => {

};

Now, we will add our routes inside the file. All routes created inside this file, will be relative to /discordbot.

For example, let's now create a GET route at / which will open at localhost:9926/discordbot

server.route({
    url: "/",
    method: "GET",
    handler: (request) => {
      return { status: "Server running!" };
    },
  });
};
. . .

Now save the file and go to HarperDB studio and click on "restart server" on the "functions" tab:

Anytime you make any change to the code, make sure to restart the custom functions server.

By the way, did you see that your code was reflected in the studio on the editor? Cool, right?

Now to see the results of your added route, visit localhost:9926/discordbot on your browser, and you should get a JSON response of:

{
  "status": "Server running!"
}

Yay! Our code works!

Now for the most exciting part, let's start coding the discord bot. We will import InteractionResponseType, InteractionType and verifyKey from discord-interactions.

const {
  InteractionResponseType,
  InteractionType,
  verifyKey,
} = require("discord-interactions");

We will create a simple POST request at / which will basically respond to a PING interaction with a PONG interaction.

. . .
server.route({
    url: "/",
    method: "POST",
    handler: async (request) => {
      const myBody = request.body;
      if (myBody.type === InteractionType.PING) {
        return { type: InteractionResponseType.PONG };
      }
    },
  });
. . .

Now let's go to the Discord Portal and register our POST endpoint as the Interactions Endpoint URL. Go to your application in Discord Developer Portal and click on the "General Information" tab, and paste our endpoint in the Interactions Endpoint URL field. But oops! Our app is currently running on localhost which Discord cannot reach. So for a temporary solution, we will use a tunnelling service called ngrok. After we finish coding and testing our code, we will deploy the bot to HarperDB cloud instance with a single click for free.

For Mac, to install ngrok:

brew install ngrok # assuming you have homebrew installed
ngrok http 9926 # create a tunnel to localhost:9926

For other operating systems, follow the installation instructions .

Copy the https URL you get from ngrok.

Paste the following to the Interactions Endpoint URL field: YOUR_NGROK_URL/discordbot.

Now, click on "Save changes". But we get an error:

So, actually discord won't accept ANY request which is sent to it, we need to perform verification to check for the validity of the request. Let's perform that verification. For that, we need access to the raw request body and for that we will use fastify-raw-body.

Add the following code just before the GET / route.

. . . 

server.register(require("fastify-raw-body"), {
    field: "rawBody",
    global: false, 
    encoding: "utf8", 
    runFirst: true, 
  });

  server.addHook("preHandler", async (request, response) => {
    if (request.method === "POST") {
      const signature = request.headers["x-signature-ed25519"];
      const timestamp = request.headers["x-signature-timestamp"];
      const isValidRequest = verifyKey(
        request.rawBody,
        signature,
        timestamp,
        <YOUR_PUBLIC_KEY> // as a string, e.g. : "7171664534475faa2bccec6d8b1337650f7"
      );
      if (!isValidRequest) {
        server.log.info("Invalid Request");
        return response.status(401).send({ error: "Bad request signature " });
      }
    }
  });
. . .

Also, we will need to add rawBody:true to the config of our POST / route. So, now it will look like this:

. . .
server.route({
    url: "/",
    method: "POST",
    config: {
      // add the rawBody to this route
      rawBody: true,
    },
    handler: async (request) => {
      const myBody = request.body;

      if (myBody.type === InteractionType.PING) {
        return { type: InteractionResponseType.PONG };
      }
    },
  });
. . .

(Don't forget to restart the functions server after each code change)

Now try to put YOUR_NGROK_URL/discordbot in the Interactions Endpoint URL field. And voila! We will be greeted with a success message.

So, now our endpoint is registered and verified. Now let's add the commands for our bot in the code. We will have 3 slash commands.

/sayjoke <joke> : post a joke on the discord server.
/listjokes <username>: view jokes of a particular user.
/top: check the leader with the max. number of jokes posted.

Let's first create a commands.js file inside the helpers folder and write the following code for the commands. We will be using this in the routes.

const SAY_JOKE = {
  name: "sayjoke",
  description: "Say a programming joke and make everyone go ROFL!",
  options: [
    {
      type: 3, // a string is type 3
      name: "joke",
      description: "The programming joke.",
      required: true,
    },
  ],
};

const TOP = {
  name: "top",
  description: "Find out who is the top scorer with his score.",
};

const LIST_JOKES = {
  name: "listjokes",
  description: "Display programming jokes said by a user.",
  options: [
    {
      name: "user",
      description: "The user whose jokes you want to hear.",
      type: 6, // a user mention is type 6
      required: true,
    },
  ],
};

module.exports = {
  SAY_JOKE,
  TOP,
  LIST_JOKES,
};

Registering the slash commands

Before using these in the routes file, we will need to register them first. This is a one-time process for each command.

Open Postman or any other REST API client.

Make a New Request with type: POST.

URL should be: https://discord.com/api/v8/applications/YOUR_APPLICATION_ID/commands

On the Headers tab, add 2 headers:

Content-Type:application/json
Authorization:Bot <YOUR_BOT_TOKEN>

Now for each command, change the Body and Hit Send. For sayjoke:

{
    "name": "sayjoke",
    "description": "Say a programming joke and make everyone go ROFL!",
    "options": [
        {
            "type": 3,
            "name": "joke",
            "description": "The programming joke.",
            "required": true
        }
    ]
}

You should see a response similar to this:

Similarly, let's register the other 2 commands.

For listjokes:

{
    "name": "listjokes",
    "description": "Display all programming jokes said by a user.",
    "options": [
        {
            "name": "user",
            "description": "The user whose jokes you want to hear.",
            "type": 6,
            "required": true
        }
    ]
}

For top:

{
    "name": "top",
    "description": "Find out who is the top scorer with his score."
}

NOTE: Now we have to wait 1 hour till all the commands are registered. If you don't want to wait, you can use your Guild/server ID . But in this case, your bot will work in that server/guild.

Just replace the URL with: https://discord.com/api/v8/applications/892533254752718898/guilds/<YOUR_GUILD_ID>/commands

Once your commands are registered, you should be able to see those commands popup when you type / on the chat.

But when you select any of these, you'll get an error. This is expected as we haven't written the code for these slash commands.

Writing code for the slash commands

Hop over to the routes/examples.js file and let's write some more code.

We will add a condition to the / POST route to check if it is a slash command:

. . .
server.route({
    url: "/",
    method: "POST",
    config: {
      // add the rawBody to this route
      rawBody: true,
    },
    handler: async (request) => {
      const myBody = request.body;

      if (myBody.type === InteractionType.PING) {
        return { type: InteractionResponseType.PONG };
      } else if (myBody.type === InteractionType.APPLICATION_COMMAND) {
          // to handle slash commands here
      }
    },
  });
. . .

So inside the else if block, we are checking if the type is InteractionType.APPLICATION_COMMAND i.e. our slash commands. Inside this block, we will add the logic for handling our 3 slash commands.

Let's import the commands information from commands.js in examples.js file.

At the top of the file, add the following lines:

const { SAY_JOKE, TOP, LIST_JOKES } = require("../helpers/commands");

The /sayjoke command:

The /sayjoke command allows a user to post a programming joke to the Discord channel. First, Let's add the code for /sayjoke command.

// replace the existing line with below line
else if (myBody.type === InteractionType.APPLICATION_COMMAND) {
        const user = myBody.member.user; // discord user object
        const username = `${user.username}`; // discord username

        const id = user.id; //discord userid (e.g. 393890098061771919)
        switch (myBody.data.name.toLowerCase()) {
          case SAY_JOKE.name.toLowerCase():
            request.body = {
              operation: "sql",
              sql: `SELECT * FROM dev.users WHERE id = ${id}`,
            };
            const sayJokeResponse = await hdbCore.requestWithoutAuthentication(request);
            if (sayJokeResponse.length === 0) {
              // new user, so insert a new row to users table
              request.body = {
                operation: "sql",
                sql: `INSERT INTO dev.users (id, name, score) VALUES ('${id}', '${username}', '1')`,
              };
              await hdbCore.requestWithoutAuthentication(request);
            } else {
              // old user, so update the users table by updating the user's score
              request.body = {
                operation: "sql",
                sql: `UPDATE dev.users SET score = ${
                  sayJokeResponse[0].score + 1
                }  WHERE id = ${id}`,
              };
              await hdbCore.requestWithoutAuthentication(request);
            }
            const jokeId = nanoid(); // creating a new id for joke
            const joke = myBody.data.options[0].value;
              // insert the joke into the jokes table
            request.body = {
              operation: "sql",
              sql: `INSERT INTO dev.jokes (id, joke, person_id) VALUE ('${jokeId}', '${joke}', '${id}')`,
            };
            await hdbCore.requestWithoutAuthentication(request);
            const newScore = sayJokeResponse.length === 0 ? 1 : sayJokeResponse[0].score + 1;

            return {
              type: InteractionResponseType.CHANNEL_MESSAGE_WITH_SOURCE,
              data: {
                content: `<@${id}> says:\n*${joke}* \n<@${id}>'s score is now: **${newScore}**`, // in markdown format
                embeds: [
            // we have an embedded image in the response
                  {
                    type: "rich",
                    image: {
                      url: "https://res.cloudinary.com/geekysrm/image/upload/v1632951540/rofl.gif",
                    },
                  },
                ],
              },
            };

Woah! That's a lot of code. Let's understand the code we just wrote step by step.

First of all, we get the user object from Discord containing all the details of the user who called this command. From that object, we extract the username and id of the discord user.

Now, inside the switch case, we compare the name of the command to our 3 slash command names. Here, we are handling the /sayjoke command.

We do a SELECT SQL query to HarperDB's database, to get the details of the user with the id as the userid we just extracted. There are 2 cases: