Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.praison.ai/llms.txt

Use this file to discover all available pages before exploring further.

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.

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

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

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

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

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