Bot Gateway - PraisonAI

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. Each channel bot gets an isolated agent via Agent.clone_for_channel() — fresh locks, fresh interrupt controller, and no shared handoffs state — so configuring tools or memory on one channel never leaks into another.

Quick Start

Install PraisonAI

pip install praisonai

Create gateway.yaml

Create a gateway.yaml file in your project (Gateway YAML files are read as UTF-8 — non-ASCII characters work on all platforms including Windows):

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}
    streaming:
      mode: draft       # off | draft | progress — see /features/bot-streaming-replies
    routes:
      dm: personal
      group: support
      default: personal
  discord:
    token: ${DISCORD_BOT_TOKEN}
    routes:
      default: personal

Set Environment Variables

export TELEGRAM_BOT_TOKEN=your_telegram_token
export DISCORD_BOT_TOKEN=your_discord_token
export OPENAI_API_KEY=your_openai_key

Start the Gateway

praisonai gateway start --config gateway.yaml

All bots start together. Messages are routed to the correct agent automatically.

Supported Channels

Full support for DMs, groups, commands, voice, and media.

Discord

Guild channels, DMs, slash commands, and embeds.

Slack

Socket Mode, channels, DMs, slash commands, and threads.

Cloud API and Web mode. DMs, groups, media support.

Windows users: Gateway Telegram error replies are automatically sanitized to ASCII-safe text — non-ASCII exception content (warning symbols, emoji, accented characters) no longer crashes the error handler with a charmap codec error. Real underlying errors (quota, rate limit, auth) surface cleanly.

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:

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:

channels:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}    # Environment variable
    routes:
      dm: personal                   # DMs → personal agent
      group: support                 # Groups → support agent
      default: personal              # Fallback agent

Use ${ENV_VAR_NAME} syntax in token fields. The gateway automatically reads from your environment variables.

Channel Security

Each channel enforces the same access-control pipeline as standalone bots.

YAML Key	Type	Default	Purpose
`token`	`str`	required*	Bot auth token. *Optional for `whatsapp` web mode and `email`/`agentmail`.
`platform`	`str`	channel name	Override channel platform (e.g. `telegram`).
`routing` / `routes`	`dict`	`{"default": "default"}`	Route map: `dm`, `group`, `default` → agent id.
`allowed_users`	`list[str]` \| `str`	`[]`	User-ID allowlist. Comma-separated string also accepted (env-expansion friendly).
`allowed_channels`	`list[str]` \| `str`	`[]`	Channel/group-ID allowlist. Same string handling.
`group_policy`	`str`	`"mention_only"`	One of `"mention_only"`, `"command_only"`, `"respond_all"`. Sets `mention_required` automatically.
`auto_approve_tools`	`bool` \| `str`	`True`	Auto-approve safe tools. Strings `"1"/"true"/"yes"/"on"` are truthy.
`default_tools`	`list[str]`	(BotConfig default)	Per-channel override for default safe tools.

channels:
  telegram_support:
    token: ${TELEGRAM_BOT_TOKEN}
    allowed_users:                # User-ID allowlist (empty list → unknown_user_policy decides)
      - "123456789"
      - "987654321"
    allowed_channels:             # Group/channel allowlist (empty = anywhere)
      - "-1001234567890"
    group_policy: "mention_only"  # mention_only | command_only | respond_all
    auto_approve_tools: true      # Auto-approve safe tools (default true)
    routes:
      dm: personal
      group: support
      default: personal

allowed_users interacts with unknown_user_policy. With an empty allowed_users list, every Telegram user is treated as “unknown” and the unknown_user_policy decides their fate:

"deny" (default) — all messages silently dropped (recommended for production).
"pair" — unknown users go through the owner-approval pairing flow.
"allow" — every user is let through (only set this in trusted networks).

Earlier releases incorrectly treated empty allowed_users as “allow everyone” on Telegram, bypassing the policy entirely. Fixed in PR #1885. Discord and Slack were already correct.

As of PR #1791, gateway-mode bots enforce the same security pipeline as standalone bots (praisonai bot start). Previous versions silently bypassed allowed_users, pairing, and group_policy in gateway mode.

Pair with unknown_user_policy: "deny" for the most secure default. To intentionally allow everyone (e.g. internal staging), leave allowed_users empty and set unknown_user_policy: "allow" — both are required.

CLI Commands

praisonai gateway start --config gateway.yaml

Python Usage

From YAML
Programmatic
Inspect Bots

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

from_config_file() automatically resolves ${ENV_VAR} syntax in your YAML, creates agents with tools, and configures channel bots.

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

# 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

Advanced: Health Endpoint

The gateway exposes a health endpoint at http://host:port/health:

curl http://127.0.0.1:8765/health

Returns:

{
  "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.

Advanced: Channel isolation

The gateway calls _create_bot() to build independent clones for each channel:Each clone has fresh locks and interrupt controllers, preventing cross-channel interference. Learn more about Agent Cloning.

Advanced: Standalone Bot Mode

You can still run a single bot without the gateway:

praisonai bot telegram --token $TELEGRAM_BOT_TOKEN

This starts just one bot connected to a single agent — no gateway needed.

Never commit bot tokens to version control. Always use environment variables or a .env file.

​Quick Start

​Supported Channels

Telegram

Discord

Slack

WhatsApp

​Configuration Reference

​Gateway Section

​Agents Section

​Channels Section

​Channel Security

​CLI Commands

​Python Usage

Quick Start

Supported Channels

Configuration Reference

Gateway Section

Agents Section

Channels Section

Channel Security

CLI Commands

Python Usage