> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nearai/ironclaw/llms.txt
> Use this file to discover all available pages before exploring further.

# Channel System Overview

> Multi-channel architecture for interacting with IronClaw agents

IronClaw's channel system provides a unified interface for communicating with your agent through multiple platforms and protocols.

## Architecture

Channels receive messages from external sources (CLI, messaging apps, HTTP webhooks) and convert them to a unified format for the agent to process. All responses flow back through the same channel.

```text theme={null}
┌─────────────────────────────────────────────────────────────────────┐
│                         ChannelManager                              │
│                                                                     │
│   ┌──────────────┐   ┌─────────────┐   ┌─────────────┐             │
│   │ ReplChannel  │   │ HttpChannel │   │ WasmChannel │   ...       │
│   └──────┬───────┘   └──────┬──────┘   └──────┬──────┘             │
│          │                 │                 │                      │
│          └─────────────────┴─────────────────┘                      │
│                            │                                        │
│                   select_all (futures)                              │
│                            │                                        │
│                            ▼                                        │
│                     MessageStream                                   │
└─────────────────────────────────────────────────────────────────────┘
```

## Available Channels

### Native Channels

**CLI (REPL)** - Built-in interactive terminal interface. Always available.

* Interactive command-line interface
* Command history and completion
* Debug mode toggle with `/debug`

**HTTP Webhook** - HTTP POST endpoint for programmatic access.

* POST requests with JSON payloads
* Webhook secret authentication
* Optional synchronous responses
* Rate limiting (60 req/min)

**Signal** - Native integration with Signal messenger via signal-cli.

* Direct messages and group chats
* DM pairing for access control
* Typing indicators and status updates
* Attachment support within sandbox

**Web Gateway** - Browser-based UI with rich features.

* Real-time chat via SSE or WebSocket
* Workspace/memory browser
* Job management interface
* OpenAI-compatible API proxy

### WASM Channels

WASM channels are dynamically loaded at runtime from `~/.ironclaw/channels/`:

**Telegram** - Telegram Bot API integration.

* Webhook or polling modes
* DM pairing with approval codes
* Group chat with @mention triggering
* Markdown formatting support

**Slack** - Slack Events API integration.

* App mentions and DMs
* Thread support
* Signature validation

## Message Flow

### Incoming Messages

1. **Receive** - Channel receives external input (HTTP POST, WebSocket, Signal message)
2. **Parse** - Convert to `IncomingMessage` with unified fields:
   * `id` - Unique message UUID
   * `channel` - Source channel name
   * `user_id` - Sender identifier
   * `content` - Message text
   * `thread_id` - Conversation thread (optional)
   * `metadata` - Channel-specific routing info
3. **Emit** - Forward to agent loop via message stream

### Outgoing Responses

1. **Generate** - Agent creates `OutgoingResponse`:
   * `content` - Response text
   * `thread_id` - Reply thread (optional)
   * `attachments` - File paths (optional)
2. **Route** - Channel uses stored metadata to target correct destination
3. **Send** - Channel-specific API call (Telegram sendMessage, Slack chat.postMessage, etc.)

## Status Updates

Channels can display real-time agent activity:

* **Thinking** - Agent is processing (shown as typing indicator)
* **ToolStarted/ToolCompleted** - Tool execution lifecycle
* **ToolResult** - Preview of tool output (debug mode)
* **Status** - General status messages
* **JobStarted** - Sandbox job launched (with URL)
* **ApprovalNeeded** - Tool requires user confirmation
* **AuthRequired/AuthCompleted** - Extension authentication flow

Each channel decides how to render these (e.g., typing indicator, status message, or skip).

## Access Control

All channels support three DM policies:

### `open`

Allow all users. No restrictions.

```json theme={null}
{
  "dm_policy": "open"
}
```

### `allowlist`

Only accept messages from pre-approved users. Silent drop for others.

```json theme={null}
{
  "dm_policy": "allowlist",
  "allow_from": ["+1234567890", "alice", "*"]
}
```

### `pairing` (default)

Combines allowlist with interactive pairing. Unknown users receive a pairing code:

```
To pair with this bot, run: ironclaw pairing approve telegram ABC12345
```

After approval, they're added to the persistent allow list.

```json theme={null}
{
  "dm_policy": "pairing",
  "allow_from": ["+1234567890"]
}
```

### Owner Restriction

Set `owner_id` to lock the channel to a single user (overrides all DM policies):

```json theme={null}
{
  "owner_id": "123456789"
}
```

## Configuration Files

WASM channels use a `.capabilities.json` file to declare:

* **HTTP allowlist** - Permitted API endpoints
* **Secrets** - Required credentials (bot tokens, signing secrets)
* **Rate limits** - Requests per minute/hour
* **Webhooks** - Allowed paths and secret validation
* **Polling** - Minimum interval for getUpdates-style APIs

Example:

```json theme={null}
{
  "type": "channel",
  "name": "telegram",
  "capabilities": {
    "http": {
      "allowlist": [
        { "host": "api.telegram.org", "path_prefix": "/bot" }
      ],
      "rate_limit": {
        "requests_per_minute": 30
      }
    },
    "secrets": {
      "allowed_names": ["telegram_*"]
    }
  }
}
```

## Channel Lifecycle

1. **on\_start()** - Initialize, register webhooks, validate tokens
2. **start()** - Begin listening for messages (returns `MessageStream`)
3. **respond()** - Send response back to user
4. **send\_status()** - Broadcast status updates
5. **health\_check()** - Verify channel is operational
6. **shutdown()** - Graceful cleanup (delete webhooks, close connections)

## Thread Support

Channels use `thread_id` for conversation continuity:

* **Telegram** - Generates deterministic UUID from sender/group ID
* **Slack** - Uses Slack's native `thread_ts`
* **Signal** - Uses `source_uuid` or phone-based UUID
* **HTTP** - Optional `thread_id` in request payload
* **Web Gateway** - WebSocket connection or SSE client ID

The agent's `maybe_hydrate_thread` loads conversation history when a thread ID matches a stored session.

## Rate Limiting

Channels enforce rate limits to prevent abuse:

* **HTTP Webhook** - 60 requests/minute
* **Telegram** - 30 API calls/minute
* **Slack** - 50 API calls/minute
* **Web Gateway** - 30 chat messages/minute

Exceeding limits returns HTTP 429 (Too Many Requests).

## Security

### Webhook Secrets

HTTP-based channels require secret validation:

* **HTTP** - `HTTP_WEBHOOK_SECRET` in request body
* **Telegram** - `X-Telegram-Bot-Api-Secret-Token` header
* **Slack** - HMAC signature validation with signing secret

The host validates secrets before forwarding to WASM channels.

### Sandboxing (WASM Channels)

WASM channels run in a secure sandbox:

* No filesystem access (except workspace via host APIs)
* HTTP limited to declared allowlist
* No raw credential access (host injects tokens via URL placeholders)
* Emit rate limits prevent message floods

### Path Validation

Attachment paths are validated to prevent traversal attacks:

```rust theme={null}
// Only paths within ~/.ironclaw/ are allowed
validate_attachment_paths(&["/home/user/.ironclaw/files/report.pdf"])
```

## Next Steps

* [Telegram Setup](/channels/telegram) - Configure Telegram bot
* [Slack Setup](/channels/slack) - Configure Slack app
* [Signal Setup](/channels/signal) - Install signal-cli daemon
* [HTTP Webhook](/channels/http) - Programmatic API access
* [Web Gateway](/channels/web-gateway) - Browser UI