Channel Adapter API

Channel Adapter API

CortexPrism supports external platform integrations via channel adapters. Inbound messages are bridged to the Cortex agent loop via createChannelEventHandler(), and webhook-capable channels receive platform events through public webhook routes.

Interface

interface ChannelPlugin {
  readonly name: string;
  readonly protocol: string;
  readonly connected: boolean;
  connect(config: { credentials: Record<string, string>; settings: Record<string, unknown> }): Promise<void>;
  disconnect(): Promise<void>;
  onEvent(handler: (event: ChannelEvent) => Promise<void>): void;
  send(target: ChannelTarget, message: OutboundMessage): Promise<MessageId>;
  edit(target: ChannelTarget, messageId: string, updates: MessageEdit): Promise<void>;
  react(target: ChannelTarget, messageId: string, reaction: string): Promise<void>;
  delete(target: ChannelTarget, messageId: string): Promise<void>;
  typing(target: ChannelTarget): Promise<void>;
  upload(target: ChannelTarget, file: FileUpload): Promise<MessageId>;
  handleWebhook?(data: unknown): void | Response;
}

Agent-Loop Bridge

createChannelEventHandler() in src/channels/bridge.ts bridges inbound channel messages to agentTurn():

1. Maps channel conversations to Cortex sessions via the channel_sessions table (migration 028)
2. Auto-creates sessions for new conversations
3. Resolves agent config → provider → model
4. Registers all built-in tools and loads plugins
5. Builds system prompt from agent identity
6. Sends agent response back to the channel
7. Sends error responses when agentTurn() throws

Wired on channel start via both REST API and server auto-start.

Webhook Routes

GET/POST /api/channels/webhook/:protocol dispatches inbound webhook events:

• WhatsApp — verifies hub.mode/hub.challenge/hub.verify_token
• Lark — handles url_verification → {challenge}
• Google Chat, Telegram, Teams — passthrough to handleWebhook()

Routes are registered as public (no Cortex auth required) so external platforms can call them directly.

Supported Channels

Channel	File	Status
Discord	src/channels/discord.ts	Available
Discord Legacy	src/channels/discord_legacy.ts	Deprecated
Slack	src/channels/slack.ts	Available
Microsoft Teams	src/channels/teams.ts	Available
Telegram	src/channels/telegram.ts	Available
WhatsApp	src/channels/whatsapp.ts	Available
Google Chat	src/channels/google-chat.ts	Available
Lark	src/channels/lark.ts	Available
Mattermost	src/channels/mattermost.ts	Available
RocketChat	src/channels/rocketchat.ts	Available

Shared Infrastructure (src/channels/_shared/)

All channel adapters share common infrastructure located in src/channels/_shared/:

Module	Purpose
websocket_manager.ts	WebSocket connection lifecycle and reconnection management
rate_limiter.ts	Per-channel rate limiting with backpressure and queue management
logger.ts	Structured logging shared across all channel adapters
http_client.ts	Shared HTTP client with retry, auth, and error handling

Shared types (src/channels/_shared/types.ts) define the canonical cross-platform event model: message, reaction_added, reaction_removed, typing, presence, member_joined, member_left.

Channel Store

src/channels/store.ts provides persistent storage for channel state:

• Connection state — online/offline, reconnection backoff, last heartbeat
• Webhook registrations — per-channel webhook URLs and verification tokens
• Session bindings — mapping between platform conversations and agent sessions
• Message cache — recent message history for context injection

Data is stored in the channels table (migrations 028-030) in cortex.db.

Channel Manager

src/channels/manager.ts handles:

• Registration and lifecycle management for all 10 channel adapters
• Agent binding — connecting channels to agent sessions
• Event routing — mapping platform events to agent turns
• Health monitoring — heartbeat tracking and automatic reconnection

CLI

cortex channels                 # List registered channels
cortex channels start <name>    # Start a channel
cortex channels stop <name>     # Stop a channel

See Also

• CLI Reference — Channels CLI commands