How It Works
Quick Start
Install Bot Dependencies
Install the bot integration package:This adds support for Telegram, Discord, Slack, and WhatsApp platforms.
Launch Gateway with Channels
Start the integrated gateway with channel bot support:This starts Pattern B host integration with channels feature enabled.
All configured channels now start reliably from a single gateway, resolving the previous
cannot pickle '_thread.RLock' object error through automatic Agent Cloning.Platform Configuration
Telegram Setup
- Create bot with @BotFather
- Get your bot token
- Set environment variable:
Telegram bots now support live streaming replies that update in real-time as your agent thinks. See Bot Streaming Replies for configuration options.
Discord Setup
- Create application in Discord Developer Portal
- Create bot and get token
- Set environment variable:
Slack Setup
- Create Slack app in Slack API
- Get Bot User OAuth Token and App-Level Token
- Set environment variables:
WhatsApp Setup
- Set up WhatsApp Business API
- Get access token and phone number ID
- Set environment variables:
Gateway Patterns
Pattern B: In-Process Host
Run channels within your application process:Pattern C: Integrated Gateway
Single process with WebSocket support:- Chat UI at
http://localhost:8080 - REST API at
http://localhost:8080/api - WebSocket at
ws://localhost:8080/ws - Bot integrations auto-start based on environment variables
WebSocket gateway YAML may include a
gateway.rate_limit: block (max_requests, window_seconds, lockout_seconds). See Gateway Rate Limit Policy and Gateway Handshake Protocol for how denials surface as rate_limited during connect.Legacy Mode
For callback-only integration without provider wiring:@aiui.reply callbacks without automatic agent integration.
BotOS Multi-Platform Orchestration
UseBotOS for advanced multi-platform management:
Channel Features Integration
Thepraisonaiui.features.channels module provides:
| Feature | Description |
|---|---|
| Auto-detection | Platforms start automatically when environment variables are set |
| Session Management | Each user gets persistent sessions across bot restarts |
| Gateway Integration | Works seamlessly with Pattern B/C host integration |
| WebSocket Support | Real-time updates via /ws endpoint in Pattern C |
Channel Security
All channels enforce the same access-control pipeline regardless of whether you run them viapraisonai bot start or praisonai gateway start.
| Feature | Standalone Bot | Gateway Mode |
|---|---|---|
User allowlist (allowed_users) | ✅ | ✅ |
Channel allowlist (allowed_channels) | ✅ | ✅ |
| Unknown user pairing | ✅ | ✅ |
| Group policy enforcement | ✅ | ✅ |
Gateway YAML Reference
Complete YAML field documentation and pipeline diagram
BotConfig Reference
Standalone bot configuration options
Platform-Specific Features
Telegram
- Supports markdown formatting
- File uploads and downloads
- Inline keyboards
- Command handling (
/start,/help)
Discord
- Rich embeds and attachments
- Slash commands
- Thread support
- Role-based permissions
Slack
- Block kit UI components
- App Home tab
- Workflow integration
- Enterprise security features
- Media message support
- Template messages
- Business API features
- Webhook verification
Outbound Media Delivery
Send agent-generated images and files through channel adapters with path validation
Bot Inbound Media
Receive and validate photos and documents from users
Development vs Production
- Development
- Production
Reachable Targets
Give the agent a named directory of channels it can deliver to. When a message arrives, the agent’s system prompt lists which channels are reachable by friendly name.describe_targets() compiles the list that appears in the agent prompt:
| Entry Type | How to Configure | Appears As |
|---|---|---|
| Home channel | set_home_channel(platform, channel_id) | "<platform>:home" |
| Named alias | add_alias(name, platform, channel_id) | "<name> (<platform>:<channel_id>)" |
| Observed channel | Seen in traffic or enumerated via refresh_directory() | "<platform>:<channel_id>" (kind: "observed") |
refresh_directory() on a background loop so the agent sees channels it has not yet been messaged from:
Platform-Aware Agents
Full reference for Origin, ReachableTarget, and channel-directory configuration.
Troubleshooting
Common Issues
Bot not starting
Bot not starting
Check environment variables are set correctly:
Messages not reaching agents
Messages not reaching agents
Ensure gateway is running with proper agent configuration:
WebSocket connection issues
WebSocket connection issues
For Pattern C, ensure WebSocket endpoint is accessible:
Best Practices
Use environment variables for tokens
Use environment variables for tokens
Never hardcode tokens in source code:
Handle rate limits gracefully
Handle rate limits gracefully
Different platforms have different rate limits:
Monitor bot health
Monitor bot health
Set up monitoring for production deployments:
Related
Host Integration
Pattern B/C integration
Integration Patterns
Pattern comparison
Outbound Media Delivery
Deliver agent-generated media via gateway channel adapters
Messaging Bots
Full bot setup for Telegram, Discord, Slack, and WhatsApp

