The Discord PlatformAdapter for @copilotkit/channels. It connects a Discord application to any AG-UI agent: ingress via discord.js (Gateway), egress as Components V2 rendered from the @copilotkit/channels-ui JSX vocabulary, plus text streaming, opaque-id interactions, and HITL.

You write your UI as JSX once (@copilotkit/channels-ui) and drive the bot with @copilotkit/channels; this package is the only one that talks to Discord.

Beta / breaking change. As of this release the discord() adapter is declarative and credential-free: it no longer takes credentials and Channels are no longer started directly. Credentials and connectivity are supplied by CopilotKit Intelligence (the recommended path) or a custom ChannelRunner. See the quick start below. (Old: discord({ botToken, appId, guildId }) + channel.start(); New: discord() + new CopilotRuntime({ intelligence, channels }).)

Install

pnpm add @copilotkit/channels-discord @copilotkit/channels @copilotkit/channels-ui

Quickstart

import { createChannel } from "@copilotkit/channels";
import {
  discord,
  defaultDiscordTools,
  defaultDiscordContext,
} from "@copilotkit/channels-discord";
import { CopilotRuntime } from "@copilotkit/runtime";
import { HttpAgent } from "@ag-ui/client";

const bot = createChannel({
  name: "support",
  agent: new HttpAgent({ url: process.env.AGENT_URL! }), // or "billing" | router | omitted→"default"
  adapters: [discord()], // credential-free
  tools: [...defaultDiscordTools, ...appTools], // lookup_discord_user + your tools
  context: [...defaultDiscordContext, ...appContext], // tagging/formatting/thread guidance
  commands: [
    {
      name: "triage",
      description: "Summarize the thread and propose issues.",
      async handler({ thread, text }) {
        await thread.runAgent({ prompt: `Triage: ${text}` });
      },
    },
  ],
});

bot.onMention(({ thread }) => thread.runAgent());

// CopilotKit Intelligence supplies the Discord bot token, connectivity, delivery, and failover:
const runtime = new CopilotRuntime({
  intelligence,
  identifyUser,
  channels: [bot],
});

