Quickstart

Get up and running with Discord Interactions in just a few minutes. This guide will walk you through creating a complete Express server that handles Discord slash commands and webhook events.

Before You Begin

Before you start, you’ll need:

Node.js 18.4.0 or higher installed
A Discord application created in the Discord Developer Portal
Your application’s Public Key (found in the “General Information” section)

If you haven’t created a Discord application yet, visit the Discord Developer Portal and click “New Application” to get started.

Build Your First Bot

Install the package

Create a new Node.js project and install discord-interactions:

mkdir my-discord-bot
cd my-discord-bot
npm init -y
npm install discord-interactions express

Create your server

Create a file named index.js with the following code:

JavaScript
TypeScript

index.js

const express = require('express');
const {
  InteractionType,
  InteractionResponseType,
  verifyKeyMiddleware,
  verifyWebhookEventMiddleware,
} = require('discord-interactions');

const app = express();
const PORT = process.env.PORT || 3000;
const CLIENT_PUBLIC_KEY = process.env.CLIENT_PUBLIC_KEY;

// Handle Discord interactions
app.post(
  '/interactions',
  verifyKeyMiddleware(CLIENT_PUBLIC_KEY),
  (req, res) => {
    const interaction = req.body;
    
    if (interaction.type === InteractionType.APPLICATION_COMMAND) {
      res.send({
        type: InteractionResponseType.CHANNEL_MESSAGE_WITH_SOURCE,
        data: {
          content: 'Hello from Discord Interactions! 👋',
        },
      });
    }
  }
);

// Handle webhook events
app.post(
  '/events',
  verifyWebhookEventMiddleware(CLIENT_PUBLIC_KEY),
  (req, res) => {
    console.log('📨 Event Received:', req.body);
  }
);

// Health check endpoint
app.get('/health', (req, res) => {
  res.send('OK');
});

app.listen(PORT, () => {
  console.log(`Server listening on port ${PORT}`);
});

index.ts

import express, { Request, Response } from 'express';
import {
  InteractionType,
  InteractionResponseType,
  verifyKeyMiddleware,
  verifyWebhookEventMiddleware,
} from 'discord-interactions';

const app = express();
const PORT = process.env.PORT || 3000;
const CLIENT_PUBLIC_KEY = process.env.CLIENT_PUBLIC_KEY!;

// Handle Discord interactions
app.post(
  '/interactions',
  verifyKeyMiddleware(CLIENT_PUBLIC_KEY),
  (req: Request, res: Response) => {
    const interaction = req.body;
    
    if (interaction.type === InteractionType.APPLICATION_COMMAND) {
      res.send({
        type: InteractionResponseType.CHANNEL_MESSAGE_WITH_SOURCE,
        data: {
          content: 'Hello from Discord Interactions! 👋',
        },
      });
    }
  }
);

// Handle webhook events
app.post(
  '/events',
  verifyWebhookEventMiddleware(CLIENT_PUBLIC_KEY),
  (req: Request, res: Response) => {
    console.log('📨 Event Received:', req.body);
  }
);

// Health check endpoint
app.get('/health', (req: Request, res: Response) => {
  res.send('OK');
});

app.listen(PORT, () => {
  console.log(`Server listening on port ${PORT}`);
});

Set your environment variables

Create a .env file in your project directory:

.env

CLIENT_PUBLIC_KEY=your_public_key_here
PORT=3000

Replace your_public_key_here with your application’s public key from the Discord Developer Portal.

To use environment variables, install dotenv and add require('dotenv').config() at the top of your file.

Run your server locally

Start your server:

node index.js

Your server should now be running on http://localhost:3000.

Discord needs to reach your server via HTTPS. Use a tool like ngrok to expose your local server during development:

ngrok http 3000

Configure Discord

In the Discord Developer Portal:

Go to your application’s General Information page
Find the Interactions Endpoint URL field
Enter your server URL followed by /interactions (e.g., https://your-server.com/interactions)
Click Save Changes

Discord will send a PING request to verify your endpoint. The middleware automatically handles this for you.

If verification fails, check that:

Your server is running and accessible
You’re using the correct public key
Your endpoint URL ends with /interactions

Create a slash command

To test your bot, you need to create a slash command:

Go to your application in the Discord Developer Portal
Navigate to the OAuth2 page
Under OAuth2 URL Generator, select the applications.commands scope
Copy the generated URL and open it in your browser
Select a server to add your bot to

Then create a command using the Discord API or a library like discord.js.

Test your bot

In your Discord server, use your slash command. You should see the response “Hello from Discord Interactions! 👋”Congratulations! You’ve successfully created your first Discord interaction webhook.

Understanding the Code

What does verifyKeyMiddleware do?

The verifyKeyMiddleware function verifies that incoming requests are actually from Discord by validating the Ed25519 signature in the request headers. This prevents unauthorized users from sending fake requests to your endpoint.It also automatically handles PING interactions that Discord sends to verify your endpoint is working.

What are interaction types?

Discord sends different types of interactions:

PING (1) - Verification ping from Discord
APPLICATION_COMMAND (2) - User invoked a slash command
MESSAGE_COMPONENT (3) - User clicked a button or selected from a menu
APPLICATION_COMMAND_AUTOCOMPLETE (4) - User is typing in an autocomplete field
MODAL_SUBMIT (5) - User submitted a modal form

What are response types?

Your bot can respond to interactions in different ways:

PONG (1) - Acknowledge a PING
CHANNEL_MESSAGE_WITH_SOURCE (4) - Send a new message
DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE (5) - Acknowledge and send a message later
DEFERRED_UPDATE_MESSAGE (6) - Acknowledge a component interaction
UPDATE_MESSAGE (7) - Update the message the component was attached to
APPLICATION_COMMAND_AUTOCOMPLETE_RESULT (8) - Return autocomplete choices
MODAL (9) - Show a modal to the user

What about webhook events?

Webhook events are different from interactions. They notify your app about server activities like:

User authorizations
Entitlement creation
Lobby messages
Direct messages during Social SDK sessions

Use verifyWebhookEventMiddleware to handle these events with the same signature verification.

Next Steps

Now that you have a working bot, explore more features:

Handling Interactions

Learn about different interaction types and how to handle them

Message Components

Add buttons, select menus, and modals to your messages

Webhook Events

Receive real-time notifications about server activities

Express Integration

Advanced Express patterns and production deployment

Get Started

Guides

Examples

Before You Begin

Build Your First Bot

Understanding the Code

Next Steps

Handling Interactions

Message Components

Webhook Events

Express Integration

Build docs developers (and LLMs) love

Get Started

Guides

Examples

​Before You Begin

​Build Your First Bot

​Understanding the Code

​Next Steps

Handling Interactions

Message Components

Webhook Events

Express Integration

Build docs developers (and LLMs) love

Before You Begin

Build Your First Bot

Understanding the Code

Next Steps