Notifications

AI OS delivers notifications through three channels: real-time WebSocket messages in the dashboard, Telegram Bot API, and Slack Incoming Webhooks. All channels are optional and independently configurable.

WebSocket (Dashboard)

The primary notification channel. All connected dashboard clients receive real-time updates via WebSocket:

• Agent status — Started, processing, completed, or failed
• Batch progress — Per-item status updates and completion counts
• System alerts — Memory warnings, rate limit hits, server shutdown notices
• Pipeline updates — Step-by-step progress through multi-stage pipelines

Connection Management

• Heartbeat: Server pings every 30 seconds; clients that miss 2 pings are disconnected
• Auto-reconnect: Client uses exponential backoff (1s, 2s, 4s, ... up to 30s max)
• Reconnect banner: Visual indicator appears when connection drops
• Graceful shutdown: Server sends server_shutdown event before stopping

Telegram

Send notifications to a Telegram chat via the Bot API. Useful for mobile alerts when you're away from the dashboard.

Setup

1. Create a bot via @BotFather on Telegram
2. Copy the bot token to TELEGRAM_BOT_TOKEN in .env
3. Start a chat with your bot and send any message
4. Get your chat ID and set it as TELEGRAM_CHAT_ID

Environment Variables

Variable	Description
TELEGRAM_BOT_TOKEN	Bot token from @BotFather
TELEGRAM_CHAT_ID	Target chat/group ID for messages

The server calls the Telegram Bot API directly via HTTP POST to api.telegram.org. Messages are sent as HTML-formatted text with agent name, status, and summary.

Slack

Send notifications to a Slack channel via Incoming Webhooks.

Setup

1. Go to your Slack workspace settings → Apps → Incoming Webhooks
2. Create a new webhook and select the target channel
3. Copy the webhook URL to SLACK_WEBHOOK_URL in .env

Environment Variable

Variable	Description
SLACK_WEBHOOK_URL	Full webhook URL from Slack app settings

Notifications are sent as Slack Block Kit messages with structured formatting including title, description, and status indicators.

Notification Events

The following events trigger notifications across all configured channels:

Event	WebSocket	Telegram	Slack
Agent completed	Always	If configured	If configured
Agent failed	Always	If configured	If configured
Batch completed	Always	If configured	If configured
Pipeline finished	Always	If configured	If configured
Rate limit hit	Always	No	No
Server shutdown	Always	If configured	If configured