discord(opts) returns a DiscordAdapter. The adapter itself holds no credentials — it only renders IR and decides what to send. The bot token, application id, and guild id live with whatever supplies connectivity (CopilotKit Intelligence's Discord connector, in the managed path). Ingress runs over the Discord Gateway (WebSocket) — no public URL required. The listener pre-filters ingress to the turns the bot should answer (@-mentions in guild channels and DMs), so a single onMention handler covers most use cases.

Response defaults

In guild channels, the bot only responds when explicitly @-mentioned — a prior bot reply in the channel does not remove that requirement.
DMs are always addressed (no mention needed).
An addressed message with no matching custom handler auto-runs the selected agent; a matching onMessage/onMention handler replaces the auto-run.
Untagged messages in a shared channel are ignored unless an onMessage handler opts in.

Credentials (now configured in CopilotKit Intelligence)

Discord still needs the same app-level credentials — they're just no longer passed to the adapter. Configure these in the CopilotKit Intelligence Discord connector instead:

Credential	Purpose
Bot token	Gateway login and REST calls.
Application ID	Used when registering slash commands.
Guild ID	(Optional) Guild ID for instant per-guild command registration in dev.

Global commands (no guild id) propagate across Discord in ~1 hour. Guild-scoped commands (with a guild id) register instantly — use them during development and switch to global for production.

Privileged intents

The connector backing this adapter requests two privileged gateway intents — MessageContent and GuildMembers. Both must be enabled in the Discord Developer Portal (your application → Bot → Privileged Gateway Intents) or Gateway login is rejected.

Message Content Intent — without it the Gateway delivers messages with an empty content string and the bot cannot read what users write.

Server Members Intent (GuildMembers) — backs member search, which powers lookup_discord_user / thread.lookupUser. Without it those lookups fail and login is rejected.

Reaction intent and partials

The connector also requests GuildMessageReactions and enables the Partials.Message and Partials.Reaction partials:

GuildMessageReactions — a non-privileged gateway intent; no toggle is needed in the Discord Developer Portal (unlike MessageContent and GuildMembers). Required to receive reaction events in guild channels.

DirectMessageReactions — also non-privileged; required to receive reaction events in DMs. Discord.js v14 treats guild and DM reactions as separate intents — both are needed if the bot operates in DMs.

Partials.Message + Partials.Reaction — Discord only includes full message objects in the reaction event payload when the message is already in the client's in-memory cache. For any message that was sent before the bot started (or was evicted from cache), the payload arrives as a partial. Enabling these two partials lets the listener fetch the full object on demand via reaction.fetch() / reaction.message.fetch(), so reactions on older messages are not silently dropped.

What it provides

JSX → Components V2 rendering

renderDiscordMessage(ir) translates the @copilotkit/channels-ui vocabulary to a ready-to-send Discord Components V2 payload ({ components, flags }) with the IS_COMPONENTS_V2 flag (MessageFlags.IsComponentsV2) set. It builds on renderComponents(ir), the lower-level building block, which returns a bare ContainerBuilder with no flag. The entire message is wrapped in a single Container; child nodes map as follows:

bot-ui element	Discord output
`Message`	`Container` (accent color → `setAccentColor`)
`Header`	`TextDisplay` with `#` prefix
`Section` / `Markdown`	`TextDisplay`
`Fields`	`TextDisplay` — each field as a bold-label line
`Context`	`TextDisplay` — each part as a `-# subtext` line
`Actions`	One or more `ActionRow`s
`Button`	`Button` (custom_id = minted opaque `ck:` id)
`Select`	`StringSelect` (custom_id = minted opaque `ck:` id)
`Image`	`MediaGallery` with a single item
`Divider`	`Separator`
`Table`	`TextDisplay` — fenced code block via `discordMarkdown`

Per-element budget

Discord caps every element. The renderer degrades by truncate-with-overflow / clamp — it never silently drops content. Limits live in DISCORD_LIMITS:

Limit	Value	Element
`componentsPerMessage`	40	total (nested) components per message
`actionRows`	5	action rows per message
`buttonsPerRow`	5	buttons per action row
`selectOptions`	25	options per string select
`textDisplayChars`	2000	chars per TextDisplay
`buttonLabel`	80	button label chars
`customId`	100	`custom_id` chars
`headerText`	256	header line chars (`#` TextDisplay)

Streaming

thread.stream(...) posts a plain-text placeholder and edits it in place via ChunkedMessageStream: throttled message.edit calls at ~1100 ms intervals, 2000-char chunking, mid-stream bracket auto-close, and Markdown → Discord-flavored Markdown translation so the in-flight message always renders.

Interactions (ack-first)

Every interactionCreate event (button click, string select) is immediately acknowledged with deferUpdate (within the ≤3s deadline, ackDeadlineMs = 3000). decodeInteraction then extracts the opaque minted id (ck:…) from the custom_id, and hands an InteractionEvent to the engine. The token carries only the opaque id — no props or secrets. Unrelated clicks decode to events the bot harmlessly ignores.

Human-in-the-loop

Use thread.awaitChoice(<Picker .../>) to post an interactive message and block until a click resolves it; the resolved value is the clicked control's value. Agent interrupts (on_interrupt) are captured by the run renderer and dispatched to your onInterrupt handler, which posts a picker; the click resumes the agent via thread.resume(value).

Modals

openModal(view) opens a Discord modal in response to a button click or slash command. The call must happen before any other response (within Discord's 3-second acknowledgement window) — open the modal first, then do long-running work in a follow-up message.

Validation re-open is not supported on Discord. When a user submits a modal, a bot.onModalSubmit handler may return { errors }, but Discord has no API to re-open the same modal with per-field validation errors (unlike Slack's response_action: "errors" mechanic). The { errors } result is ignored by the adapter — the modal is acknowledged with deferUpdate regardless. Validate inputs before calling openModal, or post a follow-up message to report any submission errors.

Only TextInput fields are supported in Discord modals. ModalSelect and RadioButtons elements are rejected at render time with a ModalRenderError (which openModal surfaces as { ok: false, error }).

Ephemeral messages

Discord ephemeral messages are interaction-scoped — Discord only supports them as the initial response to a button click or slash command, and they cannot be sent outside that 3-second window. For this reason supportsEphemeral is advertised as false.

thread.postEphemeral(user, ui, { fallbackToDM: true }) works around this by sending the message as a DM to the target user when native ephemeral is unavailable. The result carries { ok: true, usedFallback: true } so callers can detect that a DM was used instead of an in-channel ephemeral.

With { fallbackToDM: false } and no live interaction, postEphemeral returns null (the documented no-fallback sentinel).

Future enhancement: native interaction-ephemeral follow-up (calling interaction.followUp({ ephemeral: true, … }) within the ack window) is a planned addition. Once plumbed, supportsEphemeral will be upgraded to true for interaction contexts and usedFallback will return false.

Typing indicator and reactions

The adapter supports both Discord-native capabilities:

Typing indicator — channel.sendTyping() is called at the start of each run, giving users immediate feedback.
Reactions — supportsReactions: true is advertised; the engine can add emoji reactions during processing.

Sender-profile resolution

The adapter resolves each turn's Discord user id to a PlatformUser ({ id, name?, handle? }), cached per id. Note that Discord bots cannot read user email addresses — PlatformUser.email is always undefined on this platform. Inbound file attachments can be downloaded and delivered to the agent as multimodal content parts (buildFileContentParts); a tool can post a file back out via thread.postFile(...).

Built-ins

defaultDiscordTools — ships lookup_discord_user so the agent can resolve a name/handle to a <@USERID> mention. Spread into tools.
defaultDiscordContext — tagging procedure, Discord Markdown formatting guidance, and the Discord channel/thread conversation model. Spread into context.

Tool context

Tools receive the single shared ChannelToolContext from @copilotkit/channels ({ thread, message?, user?, signal?, platform }) and reach Discord power only through capability-gated thread methods, which this adapter backs:

thread.getMessages() — the current channel's recent messages (via channel.messages.fetch), each a ThreadMessage ({ user?, text, ts?, isBot? }).
thread.lookupUser(query) — resolve a name/handle to a PlatformUser by searching guild members.
thread.postFile({ bytes, filename, title?, altText? }) — upload a file into the channel as an attachment.

This keeps tools portable: define them with defineChannelTool({...}) and they work against any adapter that advertises the same capabilities.

Slash commands

Slash commands are registered up front when the Channel starts, via registerCommands. When a guild id is configured they register to that guild instantly; without one they register globally and take ~1 hour to propagate. Register handlers with bot.onCommand:

bot.onCommand({
  name: "triage",
  description: "Summarize the thread and propose issues.",
  options: {
    // Optional JSON Schema for native Discord slash-command options.
    // Generates typed Discord option descriptors via jsonSchemaToDiscordOptions.
  },
  async handler({ thread, text, user, rawOptions }) {
    await thread.runAgent({ prompt: `Triage: ${text}` });
  },
});

Unlike Slack, commands are registered programmatically — there is no manifest file. Discord delivers native structured option values via rawOptions when the command's options schema is provided; args also arrive flattened as free text in ctx.text.

App setup (OAuth scopes, bot permissions, invite URL) is done via the Discord Developer Portal and the OAuth2 invite flow.

What's NOT in v1

Modal limitations — text-input modals are supported (up to 5 fields). ModalSelect and RadioButtons elements are rejected at render time. Validation re-open (response_action: "errors") is not supported — Discord has no API for it; submit errors should be posted as a follow-up message instead.
OAuth / multi-guild install (single bot token only)
Durable (Redis/DB) ActionStore — in-memory only; actions expire on restart
Proactive posting (bot replies only to turns it's part of)
Auto-sharding (single Client instance)
Native interaction-ephemeral (supportsEphemeral is false; use thread.postEphemeral(user, ui, { fallbackToDM: true }) for a DM-based workaround)

Running without CopilotKit Intelligence

Running Channels without CopilotKit Intelligence requires implementing a custom ChannelRunner (an advanced, exported-but-undocumented escape hatch that supplies its own connectivity, credentials, delivery, and failover).

Exports

discord, DiscordAdapter, DiscordAdapterOptions; DiscordConversationStore; attachDiscordListener, ListenerConfig, ClientLike, IncomingCommandRaw; createRunRenderer, ChannelLike; decodeInteraction; conversationKeyOf, ReplyTarget, IncomingTurn; renderComponents, renderDiscordMessage, DISCORD_LIMITS; discordMarkdown; MessageStream, MessageStreamConfig; ChunkedMessageStream, ChunkedMessageStreamConfig; autoCloseOpenMarkdown; registerCommands, jsonSchemaToDiscordOptions; buildFileContentParts, DiscordAttachmentRef, AgentContentPart, FileDeliveryConfig; defaultDiscordContext, discordTaggingContext, discordFormattingContext, discordConversationModelContext; lookupDiscordUserTool, defaultDiscordTools.