Channels Gateway

Connect agents to chat platforms like Telegram, Discord, Slack, and WhatsApp

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:

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

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.

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

---

Shell execution opt-in

Set allow_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.

channels:
  slack:
    token: "${SLACK_BOT_TOKEN}"
    app_token: "${SLACK_APP_TOKEN}"
    allow_shell: true
    auto_approve_shell: false
    approval_channel: "UOWNER"

Bot Shell Execution

Full field reference, per-platform approval routing, 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

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

Development

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

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

Production

import os
import asyncio
from praisonai.integration import run_integrated_gateway

async def main():
    await run_integrated_gateway(
        port=int(os.getenv("PORT", "8080")),
        host="0.0.0.0",
        title="Production Bot Gateway",
        agents=[{
            "name": "Support Bot",
            "llm": os.getenv("PRAISONAI_MODEL", "gpt-4o"),
            "instructions": "Professional customer support assistant"
        }],
        ui_config={
            "analytics": os.getenv("ANALYTICS_ID"),
            "error_reporting": True
        }
    )

if __name__ == "__main__":
    asyncio.run(main())

---

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 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")

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.

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

Bot not starting

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

Messages not reaching agents

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
    }]
)

WebSocket connection issues

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

Use environment variables for tokens

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

Handle rate limits gracefully

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}
})

Monitor bot health

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}

---

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