# Channels SDK Documentation > Technical documentation for @copilotkit/channels — the SDK that connects any AG-UI-compatible agent to Slack, Microsoft Teams, Discord, Telegram, and WhatsApp with native interactive UI. For developers building, wiring, and operating a long-running Channels listener. ## Context Links - [Agent index](https://grok-wiki.com/public/docs/copilotkit-channels-sdk-4c947e3e6161/llms.txt) - [Human interactive docs](https://grok-wiki.com/public/docs/copilotkit-channels-sdk-4c947e3e6161) - [GitHub repository](https://github.com/CopilotKit/channels-sdk) ## Repository Metadata - Repository: CopilotKit/channels-sdk - Generated: 2026-08-05T06:44:14.357Z - Updated: 2026-08-05T06:44:30.818Z - Runtime: Claude Code - Format: Documentation - Pages: 20 ## Page Index - 01. [Overview](https://grok-wiki.com/public/docs/copilotkit-channels-sdk-4c947e3e6161/pages/01-overview.md) - What the Channels SDK exposes: the five-piece mental model (Channel, Thread, Tools, UI, Context), the you-run vs Intelligence-manages boundary, runtime assumptions (Node.js 22+, long-running process, no serverless), and the shortest path to a first online Channel. - 02. [Installation](https://grok-wiki.com/public/docs/copilotkit-channels-sdk-4c947e3e6161/pages/02-installation.md) - Install @copilotkit/channels with @copilotkit/runtime as a version-locked pair, enforce ESM with npm pkg set type=module, pin @ag-ui/client via overrides to avoid the duplicate-AbstractAgent compile failure, and configure tsconfig with jsxImportSource for the Channels JSX runtime. - 03. [Quickstart](https://grok-wiki.com/public/docs/copilotkit-channels-sdk-4c947e3e6161/pages/03-quickstart.md) - Build the first managed Channel: create the Channel in CopilotKit Intelligence, write the createChannel + CopilotRuntime + createCopilotNodeListener listener, set the four environment variables, start with node --env-file, and verify status().overall === "online" before trusting the deploy. - 04. [Set up with a coding agent](https://grok-wiki.com/public/docs/copilotkit-channels-sdk-4c947e3e6161/pages/04-set-up-with-a-coding-agent.md) - The agent-driven setup path: npx copilotkit@latest channels setup, the hosted channels-guide.md workflow, installing setup-slack-channel via the CLI instead of vendoring it, and how this repository's canonical .agents/skills layout and .claude symlink keep the build-channels-agent skill authoritative. - 05. [Architecture and the runtime boundary](https://grok-wiki.com/public/docs/copilotkit-channels-sdk-4c947e3e6161/pages/05-architecture-and-the-runtime-boundary.md) - How a turn flows: platform event → Intelligence ingress → your Channels process → agent over AG-UI → native UI back into the conversation. What you host (agent, tools, listener, state) versus what Intelligence manages (platform credentials, ingress, delivery, reconnects), and why a Channel needs a persistent gateway connection. - 06. [Channel lifecycle and status](https://grok-wiki.com/public/docs/copilotkit-channels-sdk-4c947e3e6161/pages/06-channel-lifecycle-and-status.md) - The runtime owns the lifecycle — there is no channel.start(). Listener creation starts the Channel; channels.ready() settles activation but also resolves on setup_required; the six SDK status values (connecting, online, setup_required, reconnecting, error, stopped) versus the Intelligence dashboard states; teardown ordering for SIGINT/SIGTERM. - 07. [Managed Channels vs direct adapters](https://grok-wiki.com/public/docs/copilotkit-channels-sdk-4c947e3e6161/pages/07-managed-channels-vs-direct-adapters.md) - The managed default (no adapter, Channel Code from Intelligence, no platform tokens in your process) versus the direct-adapter path (adapters: [slack({ botToken, appToken })], Socket Mode, defaultSlackTools/defaultSlackContext). When each applies, and why switching to a direct adapter to escape setup_required is a known failure mode. - 08. [Handle mentions, messages, and subscriptions](https://grok-wiki.com/public/docs/copilotkit-channels-sdk-4c947e3e6161/pages/08-handle-mentions-messages-and-subscriptions.md) - Wire the ten channel handlers — onMention, onMessage, onThreadStarted, onWelcome, onCommand, onInteraction, onInterrupt, onReaction, onModalSubmit, onModalClose — reply on mention with thread.runAgent(), forward contentParts explicitly, and use subscribe()/isSubscribed() to answer every message in an invited conversation. - 09. [Add tools](https://grok-wiki.com/public/docs/copilotkit-channels-sdk-4c947e3e6161/pages/09-add-tools.md) - Define typed agent tools with defineChannelTool and any Standard Schema validator (Zod, Valibot, ArkType): the ChannelToolContext shape ({ thread, message?, user, actor, signal?, platform }), return-value rules (raw data back to the agent, error text on failure), and registration via createChannel({ tools }) or channel.tool(). - 10. [Render interactive UI](https://grok-wiki.com/public/docs/copilotkit-channels-sdk-4c947e3e6161/pages/10-render-interactive-ui.md) - Post one JSX tree that lowers to Block Kit, Adaptive Cards, or Discord components: thread.post/update/delete, inline onClick/onSelect handlers with content-stable IDs, graceful degradation on surfaces that skip unsupported nodes, and agent-rendered components via defineChannelComponent (0.7+). - 11. [Human-in-the-loop approvals](https://grok-wiki.com/public/docs/copilotkit-channels-sdk-4c947e3e6161/pages/11-human-in-the-loop-approvals.md) - Gate agent actions on humans: thread.awaitChoice to block a tool handler on a typed button choice, onInterrupt + thread.resume for agent-originated pauses (LangGraph-style interrupts), and making approval buttons survive restarts with a durable StateStore adapter plus registered components. - 12. [Slash commands and modals](https://grok-wiki.com/public/docs/copilotkit-channels-sdk-4c947e3e6161/pages/12-slash-commands-and-modals.md) - Handle commands with channel.onCommand — arguments arrive as raw text (options is populated only on structured surfaces like Discord) — hand them to the agent explicitly, and open modals with ctx.openModal calling Modal({...}) as a function (not JSX), routing submissions by callbackId to onModalSubmit/onModalClose. - 13. [Author a platform adapter](https://grok-wiki.com/public/docs/copilotkit-channels-sdk-4c947e3e6161/pages/13-author-a-platform-adapter.md) - Implement the PlatformAdapter contract for a new surface: ingress via start(sink), egress rendering of ChannelNode[] with a total renderer that skips unsupported nodes, createRunRenderer for live agent streaming, decodeInteraction with content-stable ID recovery, and the declared capabilities object. - 14. [createChannel reference](https://grok-wiki.com/public/docs/copilotkit-channels-sdk-4c947e3e6161/pages/14-createchannel-reference.md) - Every createChannel option with constraints: required identifyUser ("platform" or a callback), Channel Code naming rules for name, the agent factory contract and per-turn cloning, adapters, tools, context, components, commands, store (adapter, state schema, actionRetentionMs, concurrency), showToolStatus, replyContinuation, and sanitizeAgentEvents. - 15. [Thread API reference](https://grok-wiki.com/public/docs/copilotkit-channels-sdk-4c947e3e6161/pages/15-thread-api-reference.md) - The per-conversation thread handle: post, update, delete, stream, postFile, postEphemeral, runAgent (prompt, context, tools, transcript, memory grants), resume, awaitChoice, subscribe/unsubscribe/isSubscribed, getMessages, setTitle, setSuggestedPrompts, react, state/setState, and lookupUser — including which methods are capability-gated and degrade instead of throwing. - 16. [UI components reference](https://grok-wiki.com/public/docs/copilotkit-channels-sdk-4c947e3e6161/pages/16-ui-components-reference.md) - The full channels-ui JSX vocabulary with props and degradation rules: layout components (Message, Header, Section, Markdown, Fields, Field, Context, Divider, Image, Table, Chart), interactive components (Actions, Button, Select, Input), modal components (Modal, TextInput, ModalSelect, RadioButtons), and handler context shapes. - 17. [Configuration reference](https://grok-wiki.com/public/docs/copilotkit-channels-sdk-4c947e3e6161/pages/17-configuration-reference.md) - Environment variables and project configuration: INTELLIGENCE_API_KEY, CHANNEL_CODE, PORT, the paired INTELLIGENCE_API_URL / INTELLIGENCE_GATEWAY_WS_URL overrides (bare base URLs, never derived from each other), AGENT_URL for remote AG-UI agents, plus the required tsconfig (jsxImportSource, module settings) and package.json shape (type: module, overrides pin). - 18. [Minimal Channel example](https://grok-wiki.com/public/docs/copilotkit-channels-sdk-4c947e3e6161/pages/18-minimal-channel-example.md) - The smallest complete listener, file by file: lib/channel.ts (createChannel plus onMention/onMessage with the subscribe pattern), lib/runtime.ts (CopilotRuntime with an explicit CopilotKitIntelligence connection), lib/env.ts (fail-fast env loading), and server.ts (ready() gate, HTTP server, SIGINT teardown) — with the 🪁 no-model-call verification trick. - 19. [OpenTag reference application](https://grok-wiki.com/public/docs/copilotkit-channels-sdk-4c947e3e6161/pages/19-opentag-reference-application.md) - The flagship Channels app vendored as a pinned git submodule: what it demonstrates (Python LangGraph agent over AG-UI, Slack and Teams surfaces, file-aware prompts, approval-gated Linear/Notion writes), how to fetch it with git submodule update --init, its prerequisites, and the deliberate one-line workflow for bumping the pin. - 20. [Troubleshooting](https://grok-wiki.com/public/docs/copilotkit-channels-sdk-4c947e3e6161/pages/20-troubleshooting.md) - Documented failure modes with fixes: the duplicate @ag-ui/client "_debug private property" compile error, TS1309 from missing type: module, TS2345 ModalView narrowing, JSX compiled against React, setup_required and Waiting for runtime states, ready() resolving on a degraded Channel, Unknown option '--skill' from a stale CLI, and the invented Bot-prefixed APIs that never existed. ## Source File Index - `.agents/skills/build-channels-agent/evals/evals.json` - `.agents/skills/build-channels-agent/references/adapter-authoring.md` - `.agents/skills/build-channels-agent/references/hitl-patterns.md` - `.agents/skills/build-channels-agent/references/ui-components.md` - `.agents/skills/build-channels-agent/SKILL.md` - `.gitmodules` - `AGENTS.md` - `examples/minimal-channel/.env.example` - `examples/minimal-channel/lib/channel.ts` - `examples/minimal-channel/lib/env.ts` - `examples/minimal-channel/lib/runtime.ts` - `examples/minimal-channel/package.json` - `examples/minimal-channel/README.md` - `examples/minimal-channel/server.ts` - `examples/minimal-channel/tsconfig.json` - `examples/README.md` - `README.md` --- ## 01. Overview > What the Channels SDK exposes: the five-piece mental model (Channel, Thread, Tools, UI, Context), the you-run vs Intelligence-manages boundary, runtime assumptions (Node.js 22+, long-running process, no serverless), and the shortest path to a first online Channel. - Page Markdown: https://grok-wiki.com/public/docs/copilotkit-channels-sdk-4c947e3e6161/pages/01-overview.md - Generated: 2026-08-05T06:37:48.127Z ### Source Files - `README.md` - `.agents/skills/build-channels-agent/SKILL.md` - `examples/minimal-channel/package.json` - `AGENTS.md` --- title: "Overview" description: "What the Channels SDK exposes: the five-piece mental model (Channel, Thread, Tools, UI, Context), the you-run vs Intelligence-manages boundary, runtime assumptions (Node.js 22+, long-running process, no serverless), and the shortest path to a first online Channel." --- The Channels SDK (`@copilotkit/channels`, MIT-licensed) connects one AG-UI-compatible agent to Slack, Microsoft Teams, Discord, Telegram, and WhatsApp with native interactive UI. You write handlers, tools, and JSX-rendered messages once; per-platform adapters translate the same message tree into Slack Block Kit, Teams Adaptive Cards, or Discord components. The agent keeps its own model, tools, and business logic — the built-in agent, LangGraph, CrewAI, Mastra, Pydantic AI, Google ADK, or any custom AG-UI agent all attach through the same `agent` factory. This repository carries the docs entry point, the `build-channels-agent` skill (the API authority under `.agents/skills/`), and runnable examples; the SDK implementation itself lives in `CopilotKit/CopilotKit` under `packages/channels`. ## The five-piece mental model Every Channels program is built from the same five pieces: | Piece | What it is | Primary API | | --- | --- | --- | | **Channel** | The unit you configure and attach handlers to | `createChannel()` returns a `Channel` | | **Thread** | The per-conversation handle passed to every handler; you render and drive the conversation through it | `thread.post`, `thread.runAgent`, `thread.awaitChoice`, `thread.subscribe`, … | | **Tools** | Typed functions the agent can call, validated by any Standard Schema library (Zod, Valibot, ArkType) | `defineChannelTool` | | **UI** | JSX from `@copilotkit/channels` that renders natively per platform and degrades gracefully where a node is unsupported | ``, `
`, ``, ` , ); return ok; } ``` Inside a tool, the pattern ends with a natural-language result for the agent, not a status object: ```tsx if (!ok) return "User cancelled; nothing was deployed."; ``` Constraints that apply to any `awaitChoice` tree: - The clicked `Button`'s `value` is what the promise resolves to, typed as `T`. A `Button` with `url` set becomes a link button and its `value`/`onClick` are ignored, so it cannot resolve a choice. - The Channels JSX runtime declares an empty `IntrinsicElements` — ``, ``, `
` are compile errors. Emphasis belongs inside ``. - The file must be `.tsx` and the project's tsconfig must set `jsxImportSource: "@copilotkit/channels"`; otherwise the tree compiles against React and fails. - For a multi-option approval, a ` or ``` `thread.stream(src)` accepts a plain string or an `AsyncIterable` and progressively edits a live message as tokens arrive. `thread.postFile({ ... })` uploads a file where the adapter implements the `postFile` capability. `thread.postEphemeral(user, ui, { fallbackToDM })` targets a single user; the options argument is required. ## runAgent `thread.runAgent(input?)` drives the agent's run / tool-call / interrupt loop and renders each step as it streams. Prefer it over hand-managing agent events. Called with no arguments, `prompt` defaults to the inbound `message.contentParts` or `message.text`, so plain `runAgent()` is the correct mention reply: ```ts channel.onMention(async ({ thread }) => { await thread.runAgent(); }); ``` Pass `prompt` explicitly only when the input is not in reconstructed history — slash-command arguments, or when combining text and attachments yourself: ```ts channel.onMessage(async ({ thread, message }) => { await thread.runAgent({ prompt: message.contentParts?.length ? [ ...(message.text ? [{ type: "text" as const, text: message.text }] : []), ...message.contentParts, ] : message.text, context: [{ description: "Originating platform", value: message.platform }], }); }); ``` The user turn for this run. Defaults to the inbound message's `contentParts` or `text` when omitted. Slash-command arguments are never posted to the channel, so they are not in reconstructed history — pass them explicitly (`runAgent({ prompt: \`Triage: ${text}\` })`). `{ description: string; value: string }` pairs injected into the agent's prompt for this run only. Channel-wide context goes on `createChannel({ context })` instead. Extra tools available for this run, in addition to those registered via `createChannel({ tools })` or `channel.tool()`. Auto-bridges cross-platform transcripts: injects history, appends the user turn, runs, appends the reply. The flag owns the whole bridge — do not also append the same turns via `channel.transcripts.append`. It no-ops with a warning when identity or transcripts are not configured. Intelligence Memory grant for this run only, where each grant is `"none" | "read" | "read-write"` (e.g. `{ user: "read-write", project: "read" }`). Omitting `memory` disables Memory entirely — there is no implicit access. ## resume `thread.resume(value, opts?)` re-enters the run loop after the agent paused itself mid-run (a LangGraph-style interrupt surfaced through `channel.onInterrupt`). It returns the next `MessageRef`, or `undefined`. The options take the same `memory` grant shape as `runAgent`, plus `subject`: ```ts channel.onInterrupt<{ question: string }>("ask_human", async ({ thread, payload }) => { const answer = await thread.awaitChoice( /* a ` Selection handler. `ctx.action.value` is a `string`, or `string[]` when `multi` is set. The selectable options. Placeholder text. Multi-select. Renders as `multi_static_select` on Slack, max-values on Discord, `isMultiSelect` on Teams; Telegram and WhatsApp degrade to single-select. ### `` Submit handler. `ctx.action.value` is the entered text. Placeholder text. Multi-line text entry. Field name. ```tsx ` — Telegram and WhatsApp degrade to single-select. - Capability-gated thread methods degrade rather than throw (`getMessages()` returns `[]`, `lookupUser()` returns `undefined`) — the same philosophy applied to the Thread API. ## Handler durability Inline `onClick`/`onSelect` handlers are bound by **content-stable IDs**: `"ck:" + sha1(name | path | stableStringify(props)).slice(0, 16)`. The same rendered control always produces the same ID, so a click long after posting still resolves to the right handler — as long as the binding still exists. - Inline handlers route **in-process only**. The default `MemoryStore` is ephemeral, so bindings are lost on restart and a button clicked after a redeploy won't resolve. - Handlers on a **registered component** (`createChannel({ components })`) with a durable store configured (`createChannel({ store: { adapter, actionRetentionMs } })`) survive a restart; `actionRetentionMs` defaults to 7 days. Without registration, a click on a pre-restart message degrades to "action expired". ## Choosing components - Announce or inform → `` with `
`, `
`, ``, ``. - Offer discrete choices → `` with `