Building your first Discord Bot

Discord apps let you customize and extend Discord using a collection of APIs and interactive features. This guide will walk you through building your first Discord app using JavaScript and by the end you'll have an app that uses slash commands, sends messages, and responds to component interactions.

We'll be building a Discord app that lets users play rock-paper-scissors (with 7 choices instead of 3). This guide is beginner-focused, but it assumes a basic understanding of JavaScript.

Before we get started, you'll need to set up your local environment and get the project code from the sample app repository.

If you don't have NodeJS installed, install that first.

After NodeJS is installed, open your command line and clone the project code:

git clone https://github.com/discord/discord-example-app.git

Then navigate to the directory and install the project's dependencies:

# navigate to directory
cd discord-example-app

# install dependencies
npm install

├── examples    -> short, feature-specific sample apps
├──── app.js  -> finished app.js code
├──── button.js
├──── command.js
├──── modal.js
├──── selectMenu.js
├── .env        -> your credentials and IDs
├── app.js      -> main entrypoint for app
├── commands.js -> slash command payloads + helpers
├── game.js     -> logic specific to Rock, Paper, Scissors
├── utils.js    -> utility functions and constants
├── package.json
├── README.md
└── .gitignore

With that out of the way, open your new project in the code editor of your choice, and we'll move ahead to setting up your Discord app.

First, you'll need to create an app in the developer portal if you don't have one already:

Create App

Enter a name for your app, then press Create.

After you create your app, you'll land on the General Information page of the app's settings where you can update basic information about your app like its description and icon. You'll also see an Application ID and Interactions Endpoint URL, which we'll use a bit later in the guide.

We'll need to set up and fetch a few sensitive values for your app, like its token and ID.

Back in your project folder, rename the .env.sample file to .env. This is where we'll store all of your app's credentials.

We'll need three values from your app's settings for your .env file:

• On the General Information page, copy the value for Application ID. In .env, replace <YOUR_APP_ID> with the ID you copied.
• Back on the General Information page, copy the value for Public Key, which is used to ensure HTTP requests are coming from Discord. In .env, replace <YOUR_PUBLIC_KEY> with the value you copied.
• On the Bot page under Token, click "Reset Token" to generate a new bot token. In .env, replace <YOUR_BOT_TOKEN> with your new token.

Now that you have the credentials you need, lets configure your bot user and installation settings.

Newly-created apps have a bot user enabled by default. Bot users allow your app to appear and behave similarly to other server members when it's installed to a server.

On the left hand sidebar in your app's settings, there's a Bot page (where we fetched the token from). On this page, you can also configure settings like its privileged intents or whether it can be installed by other users.

For now, we don't need to configure anything additional here, but you may need to in the future depending on your app's use case. Let's go ahead and get our app ready for installation.

Now we'll select where your app can be installed in Discord, which is determined by the installation contexts that your app supports.

Click on Installation in the left sidebar, then under Installation Contexts make sure both "User Install" and "Guild Install" are selected.

Install links provide an easy way for users to install your app in Discord. We'll set up the default Discord Provided Link, but you can read more about the different type of install links in the Application documentation.

On the Installation page, go to the Install Link section and select "Discord Provided Link" if it's not already selected.

When Discorded Provided Link is selected, a new Default Install Settings section will appear, which we'll configure next.

Apps need approval from installing users to perform actions in Discord (like creating a slash command or fetching a list of server members). Let's add scopes and permissions before installing the app.

On the Installation page in the Default Install Settings section:

• For User Install, add the applications.commands scope
• For Guild Install, add the applications.commands scope and bot scope. When you select bot, a new Permissions menu will appear to select the bot user's permissions. Select any permissions that you may want for your app—for now, I'll just select Send Messages.

See a list of all OAuth2 scopes, or read more on permissions in the documentation.

Once you add scopes, copy the URL from the Install Link section from before.

Since our app is supporting both installation contexts, we'll install your new app to both a test server and your user account so that we can test in both installation contexts.

To install your app to your test server, copy the default Install Link for your app from the Installation page. Paste the link in your browser and hit enter, then select "Add to server" in the installation prompt.

Select your test server, and follow the installation prompt. Once your app is added to your test server, you should see it appear in the member list.

Next, install your app to your user account. Paste the same Install Link in your browser and hit enter. This time, select "Add to my apps" in the installation prompt.

Follow the installation prompt to install your app to your user account. Once it's installed you can open a DM with it.

With your app configured and installed to your test server and account, let's take a look at the code.

