Visit the adapters directory to see other available official and vendor-official adapters.
Quick start
For managed credentials and webhook verification, see Vercel Connect.
The adapter auto-detects DISCORD_BOT_TOKEN, DISCORD_PUBLIC_KEY, DISCORD_APPLICATION_ID, and DISCORD_MENTION_ROLE_IDS from environment variables:
import { Chat } from "chat";import { createDiscordAdapter } from "@chat-adapter/discord";const discord = createDiscordAdapter();const bot = new Chat({ userName: "mybot", adapters: { discord, },});bot.onNewMention(async (thread, message) => { await thread.post("Hello from Discord!");});
Configuration
All options are auto-detected from environment variables when not provided.
Option
Required
Description
botToken
No*
Discord bot token or async resolver. Auto-detected from DISCORD_BOT_TOKEN
publicKey
No*
Application public key. Auto-detected from DISCORD_PUBLIC_KEY
applicationId
No*
Discord application ID or async resolver. Auto-detected from DISCORD_APPLICATION_ID
webhookVerifier
No
Custom webhook verifier that replaces Discord's Ed25519 publicKey verification
contentFormat
No
Render Chat SDK cards as DiscordContentFormat.Embeds or DiscordContentFormat.ComponentsV2. Defaults to DiscordContentFormat.Embeds
mentionRoleIds
No
Array of role IDs that trigger mention handlers. Auto-detected from DISCORD_MENTION_ROLE_IDS (comma-separated)
respondToChannelIds
No
Parent channel IDs whose non-bot messages, including messages in child threads, trigger mention handlers without an @mention. Top-level messages use the adapter's normal per-message Discord thread. Auto-detected from DISCORD_RESPOND_TO_CHANNEL_IDS (comma-separated). Defaults to []
respondToGlobalMentions
No
Treat @everyone/@here pings as mentions of the bot. Defaults to false
interactionFlags
No
Function returning Discord interaction flags for the initial deferred slash command response
apiUrl
No
Override the Discord API base URL. Auto-detected from DISCORD_API_URL
logger
No
Logger instance (defaults to ConsoleLogger("info"))
*botToken and applicationId are required via config or env vars. Provide either publicKey or webhookVerifier for inbound webhook verification.
Authentication
Option A — Vercel Connect
Use connectDiscordAdapter to resolve the bot token and application ID from a
Vercel Connect 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"),});
No DISCORD_BOT_TOKEN, DISCORD_PUBLIC_KEY, or DISCORD_APPLICATION_ID is
needed in this mode.
Copy the generated URL and open it to invite the bot to your server
Architecture: HTTP Interactions vs Gateway
Discord has two ways to receive events:
HTTP Interactions (default):
Receives button clicks, slash commands, and verification pings
Works out of the box with serverless
Does not receive regular messages
Gateway WebSocket (required for messages):
Receives regular messages and reactions
Receives slash commands and button clicks when no Interactions Endpoint URL is configured
Requires a persistent connection
In serverless environments, use a cron job to maintain the connection
Discord sends interactions through either the Gateway or an Interactions Endpoint URL, not both. Use the HTTP endpoint for serverless apps. For resident gateway-only apps, leave the Interactions Endpoint URL unset and start the Gateway listener without webhookUrl so interactions are processed directly.
Gateway setup for serverless
1. Create Gateway route
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 );}
Or set DISCORD_MENTION_ROLE_IDS as a comma-separated string in your environment variables.
Interaction flags
Discord interactions return a transient "thinking..." message, which then gets replaced with your content. Because of Discord's API, your message's ephemerality must be set on this initial response, not later in an onSlashCommand handler.
Use the interactionFlags option to make the loading state and your custom response visible only to the user who invoked the command:
Later calls to event.channel.post() will share the same ephemeral message.
Calls to event.channel.postEphemeral() will fallback to a private DM.
Components v2 cards
Discord cards render as embeds by default. To render Chat SDK cards with
Discord Components v2 instead, set contentFormat:
import { DiscordContentFormat } from "@chat-adapter/discord";createDiscordAdapter({ contentFormat: DiscordContentFormat.ComponentsV2,});
When enabled, card messages use Discord's IS_COMPONENTS_V2 flag and render
with components such as containers, sections, text displays, media galleries,
buttons, and string selects. Plain text messages still use 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 rather than letting Discord reject the request.
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.
Discord thread channel names
Call discord.setThreadTitle(thread.id, title) to rename an existing Discord thread channel. The bot needs the Manage Threads permission.
Environment variables
DISCORD_BOT_TOKEN=your-bot-tokenDISCORD_PUBLIC_KEY=your-application-public-keyDISCORD_APPLICATION_ID=your-application-idDISCORD_MENTION_ROLE_IDS=1234567890,0987654321 # OptionalDISCORD_API_URL=... # Optional, override the Discord API base URLCRON_SECRET=your-random-secret # For Gateway cron
Features
Messaging
Feature
Supported
Post message
Yes
Edit message
Yes
Delete message
Yes
File uploads
Yes
Streaming
Post+Edit fallback
Rich content
Feature
Supported
Card format
Embeds by default, Components v2 when enabled
Buttons
Yes
Link buttons
Yes
Select menus
Components v2
Tables
GFM
Fields
Yes
Images in cards
Yes
Modals
No
Conversations
Feature
Supported
Slash commands
Yes
Mentions
Yes
Add reactions
Yes
Remove reactions
Yes
Typing indicator
Yes
DMs
Yes
Ephemeral messages
No (DM fallback)
Message history
Feature
Supported
Fetch messages
Yes
Fetch single message
No
Fetch thread info
Yes
Fetch channel messages
Yes
List threads
Yes
Fetch channel info
Yes
Post channel message
Yes
Testing
Run a local tunnel (e.g., ngrok) to test webhooks locally:
ngrok http 3000
Update the Interactions Endpoint URL in the Discord Developer Portal to your ngrok URL.
Troubleshooting
Bot not responding to messages
Check Gateway connection: Messages require the Gateway WebSocket, not just HTTP interactions
Verify Message Content Intent: Enable this in the Bot settings
Check bot permissions: Ensure the bot can read messages in the channel
Role mentions not triggering
Verify role ID: Enable Developer Mode in Discord settings, then right-click the role
Check mentionRoleIds config: Ensure the role ID is in the array
Confirm bot has the role: The bot must have the role assigned
Signature verification failing
Check public key format: Should be a 64-character hex string (lowercase)
Verify endpoint URL: Must exactly match what's configured in Discord Developer Portal
Check for body parsing: Don't parse the request body before verification
Resources
Create a Discord support bot with Nuxt and Redis — Walks through building a Discord support bot with Nuxt, covering project setup, Discord app configuration, Gateway forwarding, AI-powered responses, and deployment.
If you use an AI coding agent such as OpenAI Codex, Claude Code, or Cursor, install the Chat SDK skill so it knows the SDK APIs, adapter patterns, and project conventions before writing code.
npx skills add vercel/chat
The skill references bundled documentation in node_modules/chat/docs, plus adapter guides and starter templates in the published package.
You can also install the Vercel Plugin for a broader agent toolkit — it includes the Chat SDK skill alongside specialist agents, agent slash commands, and more:
npx plugins add vercel/vercel-plugin
The plugin is optional; the skill alone is enough to build with Chat SDK.