Channel

createChannel(options) returns the Channel you declare on CopilotRuntime({ channels }).

import { createChannel } from "@copilotkit/channels";
import { makeAgent } from "./agent.js";

const channel = createChannel({
  name: "support",
  identifyUser: "platform",
  agent: makeAgent,
});

Use the project-unique Intelligence Channel Code. The managed runtime declares both Slack and Teams for this Channel and keeps each delivery provider-scoped.

createChannel options

One Channel may receive managed Slack and Teams deliveries. Names must be unique inside one CopilotRuntime.

For long-reply defaults, event sanitization, and agent clone requirements, see the detailed createChannel options.

StoreConfig

StateStore contains kv, list, lock, dedup, and queue facets. Remote implementations must preserve JSON-serializable values.

StateStore contract

A production adapter implements this asynchronous contract. Locks, deduplication, and queue operations must remain atomic when multiple runner instances share the same backend.

interface StateStore {
  kv: {
    get<T>(key: string): Promise<T | undefined>;
    set<T>(key: string, value: T, ttlMs?: number): Promise<void>;
    consume<T>(key: string): Promise<T | undefined>;
    delete(key: string): Promise<void>;
  };
  list: {
    append<T>(
      key: string,
      value: T,
      options?: { maxLen?: number; ttlMs?: number },
    ): Promise<number>;
    range<T>(key: string, start?: number, stop?: number): Promise<T[]>;
    trim(key: string, maxLen: number): Promise<void>;
    delete(key: string): Promise<void>;
  };
  lock: {
    acquire(
      key: string,
      options?: { ttlMs?: number },
    ): Promise<{ token: string } | null>;
    release(key: string, token: string): Promise<void>;
  };
  dedup: {
    // true means the key was already recorded inside the TTL.
    seen(key: string, ttlMs: number): Promise<boolean>;
  };
  queue: {
    enqueue<T>(
      key: string,
      value: T,
      options?: {
        maxSize?: number;
        onFull?: "drop-oldest" | "drop-newest";
      },
    ): Promise<number>;
    dequeue<T>(key: string): Promise<T | undefined>;
    depth(key: string): Promise<number>;
  };
}

All values must round-trip through JSON. A distributed implementation must release a lock only when the supplied token still owns it.

Properties

The transcripts getter is only available after Channel activation and throws if it is read before the runtime listener starts the Channel.

Message handlers

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,
  });
});

message.platform is the native provider ("slack" or "teams"). thread.platform carries that same native provider on a managed Channel.

Interaction and interrupt handlers

See the Slack interactive messages guide, the Teams interactive messages guide, and the JSX callback reference.

Register a tool

Pass tools in createChannel({ tools }), or add one before activation:

channel.tool(getIncident);

See Tools and context for Slack or Tools and context for Teams.

Runtime lifecycle

A Channel has no public start() method. Node and Express listeners own a long-running process lifetime, so creating either listener starts the managed Channel automatically. On those mounts, ready() is optional: await it when startup must observe the initial managed status before the rest of the process continues.

Hono and generic Fetch mounts are request-oriented and remain lazy. Call and await ready() during an explicit long-running startup path before expecting managed traffic; creating one of those handlers alone does not open the Realtime Gateway connection.

Install shutdown handlers before waiting for readiness so a slow or incomplete provider setup cannot prevent graceful teardown:

const listener = createCopilotNodeListener({ runtime });

const channels = listener.channels;
if (!channels) throw new Error("Channels were not configured.");

const shutdown = async () => {
  await channels.stop();
  process.exit(0);
};

process.once("SIGTERM", shutdown);
process.once("SIGINT", shutdown);

await channels.ready({ timeoutMs: 30_000 });
const status = channels.status();
if (status.overall !== "online") {
  throw new Error(`Channel not online: ${JSON.stringify(status)}`);
}

ready() observes the first online or setup_required outcome; it does not initiate Node or Express activation. Inspect status() before accepting managed traffic. A configured direct adapter still starts when managed setup is incomplete, while the Channel remains setup_required until its managed providers are configured. Observe later drops and reconnects through status().