The project contains a register script you can use to install the commands in ALL_COMMANDS, which is defined at the bottom of commands.js. It installs the commands as global commands by calling the HTTP API's PUT /applications/<APP_ID>/commands endpoint.

If you want to customize your commands or add additional ones, you can reference the command structure in the commands documentation.

In your terminal within the project folder, run the following command:

npm run register

If you navigate back to your server, you should see the slash commands appear. But if you try to run them, nothing will happen since your app isn't receiving or handling any requests from Discord.

To enable your app to receive slash command and other interactions requests, Discord needs a public URL to send them. This URL can be configured in your app's settings as Interaction Endpoint URL.

To set up a public endpoint, we'll start our app which runs an Express server, then use ngrok to expose our server publicly.

First, go to your project's folder and run the following to start your app:

npm run start

There should be output indicating your app is running on port 3000. Behind the scenes, our app is ready to handle interactions from Discord, which includes verifying security request headers and responding to PING requests. We're skipping over a lot of the details in this tutorial, but details about preparing apps for interactions is in the Interactions Overview documentation.

Next, we'll start our ngrok tunnel. If you don't have ngrok installed locally, you can install it by following the instructions on the ngrok download page.

After ngrok is installed, open a new terminal and create a public endpoint that will forward requests to your Express server:

ngrok http 3000

You should see your connection open with output similar to the following:

Tunnel Status                 online
Version                       2.0/2.0
Web Interface                 http://127.0.0.1:4040
Forwarding                    https://1234-someurl.ngrok.io -> localhost:3000

Connections                  ttl     opn     rt1     rt5     p50     p90
                              0       0       0.00    0.00    0.00    0.00

We'll use Forwarding URL as the publicly-accessible URL where Discord will send interactions requests in the next step.

Go to your app's settings and on the General Information page under Interaction Endpoint URL, paste your new ngrok forwarding URL and append /interactions.

Click Save Changes and ensure your endpoint is successfully verified.

The verification is handled automatically by the sample app in two ways:

• It uses the PUBLIC_KEY and discord-interactions package with a wrapper function (imported from utils.js) that makes it conform to Express's verify interface. This is run on every incoming request to your app.
• It responds to incoming PING requests.

You can learn more about preparing your app to receive interactions in the interactions documentation.

With the endpoint verified, navigate to your project's app.js file and find the code block that handles the /test command:

// "test" command
if (name === 'test') {
  // Send a message into the channel where command was triggered from
  return res.send({
    type: InteractionResponseType.CHANNEL_MESSAGE_WITH_SOURCE,
    data: {
      flags: InteractionResponseFlags.IS_COMPONENTS_V2,
      components: [
        {
          type: MessageComponentTypes.TEXT_DISPLAY,
          // Fetches a random emoji to send from a helper function
          content: `hello world ${getRandomEmoji()}`
        }
      ]
    },
  });
}

The code above is responding to the interaction with a message in the channel, DM, or Group DM it originated from. You can see all available response types, like responding with a modal, in the documentation.

Go to your server and make sure your app's /test slash command works. When you trigger it, your app should send a message that contains “hello world” followed by a random emoji.

In the following section, we'll add an additional command that uses slash command options, buttons, and select menus to build the rock-paper-scissors game.

The /challenge command will be how our rock-paper-scissors-style game is initiated. When the command is triggered, the app will send message components to the channel, which will guide the users to complete the game.

The /challenge command, called CHALLENGE_COMMAND in commands.js, has an array of options. In our app, the options are objects representing different things that a user can select while playing rock-paper-scissors, generated using keys of RPSChoices in game.js.

You can read more about command options and their structure in the documentation.

// "challenge" command
if (name === 'challenge' && id) {
  // Interaction context
  const context = req.body.context;
  // User ID is in user field for (G)DMs, and member for servers
  const userId = context === 0 ? req.body.member.user.id : req.body.user.id;
  // User's object choice
  const objectName = req.body.data.options[0].value;

  // Create active game using message ID as the game ID
  activeGames[id] = {
    id: userId,
    objectName,
  };

  return res.send({
    type: InteractionResponseType.CHANNEL_MESSAGE_WITH_SOURCE,
    data: {
      flags: InteractionResponseFlags.IS_COMPONENTS_V2,
      components: [
        {
          type: MessageComponentTypes.TEXT_DISPLAY,
          // Fetches a random emoji to send from a helper function
          content: `Rock papers scissors challenge from <@${userId}>`,
        },
        {
          type: MessageComponentTypes.ACTION_ROW,
          components: [
            {
              type: MessageComponentTypes.BUTTON,
              // Append the game ID to use later on
              custom_id: `accept_button_${req.body.id}`,
              label: 'Accept',
              style: ButtonStyleTypes.PRIMARY,
            },
          ],
        },
      ],
    },
  });
}

