> ## 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.

# Gateway Overview

> WebSocket gateway for multi-channel agent coordination and communication

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

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Gateway Architecture"
        subgraph "Users"
            U1[👤 Telegram User]
            U2[👤 Discord User]
            U3[👤 WhatsApp User]
        end
        
        subgraph "Gateway Server - Port 8765"
            WS[🌐 WebSocket Server]
            CH1[📱 Telegram Channel]
            CH2[💬 Discord Channel]
            CH3[📞 WhatsApp Channel]
            RT[🔀 Router]
        end
        
        subgraph "Agents"
            A1[🤖 Support Agent]
            A2[🤖 Sales Agent]
            A3[🤖 Technical Agent]
        end
        
        U1 --> CH1
        U2 --> CH2
        U3 --> CH3
        
        CH1 --> RT
        CH2 --> RT
        CH3 --> RT
        
        RT --> A1
        RT --> A2
        RT --> A3
    end
    
    classDef user fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef gateway fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef agent fill:#10B981,stroke:#7C90A0,color:#fff
    
    class U1,U2,U3 user
    class WS,CH1,CH2,CH3,RT gateway
    class A1,A2,A3 agent
```

## Quick Start

<Steps>
  <Step title="Install Gateway Dependencies">
    Install both bot and API dependencies for gateway functionality:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    pip install "praisonai[bot,api]"
    ```

    The `[api]` extra provides uvicorn, fastapi, and starlette required by the gateway server.
  </Step>

  <Step title="Create Gateway Configuration">
    Create a `gateway.yaml` file:

    ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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
    ```
  </Step>

  <Step title="Start the Gateway">
    Launch the gateway server:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai gateway start --config gateway.yaml
    ```

    The gateway starts on port 8765 with WebSocket and HTTP health endpoints.
  </Step>
</Steps>

***

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Platform as Platform (Telegram/Discord)
    participant Gateway
    participant Agent
    participant LLM
    
    User->>Platform: Send message
    Platform->>Gateway: Forward via polling/webhook
    Gateway->>Agent: Route to configured agent
    Agent->>LLM: Process with context
    LLM-->>Agent: Return response
    Agent-->>Gateway: Send reply
    Gateway-->>Platform: Forward response
    Platform-->>User: Display message
```

| Component          | Role                                                     |
| ------------------ | -------------------------------------------------------- |
| **Gateway Server** | Manages WebSocket connections and routes messages        |
| **Channels**       | Platform-specific integrations (Telegram, Discord, etc.) |
| **Router**         | Directs messages to appropriate agents based on rules    |
| **Agents**         | Process 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

<AccordionGroup>
  <Accordion title="Multi-Channel Mode">
    Run multiple platforms simultaneously:

    ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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.
  </Accordion>

  <Accordion title="WebSocket-Only Mode">
    Pure WebSocket server without chat platforms:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai gateway start --host 127.0.0.1 --port 8765
    ```

    Provides WebSocket endpoint for custom client integration.
  </Accordion>

  <Accordion title="Agent File Mode">
    Load agents from separate configuration:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai gateway start --agents agents.yaml
    ```

    Separates agent definitions from gateway configuration.
  </Accordion>
</AccordionGroup>

***

## Health Monitoring

The gateway exposes health information:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
curl http://127.0.0.1:8765/health
```

**Response:**

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "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

<Note>
  For complete configuration reference, see the auto-generated SDK documentation. The table below shows common options.
</Note>

| Option               | Type  | Default       | Description                   |
| -------------------- | ----- | ------------- | ----------------------------- |
| `host`               | `str` | `"127.0.0.1"` | Gateway bind address          |
| `port`               | `int` | `8765`        | Gateway port                  |
| `max_connections`    | `int` | `100`         | WebSocket connection limit    |
| `heartbeat_interval` | `int` | `30`          | WebSocket ping interval       |
| `session_timeout`    | `int` | `3600`        | Session expiration in seconds |

***

## Best Practices

<AccordionGroup>
  <Accordion title="Use environment variables for secrets">
    Never hardcode tokens in configuration files:

    ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Good
    channels:
      telegram:
        token: ${TELEGRAM_BOT_TOKEN}

    # Bad  
    channels:
      telegram:
        token: "123456:hardcoded_token"
    ```

    Store tokens in `.env` file or environment variables.
  </Accordion>

  <Accordion title="Implement proper error handling">
    Monitor gateway logs for platform-specific errors:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # View gateway logs
    tail -f ~/.praisonai/logs/gateway.log

    # Common error patterns
    grep "409\|Conflict\|getUpdates" ~/.praisonai/logs/gateway.log
    ```
  </Accordion>

  <Accordion title="Configure resource limits">
    Set appropriate limits based on expected load:

    ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    gateway:
      max_connections: 100    # Adjust for concurrent users
      session_timeout: 3600   # 1 hour default
      message_queue_size: 1000
    ```
  </Accordion>

  <Accordion title="Use unique tokens per channel">
    Each channel must have its own platform token:

    ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    channels:
      telegram_support:
        token: ${TELEGRAM_SUPPORT_TOKEN}  # Bot 1
      telegram_sales:  
        token: ${TELEGRAM_SALES_TOKEN}    # Bot 2 (different bot)
    ```

    Never reuse tokens across channels.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Windows Deployment" icon="windows" href="/docs/features/gateway-windows-deployment">
    Complete Windows setup guide
  </Card>

  <Card title="Multi-Channel Telegram" icon="paper-plane" href="/docs/features/gateway-telegram-multichannel">
    Hermes-style workforce deployment
  </Card>
</CardGroup>