Building your first Discord Bot

Step-by-step tutorial for building your first Discord app.

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.

If you’re interested in building a game or social experience in an iframe, you can follow the tutorial for building an Activity.

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.

What we'll be building

Here’s what the finished app will look like:

To make the user flow a bit more explicit:

1. User A initiates a new game and picks their object using the app’s /challenge slash command
2. A message is sent to the channel with a button inviting others to accept the challenge
3. User B presses the Accept button
4. User B is sent an ephemeral message where they select their object of choice
5. The result of the game is posted back into the original channel for all to see

Resources used in this guide

• GitHub repository where the code from this guide lives along with some additional feature-specific code examples.
• discord-interactions, a library that provides types and helper functions for Discord apps.
• Express, a popular JavaScript web framework we’ll use to create a server where Discord can send us requests.
• ngrok, a tool that lets us tunnel our local server to a public URL where Discord can send requests.

---

Step 0: Project setup

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

We’ll be developing our app locally with a little help from ngrok, but you can use your preferred development environment.

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

Project structure

├── 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.

Step 1: Creating an app

First, you’ll need to create an app in the developer portal if you don’t have one already. Navigate to https://discord.com/developers/applications?new_application=true and 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.

Fetching your credentials

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

Your token is used to authorize API requests and carry your app’s permissions, so they are highly sensitive. Make sure to never share your token or check it into any kind of version control.

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.

You won’t be able to view your token again unless you regenerate it, so make sure to keep it somewhere safe (like in a password manager).

Configuring your bot

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.

What are intents?

Intents determine which events Discord will send your app when you’re creating a Gateway API connection. For example, if you want your app to perform an action when users add a reaction to a message, you can pass the GUILD_MESSAGE_REACTIONS (1 << 10) intent.

Some intents are privileged, meaning they allow your app to access data that may be considered sensitive (like the contents of messages). Privileged intents can be toggled on the Bot page in your app’s settings, but they must be approved before you verify your app. Standard, non-privileged intents don’t require any additional permissions or configurations.

More information about intents and a full list of available intents (along with their associated events) is in the Gateway documentation.

Choosing installation contexts

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

What are installation contexts?

Installation contexts determine where your app can be installed: to servers, to users, or both. Apps can choose which installation contexts they support within the app’s settings.

• Apps installed in a server context (server-installed apps) must be authorized by a server member with the MANAGE_GUILD permission, and are visible to all members of the server.
• Apps installed in a user context (user-installed apps) are visible only to the authorizing user, and therefore don’t require any server-specific permissions. Apps installed to a user context are visible across all of the user’s servers, DMs, and GDMs — however, they’re limited to using commands.

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

Some apps may only want to support one installation context — for example, a moderation app may only support a server context. However, by default, we recommend supporting both installation contexts. For detailed information about supporting user-installed apps, you can read the user-installable app tutorial.

Setting up an install link

Install links provide an easy way for users to install your app in Discord. On the Installation page, go to the Install Link section and select “Discord Provided Link” if it’s not already selected.

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

Adding scopes and bot permissions

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.

What are scopes and permissions?

When creating an app, scopes and permissions determine what your app can do and access in Discord.

• OAuth2 Scopes determine what data access and actions your app can take, granted on behalf of an installing or authenticating user.
• Permissions are the granular permissions for your bot user, the same as other users in Discord have. They can be approved by the installing user or later updated within server settings or with permission overwrites.

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 Send Messages to start.

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

Installing your app

When developing apps, you should build and test on your user account (for user-installable apps) and in a server that isn’t actively used by others (for server-installable apps). If you don’t have your own server already, you can create one for free.

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

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.

Install to server: Paste the install link in your browser and 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.

Install to user account: Paste the same install link in your browser again. This time, select “Add to my apps” in the installation prompt. Follow the prompt to install your app to your user account.

---

Step 2: Running your app

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

To make development a bit simpler, the app uses discord-interactions, which provides types and helper functions. If you prefer to use other languages or libraries, check out the Community Resources documentation.

