# createChannel

> Declare a managed Slack or Teams Channel, its agent, handlers, tools, components, and SDK persistence.

`createChannel(options)` creates the provider-neutral Channel registered with
`CopilotRuntime({ channels })`.

## Signature [#signature]

```ts
function createChannel<TStateSchema>(
  options: CreateChannelOptions<TStateSchema>,
): Channel<ThreadStateOf<TStateSchema>>;
```

Import it from the umbrella package:

```ts
import { createChannel } from "@copilotkit/channels";
```

## Managed example [#managed-example]

```ts title="channel.ts"
const channel = createChannel({
  name: "support",
  identifyUser: "platform",
  agent: makeAgent,
  tools: [getIncident],
  context: [
    {
      description: "Response style",
      value: "Put the next action first.",
    },
  ],
});

channel.onMessage(async ({ thread, message }) => {
  await thread.runAgent({ prompt: message.text });
});
```

The Channel name is the project-unique Intelligence Code. A single managed
runtime declares both Slack and Teams for that Channel; Intelligence routes each
prepared delivery only to its originating provider.

Handlers that reply directly without `runAgent()` may omit `agent`.

## Options [#options]

| Option           | Type                                           | Notes                                                                                                                                |
| ---------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `name`           | `string`                                       | Required for managed delivery. Must match the project-unique Intelligence Code.                                                      |
| `identifyUser`   | `"platform" \| ChannelIdentifyUser`            | Required. Maps each provider actor to an application user or `null`. See the Identity and Memory guide for [Slack](/slack/identity-and-memory) or [Teams](/teams/identity-and-memory). |
| `showToolStatus` | `boolean`                                      | Managed Slack hides tool-call progress by default. Set `true` to show it; tool history remains available in Intelligence either way. |
| `replyContinuation` | `ReplyContinuationOptions`                  | Managed Slack continuation limits. Direct Slack configures the same option on `slack()`.                                             |
| `agent`          | `AbstractAgent \| (threadId) => AbstractAgent` | Required when calling `thread.runAgent()`. Not inherited from `runtime.agents`. Prefer a factory.                                 |
| `sanitizeAgentEvents` | `boolean`                                  | Defaults to `true`. Repairs the known nullable AG-UI parent-message field before strict HTTP-stream validation.                       |
| `tools`          | `ChannelTool[]`                                | Channel-level typed tools.                                                                                                           |
| `context`        | `ContextEntry[]`                               | Stable context added to every agent run.                                                                                             |
| `components`     | `ChannelComponentRegistration[] \| Record<string, ChannelComponent>` | Component definitions from `defineChannelComponent` (these become agent tools) or named JSX components. Both let the Channel rebuild callbacks after a restart. |
| `commands`       | `ChannelCommand[]`                             | Declared commands routed from provider ingress.                                                                                      |
| `store`          | `StoreConfig`                                  | State, persistence, turn concurrency (`parallel` default), transcripts, and dedup.                                                   |
| `adapters`       | `PlatformAdapter[]`                            | Developer-owned direct transports that may coexist with the cloud-hosted Intelligence adapter.                                            |
| `render`         | `RenderConfig`                                 | Image-render configuration: `renderer`, `fonts`, `stylesheets`, `width`, `height`, and `allowImageUrl`. To post JSX as an image, set `renderer`. |

The managed runtime validates `name` as lowercase kebab-case, 3 to 64 characters,
not equal to `channels`, and unique within the Runtime.

Handlers receive both the required provider `actor` and the nullable
application `user`. The SDK resolves that pair once for each incoming event.
Both objects are immutable snapshots. The SDK does not link accounts by email,
name, or handle.

Malformed callback output rejects with `channel_identity_invalid`. A callback
exception rejects with `channel_identity_failed` and never falls back to the
standard platform policy.

### Tune long Slack replies [#tune-long-slack-replies]

Slack replies continue into additional messages when they exceed one message's
soft byte limit. The defaults are 11,000 UTF-8 bytes per message and 20 messages
per reply, followed by a visible English truncation notice. Most Channels should
keep those defaults; customize them when the product needs a tighter bound or a
localized notice:

| Field | Behavior |
| ----- | -------- |
| `messageByteLimit` | Soft UTF-8 byte limit before continuing into another Slack message. |
| `maxMessages` | Maximum messages occupied by one reply before truncation. |
| `truncationMarker` | Visible notice appended when the message limit is reached. |

```ts
const channel = createChannel({
  name: "support",
  identifyUser: "platform",
  agent: makeAgent,
  replyContinuation: {
    maxMessages: 8,
    truncationMarker: "\n\n_This reply was shortened for Slack._",
  },
});
```

### Sanitize HTTP agent events [#sanitize-http-agent-events]

`sanitizeAgentEvents` defaults to `true`. It repairs the nullable
`parentMessageId` emitted by some LangGraph tool-call and interrupt streams so
strict client validation does not abort the run. The sanitizer applies only to
agents that stream over HTTP and only to the known malformed field. Set it to
`false` to forward events unchanged and let malformed events fail validation.

Every run uses a distinct result from `agent.clone()`, including when `agent` is
a factory. A custom agent whose subclass fields contain configuration should
override `clone()` to preserve that configuration without sharing mutable
per-run state. When `clone()` drops enumerable fields, Channels logs a warning
and still runs the turn.

## Registration methods [#registration-methods]

The returned Channel supports:

- `onMessage` and `onMention`
- `onWelcome`
- `onInterrupt`
- `onInteraction`
- `onCommand`
- `onReaction`
- `onThreadStarted`
- `onModalSubmit` and `onModalClose` for adapters that support modals
- `tool` to add a tool before the Channel starts

See [`Channel`](/reference/channels/classes/Channel) for handler signatures and
[`StoreConfig`](/reference/channels/types/StoreConfig) for persistence.
