Skip to main content
from praisonaiagents import Agent

agent = Agent(name="channel-agent", instructions="Route messages across multiple channels.")
agent.start("Handle messages from Telegram, Slack, and Discord via the gateway.")
The user messages on Telegram, Slack, or Discord; the gateway routes each channel to your agent. Connect PraisonAI agents to popular chat platforms through the channels gateway integration.

How It Works

Quick Start

1

Install Bot Dependencies

Install the bot integration package:
pip install "praisonai[bot]"
This adds support for Telegram, Discord, Slack, and WhatsApp platforms.
2

Configure Platform Tokens

Set environment variables for your chosen platforms:
# Telegram
export TELEGRAM_BOT_TOKEN="your_telegram_token"

# Discord  
export DISCORD_BOT_TOKEN="your_discord_token"

# Slack
export SLACK_BOT_TOKEN="xoxb-your-slack-token"
export SLACK_APP_TOKEN="xapp-your-slack-app-token"

# WhatsApp
export WHATSAPP_ACCESS_TOKEN="your_whatsapp_token"
export WHATSAPP_PHONE_NUMBER_ID="your_phone_number_id"
3

Launch Gateway with Channels

Start the integrated gateway with channel bot support:
praisonai dashboard --aiui
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.
Validate channel credentials before starting the gateway with praisonai gateway doctor — see Gateway CLI → Pre-flight credential check.

Platform Configuration

Telegram Setup

  1. Create bot with @BotFather
  2. Get your bot token
  3. Set environment variable:
export TELEGRAM_BOT_TOKEN="123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
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

  1. Create application in Discord Developer Portal
  2. Create bot and get token
  3. Set environment variable:
export DISCORD_BOT_TOKEN="your_discord_bot_token"

Slack Setup

  1. Create Slack app in Slack API
  2. Get Bot User OAuth Token and App-Level Token
  3. Set environment variables:
export SLACK_BOT_TOKEN="xoxb-your-bot-token"
export SLACK_APP_TOKEN="xapp-your-app-token"

WhatsApp Setup

  1. Set up WhatsApp Business API
  2. Get access token and phone number ID
  3. Set environment variables:
export WHATSAPP_ACCESS_TOKEN="your_access_token"
export WHATSAPP_PHONE_NUMBER_ID="your_phone_number_id"

Gateway Patterns

Pattern B: In-Process Host

Run channels within your application process:
from praisonai.integration import configure_host, create_host_app

configure_host(
    title="Bot Gateway",
    pages=["chat", "agents", "sessions"],
    agents=[{
        "name": "Support Agent",
        "instructions": "Help users with their questions",
        "llm": "gpt-4o"
    }]
)

app = create_host_app()
# Channels auto-start if environment variables are set

Pattern C: Integrated Gateway

Single process with WebSocket support:
import asyncio
from praisonai.integration import run_integrated_gateway

async def main():
    await run_integrated_gateway(
        port=8080,
        title="Multi-Platform Bot",
        agents=[{
            "name": "Assistant", 
            "llm": "gpt-4o"
        }]
    )

asyncio.run(main())
The gateway serves:
  • 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:
export PRAISONAI_HOST_LEGACY=1
praisonai ui
This uses only @aiui.reply callbacks without automatic agent integration.

BotOS Multi-Platform Orchestration

Use BotOS for advanced multi-platform management:
Pass reliability="production" to enable graceful drain + inbound admission control in one line. See Gateway Reliability.
from praisonai.bots import BotOS

# Initialize BotOS with all available platforms
bot_os = BotOS(reliability="production")  # or "default" / "off"

# Platforms auto-detected from environment variables
available_platforms = bot_os.get_available_platforms()
# ['telegram', 'discord'] # Based on set environment variables

# Start specific platforms
await bot_os.start_platform('telegram')
await bot_os.start_platform('discord')

# Or start all available
await bot_os.start_all()

Channel Features Integration

The praisonaiui.features.channels module provides:
FeatureDescription
Auto-detectionPlatforms start automatically when environment variables are set
Session ManagementEach user gets persistent sessions across bot restarts
Gateway IntegrationWorks seamlessly with Pattern B/C host integration
WebSocket SupportReal-time updates via /ws endpoint in Pattern C
Example with custom configuration:
from praisonaiui.features.channels import enable_channels

