Channels Gateway

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

Connect PraisonAI agents to popular chat platforms through the channels gateway integration.

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.

---

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"

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

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:

from praisonai.bots import BotOS

# Initialize BotOS with all available platforms
bot_os = BotOS()

# 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

---

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

---

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

---

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