Multi-Channel Support

Headless Core, Multi-Shell

Matrix OS is headless by design. The web workspace is the primary shell, and the same AI can also be reached through connected channels such as Telegram, Discord, WhatsApp, Slack, Matrix protocol, and developer tools as those surfaces are enabled.

Web Workspace     Telegram Bot     Discord Bot     Slack
      |                              |                |            |
      +--- WebSocket /ws ---+        |                |            |
                             |       |                |            |
                    Matrix Gateway
                             |
                    Dispatcher -> Kernel

Channel Architecture

The ChannelManager in packages/gateway/src/channels/ manages gateway channel adapters. Each adapter implements the ChannelAdapter interface:

start() -- begin listening (polling, webhooks, or WebSocket connections)
stop() -- gracefully shut down
send() -- format and send a message to the channel

Messages from these gateway adapters flow through the dispatcher to the kernel. The kernel's response is formatted for the originating channel via formatForChannel().

Direct WhatsApp access uses a shared Meta Cloud API sender on the platform. It links each sender to an owner and delivers requests through the canonical Chat API on that owner's primary Matrix computer. See WhatsApp for the linking flow and pilot availability.

Available Channels

Channel	Status	Transport	Configuration
Web Desktop	Built-in	WebSocket	Automatic
Telegram	Adapter	Long polling	`config.json` -> `channels.telegram.token`
Discord	Adapter	Gateway WebSocket	`config.json` -> `channels.discord.token`
Slack	Adapter	Socket Mode	`config.json` -> `channels.slack.token`
WhatsApp	Controlled pilot	Meta Cloud API	Message Matrix, sign in, and confirm the WhatsApp code
CLI	Built-in	stdin/stdout	`bin/matrixos.ts`

Configuring Channels

Gateway channel setup is handled from Matrix settings when available. Under the hood, gateway channel configuration lives in the user's Matrix system configuration so it can be backed up and restored with the rest of the workspace. The direct WhatsApp pilot has a separate platform setup; users connect through the business chat and account proof.

{
  "channels": {
    "telegram": {
      "token": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
      "allowFrom": [123456789]
    }
  }
}

The allowFrom field restricts which user IDs can interact with the bot, providing basic access control.

Hot reload

Supported gateway channel config changes are detected by the file watcher. Add a new channel token and the adapter starts automatically -- no restart needed. Direct WhatsApp availability depends on the configured platform deployment.

Channel-Aware Dispatch

The dispatcher uses a DispatchContext that includes the originating channel. This context flows through to the kernel, so agents can tailor their responses. For example, Telegram messages are formatted with Markdown, while Discord uses embeds.

The formatForChannel() function handles platform-specific formatting:

Telegram: Markdown with inline code and bold
Discord: Rich embeds with fields
Slack: Block Kit with sections and actions
WhatsApp: Plain text with limited formatting

Proactive Channels

Channels aren't just for receiving messages. The CronService and HeartbeatRunner can proactively send messages through any channel:

Cron jobs defined in ~/matrixos/system/cron.json trigger kernel invocations on a schedule
Heartbeat periodically invokes the kernel during active hours to check for tasks, health, and notifications
Proactive messages are sent back through the channel that the user most recently interacted with

The direct WhatsApp pilot supports replies within its 24-hour message window. Proactive messages and approved message templates are outside the pilot scope.