# Manual channel configuration
enable_channels({
    'telegram': {
        'token': os.getenv('TELEGRAM_BOT_TOKEN'),
        'agent_config': {
            'name': 'Telegram Assistant',
            'instructions': 'You are helpful on Telegram'
        }
    },
    'discord': {
        'token': os.getenv('DISCORD_BOT_TOKEN'), 
        'agent_config': {
            'name': 'Discord Bot',
            'instructions': 'You are helpful on Discord'
        }
    }
})

Channel Security

All channels enforce the same access-control pipeline regardless of whether you run them via praisonai bot start or praisonai gateway start.
FeatureStandalone BotGateway 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

WhatsApp

  • 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

# Single platform for testing
export TELEGRAM_BOT_TOKEN="your_token"
praisonai dashboard --aiui

# Check logs
tail -f ~/.praisonai/unified/logs/ui.log

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.
from praisonai.bots import TelegramBot
from praisonai.bots.delivery import ChannelDirectory
from praisonaiagents import Agent

directory = ChannelDirectory()
directory.set_home_channel("slack", "C0123456")   # default slack target
directory.add_alias("team", "slack", "C0123456")  # friendly alias
directory.add_alias("ops", "discord", "987654321")

agent = Agent(
    name="gateway",
    instructions="Help users. Deliver to team or ops channels when asked.",
)

bot = TelegramBot(
    token="your-telegram-token",
    agent=agent,
    channel_directory=directory,
)
describe_targets() compiles the list that appears in the agent prompt:
Entry TypeHow to ConfigureAppears As
Home channelset_home_channel(platform, channel_id)"<platform>:home"
Named aliasadd_alias(name, platform, channel_id)"<name> (<platform>:<channel_id>)"
Observed channelSeen in traffic or enumerated via refresh_directory()"<platform>:<channel_id>" (kind: "observed")
Call refresh_directory() on a background loop so the agent sees channels it has not yet been messaged from:
import asyncio
from praisonai.bots import BotOS, TelegramBot
from praisonaiagents import Agent

agent = Agent(name="gateway", instructions="Help users and deliver summaries when asked.")
bot = TelegramBot(token="your-telegram-token", agent=agent)
botos = BotOS(bots=[bot])

async def background_refresh(interval=300):
    while True:
        botos.delivery_router.refresh_directory()
        await asyncio.sleep(interval)

async def main():
    asyncio.create_task(background_refresh())
    await botos.start()

asyncio.run(main())

Platform-Aware Agents

Full reference for Origin, ReachableTarget, and channel-directory configuration.

Troubleshooting

Common Issues

Check environment variables are set correctly:
# Verify tokens are set
echo $TELEGRAM_BOT_TOKEN
echo $DISCORD_BOT_TOKEN

# Check bot permissions
# Telegram: Bot must be added to chat
# Discord: Bot needs appropriate server permissions
# Slack: App must be installed to workspace
Ensure gateway is running with proper agent configuration:
# Verify agent is configured
from praisonai.integration import configure_host

configure_host(
    agents=[{
        "name": "Bot Agent",  # Required
        "instructions": "You are helpful",  # Required
        "llm": "gpt-4o"  # Model must be valid
    }]
)
For Pattern C, ensure WebSocket endpoint is accessible:
# Test WebSocket connectivity
curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" \
  http://localhost:8080/ws

Best Practices

Never hardcode tokens in source code:
# Good
token = os.getenv('TELEGRAM_BOT_TOKEN')
if not token:
    raise ValueError("TELEGRAM_BOT_TOKEN not set")

# Bad
token = "123456:hardcoded_token"  # Security risk
Different platforms have different rate limits:
# Built-in rate limiting
from praisonai.bots import BotOS

bot_os = BotOS(rate_limit_config={
    'telegram': {'requests_per_second': 30},
    'discord': {'requests_per_minute': 50},
    'slack': {'requests_per_minute': 100}
})
Set up monitoring for production deployments:
# Health check endpoint
@app.get("/health")
async def health_check():
    bot_status = await bot_os.get_platform_status()
    return {"status": "healthy", "bots": bot_status}

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