if (type === InteractionType.MESSAGE_COMPONENT) {
  // custom_id set in payload when sending message component
  const componentId = data.custom_id;

  if (componentId.startsWith('accept_button_')) {
    // get the associated game ID
    const gameId = componentId.replace('accept_button_', '');
    // Delete message with token in request body
    const endpoint = `webhooks/${process.env.APP_ID}/${req.body.token}/messages/${req.body.message.id}`;
    try {
      await res.send({
        type: InteractionResponseType.CHANNEL_MESSAGE_WITH_SOURCE,
        data: {
          // Indicates it'll be an ephemeral message
          flags: InteractionResponseFlags.EPHEMERAL | InteractionResponseFlags.IS_COMPONENTS_V2,
          components: [
            {
              type: MessageComponentTypes.TEXT_DISPLAY,
              content: 'What is your object of choice?',
            },
            {
              type: MessageComponentTypes.ACTION_ROW,
              components: [
                {
                  type: MessageComponentTypes.STRING_SELECT,
                  // Append game ID
                  custom_id: `select_choice_${gameId}`,
                  options: getShuffledOptions(),
                },
              ],
            },
          ],
        },
      });
      // Delete previous message
      await DiscordRequest(endpoint, { method: 'DELETE' });
    } catch (err) {
      console.error('Error sending message:', err);
    }
  }
  return;
}

if (type === InteractionType.MESSAGE_COMPONENT) {
  // custom_id set in payload when sending message component
  const componentId = data.custom_id;

  if (componentId.startsWith('accept_button_')) {
    // get the associated game ID
    const gameId = componentId.replace('accept_button_', '');
    // Delete message with token in request body
    const endpoint = `webhooks/${process.env.APP_ID}/${req.body.token}/messages/${req.body.message.id}`;
    try {
      await res.send({
        type: InteractionResponseType.CHANNEL_MESSAGE_WITH_SOURCE,
        data: {
          // Indicates it'll be an ephemeral message
          flags: InteractionResponseFlags.EPHEMERAL | InteractionResponseFlags.IS_COMPONENTS_V2,
          components: [
            {
              type: MessageComponentTypes.TEXT_DISPLAY,
              content: 'What is your object of choice?',
            },
            {
              type: MessageComponentTypes.ACTION_ROW,
              components: [
                {
                  type: MessageComponentTypes.STRING_SELECT,
                  // Append game ID
                  custom_id: `select_choice_${gameId}`,
                  options: getShuffledOptions(),
                },
              ],
            },
          ],
        },
      });
      // Delete previous message
      await DiscordRequest(endpoint, { method: 'DELETE' });
    } catch (err) {
      console.error('Error sending message:', err);
    }
  } else if (componentId.startsWith('select_choice_')) {
    // get the associated game ID
    const gameId = componentId.replace('select_choice_', '');

    if (activeGames[gameId]) {
      // Interaction context
      const context = req.body.context;
      // Get user ID and object choice for responding user
      // User ID is in user field for (G)DMs, and member for servers
      const userId = context === 0 ? req.body.member.user.id : req.body.user.id;
      const objectName = data.values[0];
      // Calculate result from helper function
      const resultStr = getResult(activeGames[gameId], {
        id: userId,
        objectName,
      });

      // Remove game from storage
      delete activeGames[gameId];
      // Update message with token in request body
      const endpoint = `webhooks/${process.env.APP_ID}/${req.body.token}/messages/${req.body.message.id}`;

      try {
        // Send results
        await res.send({
          type: InteractionResponseType.CHANNEL_MESSAGE_WITH_SOURCE,
          data: {
            flags: InteractionResponseFlags.IS_COMPONENTS_V2,
            components: [
              {
                type: MessageComponentTypes.TEXT_DISPLAY,
                content: resultStr
              }
            ]
            },
        });
        // Update ephemeral message
        await DiscordRequest(endpoint, {
          method: 'PATCH',
          body: {
            components: [
              {
                type: MessageComponentTypes.TEXT_DISPLAY,
                content: 'Nice choice ' + getRandomEmoji()
              }
            ],
          },
        });
      } catch (err) {
        console.error('Error sending message:', err);
      }
    }
  }

  return;
}

....and that's it 🎊 Go ahead and test your app and make sure everything works.

Congrats on building your first Discord app! 🤖

Hopefully you learned a bit about Discord apps, how to configure them, and how to make them interactive. From here, you can continue building out your app or explore what else is possible.