Discord

Create a new bot

Scaffold a Next.js bot with the Discord adapter using create-chat-sdk:

The generated app uses the Memory state adapter for local development. To add the adapter to an existing app, start at Install.

Install

Quick start

import { Chat } from "chat";
import { createDiscordAdapter } from "@chat-adapter/discord";
import { createMemoryState } from "@chat-adapter/state-memory";

const discord = createDiscordAdapter();
export const bot = new Chat({
  userName: "mybot",
  adapters: {
    discord,
  },
  state: createMemoryState(),
});

bot.onNewMention(async (thread, message) => {
  await thread.post("Hello from Discord!");
});

The memory state adapter keeps subscriptions and locks in process memory, which suits local development. Use Redis or PostgreSQL in production.

Then create the webhook route:

import { after } from "next/server";
import { bot } from "@/lib/bot";

export async function POST(request: Request): Promise<Response> {
  return bot.webhooks.discord(request, {
    waitUntil: (task) => after(() => task),
  });
}

Platform setup

These steps create your own Discord application and bot, which you need when you authenticate with Discord app credentials.

Authentication

Vercel Connect

Use Vercel Connect to resolve the bot token and application ID from a Discord connector and verify trigger-forwarded interactions with Vercel OIDC:

import { createDiscordAdapter } from "@chat-adapter/discord";
import { connectDiscordAdapter } from "@vercel/connect/chat";

const discord = createDiscordAdapter({
  ...connectDiscordAdapter("discord/acme-discord"),
});

Replace discord/acme-discord with your connector UID. The helper supplies botToken, applicationId, and webhookVerifier, so you don't need DISCORD_BOT_TOKEN, DISCORD_PUBLIC_KEY, or DISCORD_APPLICATION_ID in your deployment. Configure the Connect trigger to forward interactions to /api/webhooks/discord on your deployed app.

Connect OIDC verification replaces Discord's Ed25519 public-key check for forwarded interactions. Regular messages and reactions still require a Gateway connection.

Create the connector and attach it to your project with the Vercel CLI. --trigger-path registers the Discord webhook route as the trigger destination, and vercel env pull downloads a development OIDC token for local runs:

vercel link
vercel connect create discord --name acme-discord --triggers
vercel connect attach discord/acme-discord --triggers --trigger-path /api/webhooks/discord
vercel env pull

Without --trigger-branch, Connect forwards webhooks to your production deployment. See Vercel Connect for the full setup.

Discord app credentials

Set DISCORD_BOT_TOKEN, DISCORD_PUBLIC_KEY, and DISCORD_APPLICATION_ID from the application you created in Platform setup, and the adapter picks them up automatically.

Configuration

botToken and applicationId are required. Provide either publicKey or webhookVerifier.

Environment variables

HTTP Interactions vs Gateway

Discord delivers events over two channels:

• HTTP Interactions deliver button clicks, slash commands, and verification pings. They work on serverless but do not include regular messages.
• The Gateway WebSocket is required to receive regular messages and reactions, and it needs a persistent connection.

In serverless environments, use a cron job to keep the Gateway connection alive.

Gateway setup for serverless

import { after } from "next/server";
import { bot } from "@/lib/bot";

export const maxDuration = 800;

export async function GET(request: Request): Promise<Response> {
  const cronSecret = process.env.CRON_SECRET;
  if (!cronSecret) {
    return new Response("CRON_SECRET not configured", { status: 500 });
  }

  const authHeader = request.headers.get("authorization");
  if (authHeader !== `Bearer ${cronSecret}`) {
    return new Response("Unauthorized", { status: 401 });
  }

  const durationMs = 600 * 1000;
  const webhookUrl = `https://${process.env.VERCEL_URL}/api/webhooks/discord`;

  await bot.initialize();
  const discord = bot.getAdapter("discord");
  return discord.startGatewayListener(
    { waitUntil: (task) => after(() => task) },
    durationMs,
    undefined,
    webhookUrl
  );
}

{
  "crons": [
    {
      "path": "/api/discord/gateway",
      "schedule": "*/9 * * * *"
    }
  ]
}

This runs every 9 minutes, overlapping with the 10-minute listener duration to keep coverage continuous.

Role mentions

By default, only direct user mentions (@BotName) trigger onNewMention handlers. To also trigger on role mentions:

1. Create a role in your Discord server (for example, "AI") and assign it to your bot.
2. Copy the role ID. With Developer Mode enabled, right-click the role in server settings.
3. Add it to mentionRoleIds:

createDiscordAdapter({
  mentionRoleIds: ["1457473602180878604"],
});

Or set DISCORD_MENTION_ROLE_IDS as a comma-separated string.

Cards

Discord cards render as embeds by default. Set contentFormat to render Chat SDK cards with Discord Components:

import {
  createDiscordAdapter,
  DiscordContentFormat,
} from "@chat-adapter/discord";

createDiscordAdapter({
  contentFormat: DiscordContentFormat.ComponentsV2,
});

When enabled, card messages use Discord's IS_COMPONENTS_V2 flag and render with containers, sections, text displays, media galleries, buttons, and string selects. Plain text messages continue to use normal Discord message content.

Discord caps a Components v2 message at 40 total components and 4000 characters across all text. When a card exceeds either limit the adapter throws a ValidationError instead of letting Discord reject the request, so reduce the number of sections, fields, actions, or images, or shorten the text on very large cards.

Interaction flags

Discord slash commands are acknowledged with DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE before your handler posts the final response. Use the interactionFlags option to set Discord interaction flags on that initial deferred response.

Return Discord's EPHEMERAL flag to make the loading state and original interaction response visible only to the user who invoked the command:

import {
  createDiscordAdapter,
  DiscordInteractionResponseFlag,
} from "@chat-adapter/discord";

createDiscordAdapter({
  interactionFlags: ({ command, interaction }) => {
    if (
      command === "/admin" ||
      interaction.member?.roles.includes("1457473602180878604")
    ) {
      return DiscordInteractionResponseFlag.Ephemeral;
    }

    return undefined;
  },
});

The callback receives the parsed command path, flattened option text, invoking user, normalized Chat SDK channel ID, and raw Discord interaction. Later calls to event.channel.post() continue through the normal Discord interaction response flow. Calls to event.channel.postEphemeral() still use the normal Chat SDK fallback behavior.

Discord thread channel names

Call discord.setThreadTitle(thread.id, title) to rename an existing Discord thread channel. The bot needs the Manage Threads permission.

Inbound attachments

Incoming attachments expose a lazy fetchData() that downloads from Discord's CDN anonymously. Downloads refuse private and internal addresses, including after redirects, are limited to 25 MB, and time out after 30 seconds.

Feature support

Resources

• Create a Discord support bot with Nuxt and Redis: build a Discord support bot with Nuxt, from project setup and Discord app configuration through Gateway forwarding, AI responses, and deployment.

See all guides and templates on the resources page.