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.

The PraisonAI Gateway enables multi-channel agent deployment through a WebSocket server that coordinates communication between agents and various platforms.

​
Quick Start

1

Install Gateway Dependencies

Install both bot and API dependencies for gateway functionality:
pip install "praisonai[bot,api]"
The [api] extra provides uvicorn, fastapi, and starlette required by the gateway server.
2

Create Gateway Configuration

Create a gateway.yaml file:
gateway:
  host: "127.0.0.1"
  port: 8765

agents:
  assistant:
    model: gpt-4o-mini
    instructions: "You are a helpful assistant."

channels:
  telegram:
    platform: telegram
    token: ${TELEGRAM_BOT_TOKEN}
    routes:
      default: assistant
3

Start the Gateway

Launch the gateway server:
praisonai gateway start --config gateway.yaml
The gateway starts on port 8765 with WebSocket and HTTP health endpoints.

​
How It Works

ComponentRole
Gateway ServerManages WebSocket connections and routes messages
ChannelsPlatform-specific integrations (Telegram, Discord, etc.)
RouterDirects messages to appropriate agents based on rules
AgentsProcess messages and generate responses

​
Architecture Principles

​
Single Instance Rule

Critical: Only run one gateway process per machine. Multiple processes conflict:
  • Both try to bind port 8765
  • Both poll the same Telegram token (causes 409 conflicts)
  • Session state becomes inconsistent

​
Channel Isolation

Each channel operates independently:
  • Separate token per platform
  • Independent routing rules
  • Isolated session management
  • Per-channel error handling

​
Fail-Safe Design

The gateway implements fail-safe patterns:
  • Health checks at /health endpoint
  • Automatic reconnection for platform polling
  • Graceful degradation when agents are unavailable
  • Request timeout handling (25-30 seconds for RAG)

​
Gateway Modes

Run multiple platforms simultaneously:
channels:
  telegram_support:
    platform: telegram
    token: ${TELEGRAM_SUPPORT_TOKEN}
    routes:
      default: support_agent
  
  discord_community:
    platform: discord
    token: ${DISCORD_BOT_TOKEN}
    routes:
      default: community_agent
Each channel requires a unique token and can route to different agents.
Pure WebSocket server without chat platforms:
praisonai gateway start --host 127.0.0.1 --port 8765
Provides WebSocket endpoint for custom client integration.
Load agents from separate configuration:
praisonai gateway start --agents agents.yaml
Separates agent definitions from gateway configuration.

​
Health Monitoring

The gateway exposes health information: 
curl http://127.0.0.1:8765/health
Response: 
{
  "status": "healthy",
  "uptime": 3600.5,
  "agents": 3,
  "sessions": 12,
  "clients": 8,
  "channels": {
    "telegram_support": {
      "platform": "telegram",
      "running": true
    },
    "discord_community": {
      "platform": "discord", 
      "running": true
    }
  }
}

​
Health Check Limitations

Current implementation limitations:
  • "running": true doesn’t guarantee platform polling health
  • No detection of Telegram 409 conflicts until PraisonAI fix ships
  • Manual verification required for silent bot issues

​
Configuration Options

For complete configuration reference, see the auto-generated SDK documentation. The table below shows common options.
OptionTypeDefaultDescription
hoststr"127.0.0.1"Gateway bind address
portint8765Gateway port
max_connectionsint100WebSocket connection limit
heartbeat_intervalint30WebSocket ping interval
session_timeoutint3600Session expiration in seconds

​
Best Practices

Never hardcode tokens in configuration files:
# Good
channels:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}

# Bad  
channels:
  telegram:
    token: "123456:hardcoded_token"
Store tokens in .env file or environment variables.
Monitor gateway logs for platform-specific errors:
# View gateway logs
tail -f ~/.praisonai/logs/gateway.log

# Common error patterns
grep "409\|Conflict\|getUpdates" ~/.praisonai/logs/gateway.log
Set appropriate limits based on expected load:
gateway:
  max_connections: 100    # Adjust for concurrent users
  session_timeout: 3600   # 1 hour default
  message_queue_size: 1000
Each channel must have its own platform token:
channels:
  telegram_support:
    token: ${TELEGRAM_SUPPORT_TOKEN}  # Bot 1
  telegram_sales:  
    token: ${TELEGRAM_SALES_TOKEN}    # Bot 2 (different bot)
Never reuse tokens across channels.

Windows Deployment

Complete Windows setup guide

Multi-Channel Telegram

Hermes-style workforce deployment