Channels

Octipus supports multiple communication channels, allowing you to interact with your agents from wherever you work. All channels route through the Gateway Hub — a central WebSocket entry point with unified authentication, event routing, and rate limiting.

Architecture

Every channel connects through the Gateway Hub, which handles auth, rate limiting, and event routing:

Telegram ──┐
Slack ─────┤
Teams ─────┤
WhatsApp ──┼──► Gateway Hub ──► Orchestrator ──► Worker(s) ──► Gateway Hub ──► Channel
WebChat ───┤
TUI ───────┘

The Gateway Hub provides:

Typed WebSocket protocol (Zod-validated messages)
Multi-auth — session tokens, local file tokens (TUI), HMAC keys (adapters), API keys
Central event bus — pub/sub with pattern matching and per-session replay
12 gateway commands — /help, /status, /expert, /abort, /clear, /compact, /think, /verbose, /usage, /cost, /diff, /version
Rate limiting — per-connection, per-action, trust-level-aware
Real-time emoji reactions — agent lifecycle feedback on all channels (👀→🧠→🔧→✅)
Typing indicators — repeating typing status while agent works (4s refresh for Telegram)
Stall detection — 😐 after 15s, 😬 after 45s without progress

Channels support hot-reload — change a setting in the web UI and the channel reconnects automatically.

Channel Feedback

All external channels (Telegram, Slack, WhatsApp, Teams) provide real-time emoji reactions on user messages:

Phase	Emoji	Meaning
Received	👀	Message received, queued
Working	💻🔍✍️🧠	Role-specific (coding, research, writing, etc.)
Tool use	📖💻🔍🐳💬🔧	Tool-specific during execution
Permission	⏳	Waiting for user approval
Done	✅	Completed successfully
Failed	❌	Error occurred

Permission prompts show tool details (file path, command, URL) so you know exactly what you’re approving.

Terminal UI (TUI)

A terminal-based chat interface connecting via the gateway protocol with local-token auth. No password needed — auto-generated token at ~/.octipus/local-token.

assistant tui        # If installed via bin/octi
bun run src/tui/index.tsx  # Direct

Features:

Braille spinner with current tool and model display during agent execution
Token/cost tracking in header, per-agent stats after completion
Permission prompts — inline yellow-bordered prompt with y/n approval
Expert footer — active expert and session ID always visible below chat
Full terminal clear — /clear clears screen, scrollback, and stats
Commands — /cost, /diff, /version, /expert, /help, /status, and more
Matte color theme — optimized for dark/transparent terminal backgrounds

Built with grammY. Uses long polling by default — no public URL required.

Setup

Message @BotFather on Telegram
Send /newbot and follow the prompts
Copy the bot token
Add it in Settings > Channels or set TELEGRAM_BOT_TOKEN

Configuration

Setting	Env Var	Description
`telegram.botToken`	`TELEGRAM_BOT_TOKEN`	Bot token from BotFather
`telegram.allowedUsers`	`TELEGRAM_ALLOWED_USERS`	Allowed user IDs (empty = all)
`telegram.webhookUrl`	`TELEGRAM_WEBHOOK_URL`	Webhook URL (empty = polling)
`telegram.pollingTimeout`	`TELEGRAM_POLLING_TIMEOUT`	Polling timeout in seconds (default: 30)

Bot Commands

Command	Description
`/start`	Initialize the bot
`/help`	Show available commands
`/link`	Get a code to link your account
`/status`	Check bot status
`/clear`	Clear conversation history

Features

Text, photo, document, voice, and video messages
Reply-to message context
Automatic message chunking (4096 char limit)
Markdown formatting in responses
User whitelist via allowedUsers

Slack

Built with Bolt.js. Uses Socket Mode — no public URL required.

Setup

Go to api.slack.com/apps > Create New App > From scratch
Name your app and select your workspace
OAuth & Permissions — add Bot Token Scopes:
- chat:write, channels:history, groups:history, im:history, mpim:history
- users:read, files:read, app_mentions:read
Socket Mode — enable it, generate an App-Level Token with connections:write scope
Event Subscriptions — enable and subscribe to:
- message.channels, message.groups, message.im, message.mpim, app_mention
Install the app to your workspace
Copy the Bot Token and App Token to Settings > Channels

Configuration

Setting	Env Var	Description
`slack.botToken`	`SLACK_BOT_TOKEN`	Bot token (`xoxb-...`)
`slack.appToken`	`SLACK_APP_TOKEN`	App-level token (`xapp-...`)
`slack.signingSecret`	`SLACK_SIGNING_SECRET`	Signing secret from app settings

Features

Direct messages and @mentions
Thread-based conversations
File attachments (images, documents)
Rich message blocks with Markdown
Socket Mode (no public endpoint needed)
Account linking via link keyword

Microsoft Teams

Built with the Bot Framework. Webhook-based — requires a public URL.

Setup

Go to the Azure Portal
Create a new Bot Channels Registration resource
Note the Microsoft App ID and generate a Client Secret
Under Channels, add Microsoft Teams
Set the messaging endpoint to https://your-domain.com/api/channels/teams/webhook

Configuration

Setting	Env Var	Description
`teams.appId`	`TEAMS_APP_ID`	Microsoft App ID from Azure
`teams.appPassword`	`TEAMS_APP_PASSWORD`	Client secret
`teams.tenantId`	`TEAMS_TENANT_ID`	Azure AD tenant ID (optional)

Features

