package
Discord adapter for Chat SDK — HTTP interactions, Gateway events, slash commands, and embeds
npm install @chat-adapter/discordGitHub-flavored package documentation.
Across all versions.
Download trend unavailable.
Runtime metadata.
Tagged topics.
vercel-release-bot
infra+release@vercel.com
Discord adapter for Chat SDK. Configure with HTTP Interactions and Gateway WebSocket support.
Documentation: chat-sdk.dev/adapters/official/discord · Guides: vercel.com/kb/chat-sdk
pnpm add @chat-adapter/discordTo scaffold a new Discord bot with this adapter preselected:
npx create-chat-sdk@latest my-bot --adapter discord memoryVisit the adapters directory to see other available official and vendor-official adapters.
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!");
});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.
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.
Regular messages and reactions still require a Gateway connection.
https://your-domain.com/api/webhooks/discordbot, applications.commandsDiscord has two ways to receive events:
HTTP Interactions (default):
Gateway WebSocket (required for messages):
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.
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, ensuring overlap with the 10-minute listener duration.
Add CRON_SECRET to your Vercel project settings.
By default, only direct user mentions (@BotName) trigger onNewMention handlers. To also trigger on role mentions (e.g., @AI):
mentionRoleIds:createDiscordAdapter({
mentionRoleIds: ["1457473602180878604"],
});Or set DISCORD_MENTION_ROLE_IDS as a comma-separated string in your environment variables.
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:
import {
createDiscordAdapter,
DiscordInteractionResponseFlag,
} from "@chat-adapter/discord";
createDiscordAdapter({
interactionFlags: ({ command }) => {
if (command === "/admin") {
return DiscordInteractionResponseFlag.Ephemeral;
}
},
});Later calls to event.channel.post() will share the same ephemeral message.
Calls to event.channel.postEphemeral() will fallback to a private DM.
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.
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.
Call discord.setThreadTitle(thread.id, title) to rename an existing Discord thread channel. The bot needs the Manage Threads permission.
DISCORD_BOT_TOKEN=your-bot-token
DISCORD_PUBLIC_KEY=your-application-public-key
DISCORD_APPLICATION_ID=your-application-id
DISCORD_MENTION_ROLE_IDS=1234567890,0987654321 # Optional
DISCORD_API_URL=... # Optional, override the Discord API base URL
CRON_SECRET=your-random-secret # For Gateway cron| Feature | Supported |
|---|---|
| Post message | Yes |
| Edit message | Yes |
| Delete message | Yes |
| File uploads | Yes |
| Streaming | Post+Edit fallback |
| 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 |
| Feature | Supported |
|---|---|
| Slash commands | Yes |
| Mentions | Yes |
| Add reactions | Yes |
| Remove reactions | Yes |
| Typing indicator | Yes |
| DMs | Yes |
| Ephemeral messages | No (DM fallback) |
| 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 |
Run a local tunnel (e.g., ngrok) to test webhooks locally:
ngrok http 3000Update the Interactions Endpoint URL in the Discord Developer Portal to your ngrok URL.
mentionRoleIds config: Ensure the role ID is in the arraySee all guides and templates at chat-sdk.dev/resources.
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/chatThe 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-pluginThe plugin is optional; the skill alone is enough to build with Chat SDK.
For agent-readable documentation, see chat-sdk.dev/llms.txt (page index) or chat-sdk.dev/llms-full.txt (full text).
MIT
Estimated unpacked size across 45 packages.
15.6 MB
Includes dependencies.
5 direct dependencies.
4.45.0
4.45.0
^14.25.1
14.28.1
^0.38.55
0.38.59
4.45.0
4.45.0
^4.4.0
4.4.0