> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Gateway Overview

> WebSocket gateway for multi-channel agent coordination and communication

<Note>
  The gateway now ships in the `praisonai-bot` package. `praisonai serve gateway` still works exactly as documented here; for a standalone install see [praisonai-bot Migration](/docs/guides/praisonai-bot-migration).
</Note>

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(name="gateway-agent", instructions="Route messages through the PraisonAI gateway.")
agent.start("Set up the gateway to handle Telegram and Slack messages.")
```

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

The user starts the gateway and sends a message on a channel; the gateway routes it to the right agent and returns the reply.

```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                                                                                                           |
| **Inbound Triggers** | `POST /hooks/<path>` — start agent runs from external HTTP events (webhooks, CI, IoT). See [Inbound Hooks](/docs/features/gateway-inbound-hooks). |

***

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

### Live Config Reload

The gateway diffs `gateway.yaml` against the running config and restarts only affected agents or channels. Invalid YAML saves keep the last-known-good config. The WebSocket server is never restarted. See [Gateway Hot-Reload](/docs/features/gateway-hot-reload).

### 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)
* Versioned `hello` handshake with capability negotiation — see [Handshake Protocol](/docs/features/gateway-handshake-protocol)
* Shutdown forensics — on every exit, one log line and one diagnostic file record *why* the gateway stopped. See [Crash Forensics](/docs/features/gateway-forensics).

***

## 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            |
| `session.persist`       | `bool` | `false`                  | Persist sessions across restarts         |
| `session.persist_path`  | `str`  | `~/.praisonai/sessions/` | Storage directory                        |
| `session.resume_window` | `int`  | `86400`                  | Seconds detached sessions stay resumable |

***

## Best Practices

<AccordionGroup>
  <Accordion title="Edit gateway.yaml live">
    You can change agent instructions, models, or a single channel section while the gateway runs. Agent-only edits recreate agents without restarting channels. See [Hot-Reload](/docs/features/gateway-hot-reload).
  </Accordion>

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

***

## Cost Optimization

Running a PraisonAI gateway on serverless hosts (Fly.io Machines, Modal, Cloud Run) charges for every second the machine is alive — even when no users are chatting. The **Scale-to-Zero** feature lets the gateway stand transports down after a configurable period of silence and wake back up on the next inbound message, so you pay only for active time.

<Card title="Scale-to-Zero Gateway" icon="moon" href="/docs/features/gateway-scale-to-zero">
  Suspend the gateway when idle and wake on the next message — pay only for active time.
</Card>

***

## Related

<CardGroup cols={2}>
  <Card title="Admission Control" icon="shield-check" href="/docs/features/gateway-admission-control">
    Bound concurrent inbound agent runs with a fair queue and overflow policy
  </Card>

  <Card title="Session Persistence" icon="database" href="/docs/features/gateway-session-persistence">
    Survive restarts and resume mid-conversation
  </Card>

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

  <Card title="Scale to Zero" icon="moon" href="/docs/features/gateway-scale-to-zero">
    Pay only for active time — idle-dormancy for serverless hosts
  </Card>

  <Card title="Tracing Hook" icon="route" href="/docs/features/gateway-tracing-hook">
    Emit OpenTelemetry spans across each pipeline stage
  </Card>
</CardGroup>