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

# Bot Gateway

> Run multiple bots (Telegram, Discord, Slack) from a single gateway server with multi-agent routing.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
flowchart LR
    Config[gateway.yaml] --> Gateway[Gateway Server]
    Gateway --> TG[Telegram Bot]
    Gateway --> DC[Discord Bot]
    Gateway --> SL[Slack Bot]
    TG --> AgentA[Agent A]
    DC --> AgentA
    SL --> AgentB[Agent B]
    
    style Config fill:#8B0000,color:#fff
    style Gateway fill:#189AB4,color:#fff
    style TG fill:#189AB4,color:#fff
    style DC fill:#189AB4,color:#fff
    style SL fill:#189AB4,color:#fff
    style AgentA fill:#8B0000,color:#fff
    style AgentB fill:#8B0000,color:#fff
```

Run all your bots from one command. The Gateway Server manages multiple bot connections and routes messages to the right AI agent.

**Parity with Bot()**: `praisonai gateway start` now applies the same smart defaults as `praisonai bot start`, resolving the previous "zero tools in daemon mode" issue. Both entry points produce identical behavior with safe tools auto-injected and auto-approval enabled by default.

## Quick Start

<Steps>
  <Step title="Install PraisonAI">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    pip install praisonai
    ```
  </Step>

  <Step title="Create gateway.yaml">
    Create a `gateway.yaml` file in your project:

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

    agents:
      personal:
        instructions: "You are a helpful personal assistant"
        model: gpt-4o-mini
        tools:
          - internet_search
          - get_current_time
        reflection: true
      support:
        instructions: "You are a customer support agent"
        model: gpt-4o
        role: "Customer Support Specialist"
        goal: "Resolve customer issues quickly and accurately"
        backstory: "Expert in troubleshooting and customer care"
        tools:
          - internet_search
        tool_choice: auto
        allow_delegation: false

    channels:
      telegram:
        token: ${TELEGRAM_BOT_TOKEN}
        routes:
          dm: personal
          group: support
          default: personal
      discord:
        token: ${DISCORD_BOT_TOKEN}
        routes:
          default: personal
    ```
  </Step>

  <Step title="Set Environment Variables">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    export TELEGRAM_BOT_TOKEN=your_telegram_token
    export DISCORD_BOT_TOKEN=your_discord_token
    export OPENAI_API_KEY=your_openai_key
    ```
  </Step>

  <Step title="Start the Gateway">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai gateway start --config gateway.yaml
    ```

    All bots start together. Messages are routed to the correct agent automatically.
  </Step>
</Steps>

## Supported Channels

<CardGroup cols={2}>
  <Card title="Telegram" icon="paper-plane">
    Full support for DMs, groups, commands, voice, and media.
  </Card>

  <Card title="Discord" icon="discord">
    Guild channels, DMs, slash commands, and embeds.
  </Card>

  <Card title="Slack" icon="slack">
    Socket Mode, channels, DMs, slash commands, and threads.
  </Card>

  <Card title="WhatsApp" icon="whatsapp">
    Cloud API and Web mode. DMs, groups, media support.
  </Card>
</CardGroup>

## Configuration Reference

### Gateway Section

| Field    | Type    | Default     | Description                        |
| -------- | ------- | ----------- | ---------------------------------- |
| **host** | string  | `127.0.0.1` | Address to bind the gateway server |
| **port** | integer | `8765`      | Port for the WebSocket server      |

### Agents Section

Each agent is defined by a unique ID and its configuration:

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agents:
  my_agent_id:
    instructions: "Your system prompt here"
    model: gpt-4o-mini
    memory: true
    tools:
      - internet_search
      - get_current_time
    reflection: true
    role: "Research Analyst"
    goal: "Find accurate information"
    backstory: "Expert researcher"
    tool_choice: auto
    allow_delegation: false
```