Installing slash commands

To install slash commands, the app is using node-fetch. You can see the implementation for the installation in utils.js within the DiscordRequest() function.

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.

---

Step 3: Handling interactivity

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

Set up a public endpoint

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.

By default, the server will listen to requests sent to port 3000, but if you want to change the port, you can specify a PORT variable in your .env file.

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 the Forwarding URL as the publicly-accessible URL where Discord will send interactions requests in the next step.

Adding an interaction endpoint URL

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.

If you have trouble verifying your endpoint, make sure both ngrok and your app are running on the same port, and that you’ve copied the ngrok URL correctly.

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.

Handling slash command requests

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.

---

Step 4: Adding message components

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.

Adding a command with options

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.

Handling the command interaction

To handle the /challenge command, add the following code after the if name === "test" if block:

// "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,
          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,
            },
          ],
        },
      ],
    },
  });
}

The above code is doing a few things:

1. Parses the request body to get the ID of the user who triggered the slash command (userId), and the option (object choice) they selected (objectName). If the interaction is run in a server (context === 0), the user ID will be nested in the member object. If it’s in a DM or Group DM, it will be in the user object.
2. Adds a new game to the activeGames object using the interaction ID. The active game records the userId and objectName.
3. Sends a message back to the channel with a button with a custom_id of accept_button_<SOME_ID>.

The sample code uses an object as in-memory storage, but for production apps you should use a database.

When sending a message with message components, the individual payloads are appended to a components array. Actionable components (like buttons) need to be inside of an action row, which you can see in the code sample.

Note the unique custom_id sent with message components, in this case accept_button_ with the active game’s ID appended to it. A custom_id can be used to handle requests that Discord sends you when someone interacts with the component, which you’ll see in a moment.

Handling button interactions

When users interact with a message component, Discord will send a request with an interaction type of 3 (or the MESSAGE_COMPONENT value when using discord-interactions).

To set up a handler for the button, we’ll check the type of interaction, followed by matching the custom_id.

Paste the following code under the type handler for APPLICATION_COMMANDs:

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;
}

The above code:

1. Checks for a custom_id that matches what we originally sent (in this case, it starts with accept_button_). The custom ID also has the active game ID appended, so we store that in gameId.
2. Deletes the original message calling a webhook using node-fetch and passing the unique interaction token in the request body. This is done to clean up the channel, and so other users can’t click the button.
3. Responds to the request by sending a message that contains a select menu with the object choices for the game. The flags: 64 indicates that the message is ephemeral.

Handling select menu interactions

The last thing to add is code to handle select menu interactions, and to send the result of the game to the channel.

Since select menus are just another message component, the code to handle their interactions will be almost identical to buttons.

Modify the code above to handle the select menu:

if (type === InteractionType.MESSAGE_COMPONENT) {
  const componentId = data.custom_id;

  if (componentId.startsWith('accept_button_')) {
    // ... existing accept_button handling ...
  } else if (componentId.startsWith('select_choice_')) {
    // get the associated game ID
    const gameId = componentId.replace('select_choice_', '');

    if (activeGames[gameId]) {
      const context = req.body.context;
      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];
      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;
}

The code above gets the user ID and their object selection from the interaction request. That information, along with the original user’s ID and selection from the activeGames object, are passed to the getResult() function. getResult() determines the winner, then builds a readable string to send back to the channel.

We’re also calling another webhook, this time to update the follow-up ephemeral message since it can’t be deleted.

Finally, the results are sent in the channel using the CHANNEL_MESSAGE_WITH_SOURCE interaction response type.

Go ahead and test your app and make sure everything works.

---

Next steps

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.

Overview of Apps

Explore the platform features and APIs you have access to when building an app on Discord.

Explore developer tools

Explore 1st party and community-built libraries and tools to speed up and simplify your development.

Developing user-installable apps

Tutorial on building and handling interactions for apps installed to a user.

Discord Developers

Join our community to ask questions about the API, attend events hosted by the Discord platform team, and interact with other devs.