Message and conversation update handling
Bot mention removal from text
Proactive messaging via conversation references
File attachments and Adaptive Cards
Enterprise integration

Uses the Meta WhatsApp Cloud API. Webhook-based — requires a public URL.

Setup

1. Create a Meta Business App

Go to developers.facebook.com > My Apps > Create App
Select Business type, fill in the app name, select your Business Account

2. Add WhatsApp Product

In the app dashboard, click Add Product > WhatsApp > Set up
This creates a test phone number and gives you a temporary access token

3. Get Your Credentials

From WhatsApp > API Setup in the Meta developer dashboard:

Phone Number ID — listed under the test number
Access Token — click “Generate” for a temporary token
App Secret — go to Settings > Basic

4. Configure the Webhook

Your assistant must be reachable from the internet (use Cloudflare Tunnel, ngrok, etc.).

In Meta’s WhatsApp > Configuration > Webhook:
- Callback URL: https://your-domain.com/api/channels/whatsapp/webhook
- Verify Token: same value as your whatsapp.verifyToken setting
Click Verify and Save
Subscribe to the messages field

5. Production: Permanent Token

The temporary token expires after 24 hours. For production:

Meta Business Suite > Settings > System Users — create an Admin System User
Add your WhatsApp Business Account as an asset with full control
Generate a token with whatsapp_business_messaging and whatsapp_business_management permissions
Use this as your whatsapp.accessToken

Configuration

Setting	Env Var	Description
`whatsapp.accessToken`	`WHATSAPP_ACCESS_TOKEN`	Cloud API access token
`whatsapp.phoneNumberId`	`WHATSAPP_PHONE_NUMBER_ID`	Phone Number ID from Meta
`whatsapp.verifyToken`	`WHATSAPP_VERIFY_TOKEN`	Webhook verify token (default: `assistant-whatsapp-verify`)
`whatsapp.appSecret`	`WHATSAPP_APP_SECRET`	Meta App Secret for signature verification
`whatsapp.businessAccountId`	`WHATSAPP_BUSINESS_ACCOUNT_ID`	Business Account ID (optional)

Bot Commands

Command	Description
`/start`	Initialize the bot
`/help`	Show available commands
`/link`	Get a code to link your account
`/status`	Check bot status
`/clear`	Clear conversation history

Webhook Endpoints

Method	Path	Auth	Description
`GET`	`/api/channels/whatsapp/webhook`	None	Meta verification (`hub.challenge`)
`POST`	`/api/channels/whatsapp/webhook`	Signature	Incoming messages

Features

Text, image, document, audio, video, and location messages
Reply-to context (quoted messages)
Webhook signature verification (X-Hub-Signature-256)
Automatic message chunking (4096 char limit)
Media download via Graph API
Delivery status tracking (sent, delivered, read)

WebChat

The built-in WebSocket chat is always available and is the primary interface through the web UI. No configuration required.

Features

Real-time bidirectional messaging via WebSocket
Persistent sessions across page reloads
Typing indicators and agent activity tracking
Permission request/approval flow
Voice input support
Session management

Account Linking

All external channels use the same cross-channel identity binding flow:

Send /link (or link in Slack) in the channel
You receive a 6-character code valid for 5 minutes
Enter the code in the web UI at Settings > Channels

Once linked, messages from all your connected channels are attributed to the same user account. This enables:

Shared session history across channels
Unified permission settings
Consistent agent access regardless of channel

Permission Requests

When an agent needs permission (e.g., to run a shell command), the request is forwarded to the channel where the conversation originated. Reply yes or no directly in the channel to approve or deny.

Environment Variable Reference

# ─── Telegram ────────────────────────────────────────────────
TELEGRAM_BOT_TOKEN=                    # From @BotFather
TELEGRAM_ALLOWED_USERS=                # Comma-separated user IDs
TELEGRAM_WEBHOOK_URL=                  # Leave empty for polling

# ─── Slack ───────────────────────────────────────────────────
SLACK_BOT_TOKEN=                       # xoxb-...
SLACK_APP_TOKEN=                       # xapp-...
SLACK_SIGNING_SECRET=                  # From app settings

# ─── Microsoft Teams ────────────────────────────────────────
TEAMS_APP_ID=                          # Azure App ID
TEAMS_APP_PASSWORD=                    # Azure Client Secret
TEAMS_TENANT_ID=                       # Azure AD Tenant (optional)

# ─── WhatsApp ───────────────────────────────────────────────
WHATSAPP_ACCESS_TOKEN=                 # Meta Cloud API token
WHATSAPP_PHONE_NUMBER_ID=             # From Meta dashboard
WHATSAPP_VERIFY_TOKEN=                 # Your chosen verify token
WHATSAPP_APP_SECRET=                   # Meta App Secret
WHATSAPP_BUSINESS_ACCOUNT_ID=         # Business Account ID (optional)

Troubleshooting

Channel not connecting:

Check Settings > Channels in the web UI to verify credentials
Check backend logs: tail -f ~/.octipus/backend.log
Ensure secrets are stored in the vault (not as plain text in env vars)

Messages not arriving:

Telegram: Verify token at https://api.telegram.org/bot<TOKEN>/getMe
Slack: Ensure Socket Mode is enabled and the app is installed
Teams: Verify the endpoint URL is reachable from Azure
WhatsApp: Check webhook is verified (green checkmark) and subscribed to messages

Account linking fails:

Link codes expire after 5 minutes
Ensure the web account is logged in before entering the code
Verify Redis is running (codes are stored in Redis)