| Field                 | Type    | Default | Description                               |
| --------------------- | ------- | ------- | ----------------------------------------- |
| **instructions**      | string  | `""`    | System prompt for the agent               |
| **model**             | string  | `None`  | LLM model (e.g., `gpt-4o-mini`, `gpt-4o`) |
| **memory**            | boolean | `false` | Enable conversation memory                |
| **tools**             | list    | `[]`    | Tool names resolved via ToolResolver      |
| **reflection**        | boolean | `true`  | Enable self-reflection / interactive mode |
| **role**              | string  | `None`  | Agent role (CrewAI-style)                 |
| **goal**              | string  | `None`  | Agent goal (CrewAI-style)                 |
| **backstory**         | string  | `None`  | Agent backstory (CrewAI-style)            |
| **tool\_choice**      | string  | `None`  | `auto`, `required`, or `none`             |
| **allow\_delegation** | boolean | `false` | Allow task delegation to other agents     |

### Channels Section

Each channel maps to a bot platform:

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
channels:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}    # Environment variable
    routes:
      dm: personal                   # DMs → personal agent
      group: support                 # Groups → support agent
      default: personal              # Fallback agent
```

<Tip>
  Use `${ENV_VAR_NAME}` syntax in token fields. The gateway automatically reads from your environment variables.
</Tip>

## CLI Commands

<CodeGroup>
  ```bash Start Gateway theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  praisonai gateway start --config gateway.yaml
  ```

  ```bash Start with Custom Host/Port theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  praisonai gateway start --config gateway.yaml --host 0.0.0.0 --port 9000
  ```

  ```bash Check Gateway Status theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  praisonai gateway status
  ```
</CodeGroup>

## Python Usage

<Tabs>
  <Tab title="From YAML">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonai.gateway import WebSocketGateway

    # Load gateway config, agents, and channels from YAML
    gateway = WebSocketGateway.from_config_file("gateway.yaml")

    import asyncio
    asyncio.run(gateway.start())
    ```

    <Tip>
      `from_config_file()` automatically resolves `${ENV_VAR}` syntax in your YAML, creates agents with tools, and configures channel bots.
    </Tip>
  </Tab>

  <Tab title="Programmatic">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    import asyncio
    from praisonai.gateway import WebSocketGateway
    from praisonaiagents import Agent
    from praisonaiagents.gateway import GatewayConfig

    # Create agents
    personal = Agent(name="personal", instructions="You are a helpful assistant")
    support = Agent(name="support", instructions="You are a support agent")

    # Create gateway
    config = GatewayConfig(host="127.0.0.1", port=8765)
    gateway = WebSocketGateway(config=config)

    # Register agents (use overwrite=False to prevent accidental replacement)
    gateway.register_agent(personal, agent_id="personal")
    gateway.register_agent(support, agent_id="support", overwrite=False)

    # Start gateway
    asyncio.run(gateway.start())
    ```
  </Tab>

  <Tab title="Inspect Bots">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # After starting the gateway, inspect connected channel bots
    gateway.list_channel_bots()      # ['telegram', 'discord']
    gateway.get_channel_bot("telegram")  # Returns bot instance
    gateway.has_channel_bot("slack")     # False

    # Inspect registered agents
    gateway.list_agents()            # ['personal', 'support']
    gateway.get_agent("personal")    # Returns Agent instance
    ```
  </Tab>
</Tabs>

<Accordion title="Advanced: Health Endpoint">
  The gateway exposes a health endpoint at `http://host:port/health`:

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

  Returns:

  ```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  {
    "status": "healthy",
    "uptime": 120.5,
    "agents": 2,
    "sessions": 3,
    "clients": 1,
    "channels": {
      "telegram": {
        "platform": "telegram",
        "running": true
      },
      "discord": {
        "platform": "discord", 
        "running": false
      }
    },
    "push": {
      "enabled": true,
      "push_channels": 2,
      "online_clients": 5,
      "redis_connected": true
    }
  }
  ```

  The `push` section is only included when push notifications are enabled.
</Accordion>

<Accordion title="Advanced: Standalone Bot Mode">
  You can still run a single bot without the gateway:

  ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  praisonai bot telegram --token $TELEGRAM_BOT_TOKEN
  ```

  This starts just one bot connected to a single agent — no gateway needed.
</Accordion>

<Warning>
  Never commit bot tokens to version control. Always use environment variables or a `.env` file.
</Warning>