How It Works
Channels bound to a
recipe: in their capabilities stream progressively just like Python Agent targets — the same DraftStreamer / SSE pipeline is used. See Bot Streaming Replies.Quick Start
1
Install Bot Dependencies
Install the bot integration package:This adds support for Telegram, Discord, Slack, and WhatsApp platforms.
2
Configure Platform Tokens
Set environment variables for your chosen platforms:
3
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:
Signal Setup
Signal links a device through a local signal-cli-rest-api bridge — no cloud token.- Run the bridge (
docker run -p 8080:8080 bbernhard/signal-cli-rest-api) - Link a device by scanning the bridge QR from Signal → Linked Devices
- Set environment variables:
No token needed — Signal links a device via the local bridge. See Signal Bot for the full setup.
Local (Terminal) Setup
The built-inlocal channel reads stdin and writes stdout — no token, no webhook, no allowlist. Add it alongside remote channels to chat with the same live agent from your terminal.
Local (Terminal) Channel
Chat from your terminal, commands, capabilities, and cross-channel continuity
Webhook Setup
Route any third-party HTTP webhook (GitHub, Stripe, CI) to an agent with atype: webhook channel and declarative routes — no adapter code.
Add a custom channel
Point a channel at your own adapter class from YAML — no packaging, no bootstrap Python.~/.praisonai/channels/*.py. See Custom Gateway Channel (Zero-Code) for both surfaces, the precedence ladder, and the trust model.
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:
Example with custom configuration:
Channel Security
All channels enforce the same access-control pipeline regardless of whether you run them viapraisonai bot start or praisonai gateway start.
Gateway channels also accept
group:<name> references in allowed_users, allowlist and blocklist — see Access Groups.
Gateway YAML Reference
Complete YAML field documentation and pipeline diagram
BotConfig Reference
Standalone bot configuration options
Shell execution opt-in
Setallow_shell: true on a channel to let its bot run shell commands on the gateway host. Policy is per-channel — Slack can auto-approve while WhatsApp requires approval.
auto_approve_shell: true only stays blanket auto-approve on a loopback-bound gateway + single-operator DM. On a 0.0.0.0 bind — or any channel with a group_policy — the gateway silently downgrades it to “require approval” unless you add auto_approve_shell_acknowledge_exposed: true.Bot Shell Execution
Full field reference, per-platform approval routing, exposure-aware downgrade, and copy-paste recipes.
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
Signal
- End-to-end encryption via linked-device bridge
- DMs + groups with digit-normalised allowlist
- Typing indicators (best-effort)
- Poll-based (no webhooks); text-only in this release
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:
ChannelDirectory covers outbound delivery (which channel an agent sends to). For inbound routing — dispatching an incoming WhatsApp/SMS number to a specific agent — use the Agent Registry.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
Bot Streaming Replies
Progressive streaming for Python-
Agent and recipe/YAML-backed channels
