Bot Gateway

Bot platform adapters now ship in the praisonai-bot package. praisonai bot serve still works exactly as documented here; for a standalone install see praisonai-bot Migration.

from praisonaiagents import Agent

agent = Agent(name="gateway-bot", instructions="Handle messages from Telegram, Slack, and Discord.")
agent.start("Set up the bot gateway for all chat platforms.")

The user messages on Telegram, Slack, or Discord; the gateway routes each channel to the right agent. 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}
    allowed_users: []                        # or a list of allowed user IDs
    unknown_user_policy: deny                # deny (default, secure) | pair | allow
    owner_user_id: ${TELEGRAM_OWNER_ID}      # required if unknown_user_policy: pair
    streaming:
      mode: draft       # off | draft | progress — see /features/bot-streaming-replies
    routes:
      dm: personal
      group: support
      default: personal
  discord:
    token: ${DISCORD_BOT_TOKEN}
    allowed_users: []
    unknown_user_policy: deny
    owner_user_id: ${DISCORD_OWNER_ID}
    routes:
      default: personal

Set Environment Variables

export TELEGRAM_BOT_TOKEN=your_telegram_token
export DISCORD_BOT_TOKEN=your_discord_token
export OPENAI_API_KEY="${OPENAI_API_KEY:?Set OPENAI_API_KEY in your shell}"

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
    unknown_user_policy: deny        # deny (default) | pair | allow
    owner_user_id: ${TELEGRAM_OWNER_ID}  # required if unknown_user_policy: pair
    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. Every key below is read per-channel from gateway.yaml — including unknown_user_policy and owner_user_id, which the gateway now wires through at start and on hot-reload (PR #2856).

# Same effect from Python — for consumers building custom adapters
from praisonaiagents.bots import BotConfig

config = BotConfig(
    token="...",
    allowed_users=["telegram:123456"],
    unknown_user_policy="pair",     # deny | pair | allow
    owner_user_id="telegram:987654",
)

# is_explicitly_allowed skips the pairing flow for whitelisted users
config.is_explicitly_allowed("telegram:123456")  # True
config.is_explicitly_allowed("telegram:99999")   # False → policy decides

The same configuration comes straight from gateway.yaml:

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.
`unknown_user_policy`	`"deny" \| "pair" \| "allow"`	`"deny"`	What to do with users not in `allowed_users`. `deny` silently drops. `pair` runs the owner-approval flow (`owner_user_id` required). `allow` lets everyone through (trusted networks only).
`owner_user_id`	`str`	`null`	Platform user ID of the channel owner. Required when `unknown_user_policy: "pair"` — the owner receives approval prompts for new users.
`group_policy`	`str`	`"mention_only"`	One of `"mention_only"`, `"command_only"`, `"respond_all"`, `"observe"`. Sets `mention_required` automatically. `observe` records unmentioned group messages as passive context instead of dropping them (Telegram only).
`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.

`observe`: passive group context

observe records unmentioned group messages as passive context so the bot can answer with full conversational awareness when it’s finally mentioned. With mention_only (the default), messages that don’t @mention the bot are dropped and leave no session record. With observe, those messages are appended to the session transcript as ordinary user turns — the bot still does not answer them, but the next time it is addressed (e.g. @bot summarise what we just decided) the preceding conversation is in its history. Pair observe with session_scope: per_chat so passive messages route to the shared per-chat key that a later addressed turn reads from. Under the default per_user scope, passive turns are retained only in that sender’s own history — they do not leak into any single user’s per_user history when per_chat is used.

channels:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}
    group_policy: observe
    session_scope: per_chat

observe is Telegram-only today. Other adapters ignore it and fall back to their default group handling.

When to use it: a busy group where users want to @bot and have it see prior discussion; the bot stays quiet until addressed. When not to use it: noise-sensitive or high-PII channels — every unmentioned message is stored, increasing the volume of retained conversation text. See Session Scopes and Intentional Silence.

Shell execution

Set allow_shell: true on any channel to turn its bot into a shell-capable agent, with approval routed per platform. Policy is per-channel — one channel can auto-approve while another requires owner sign-off. On channels with routing rules, routed agents inherit execute_command too — the shell setup is re-applied to each routed agent, cloned and cached per (channel, agent). See Bot Shell Execution.

Routing rules apply to Slack @mentions. Slack handle_mention dispatches through registered on_message handlers, so per-route agent selection and allow_shell opt-in reach @mentions the same way they reach DMs and channel messages. On older builds, @mentions bypassed routing and ran the raw default agent. See Messaging Bots → Slack.

YAML Key	Type	Default	Purpose
`allow_shell`	`bool`	`False`	Opt in shell execution for this channel. Injects `execute_command`, lifts the deny-list entry, and appends a permission-grant line to the agent’s instructions.
`auto_approve_shell`	`bool`	`True`	Runs every shell call immediately only on a loopback-bound gateway + non-group channel. On externally-bound gateways or any channel with a `group_policy`, the gateway automatically downgrades this to an approval backend (see `auto_approve_shell_acknowledge_exposed`).
`auto_approve_shell_acknowledge_exposed`	`bool`	`False`	Explicit acknowledgement that blanket auto-approval is safe on this externally-exposed or multi-user channel. Set to `true` (with `auto_approve_shell: true`) to keep the blanket behaviour on `0.0.0.0` binds or group channels. Off by default — the gateway fails closed to approval.
`approval_channel`	`str`	`None`	Where the approval prompt is delivered (Slack user/channel ID, Telegram chat ID, Discord channel ID — falls back to `home_channel`).
`approval_users`	`str` \| `list[str]`	`None`	Approver allowlist. Comma-separated string or list. Falls back to `SLACK_APPROVERS` / `TELEGRAM_APPROVERS` / `DISCORD_APPROVERS`.
`approval_mode`	`str`	`None` (= `channel`)	Backend selector: `channel`, `gateway`, `http`, or `webhook`. Validated at load — typos raise `ValueError`.
`approval_webhook_url`	`str`	`None`	HTTPS URL for `approval_mode: webhook`. Falls back to `APPROVAL_WEBHOOK_URL`. Missing → warns and falls through to the gateway queue.
`approval_http_host`	`str`	`"127.0.0.1"`	HTTP dashboard host for `approval_mode: http`. Set `"0.0.0.0"` to expose.
`approval_http_port`	`int`	`8899`	HTTP dashboard port for `approval_mode: http`.

channels:
  telegram:
    token: "${TELEGRAM_BOT_TOKEN}"
    # allow_shell: true
    # auto_approve_shell: false
    # approval_channel: "123456789"

See Bot Shell Execution for the full routing ladder, per-platform ID resolution, env-var reference, and copy-paste recipes.

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"
    unknown_user_policy: deny     # deny (default, secure) | pair | allow
    owner_user_id: ${TELEGRAM_OWNER_ID}  # required if unknown_user_policy: pair
    group_policy: "mention_only"  # mention_only | command_only | respond_all | observe
    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.

Startup warnings

An empty allowed_users triggers a policy-aware warning at gateway start and on hot-reload. Grep these exact strings in your logs:

Channel 'telegram' has no allowed_users AND unknown_user_policy='deny' — inbound DMs from unknown users are SILENTLY DROPPED. Set unknown_user_policy: pair (with owner_user_id) or allow to change this.

Channel 'telegram' has no allowed_users AND unknown_user_policy='pair' — unknown users go through the owner-approval pairing flow. Ensure owner_user_id is set.

Channel 'telegram' has no allowed_users AND unknown_user_policy='allow' — bot accepts messages from everyone. This is intentional only in trusted networks.

If you see the deny warning and expected messages to flow through, your config is secure-by-default and DMs are intentionally dropped. Add IDs to allowed_users, or set unknown_user_policy: pair (with owner_user_id) or allow.

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.

Interactive presentations (optional)

GatewayMessage carries an optional presentation: MessagePresentation field. When set, channel adapters that implement SupportsPresentation render it as a native widget (Telegram inline keyboard, Slack Block Kit, Discord components). Channels that do not implement the protocol fall back to the message’s plain-text content. See Interactive Bot Messages for the full presentation model.

Hot-Reload

Editing gateway.yaml while the gateway runs triggers a diff-driven reload — only affected agents or channels restart. The WebSocket server stays up. See Gateway Hot-Reload for the full restart-scope table.

CLI Commands

praisonai gateway start --config gateway.yaml

praisonai gateway start --config gateway.yaml --host 0.0.0.0 --port 9000

praisonai gateway status

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

BotOS Options

When creating a BotOS instance in Python, the following options control gateway-level behaviour:

Field	Type	Default	Description
`bots`	`list[Bot]`	`[]`	Pre-built Bot instances to orchestrate
`agent`	`Agent`	`None`	Shared agent for auto-created bots (used with `platforms`)
`platforms`	`list[str]`	`None`	Platform names; creates one Bot per platform using the shared `agent`
`health_monitor`	`HealthMonitorConfig`	`None`	Channel health monitoring configuration
`enable_supervision`	`bool`	`True`	Enable automatic channel supervision and recovery
`idle_policy`	`GatewayIdlePolicyProtocol`	`None`	When set, schedules an idle-dormancy loop that quiesces transports after inactivity. Default `None` = always-on. See Scale-to-Zero Gateway.

from praisonaiagents import Agent
from praisonai.bots import BotOS, Bot
from praisonaiagents.gateway import ScaleToZeroPolicy

agent = Agent(name="assistant", instructions="Help users")

botos = BotOS(
    bots=[Bot("telegram", agent=agent)],
    idle_policy=ScaleToZeroPolicy(
        idle_timeout_minutes=5,
        wake_url="https://my-bot.fly.dev/_wake",
    ),
)
botos.run()

Observability

Gateway Metrics

Scrape GET /metrics for Prometheus-format counters and gauges on every hop of the message flow — no extra dependencies.

Correlation IDs

One stable id joins ingress, session, and agent-run logs for every turn. Read it inside any tool with current_correlation_id().

Gateway Tracing Hook

Open a distributed-tracing span around each pipeline stage — inbound, admit, agent.run, llm.call, tool.call, outbox.enqueue, delivery.

Code-Skew Guard

After running git pull or pip install -U, the gateway’s /model command detects that the installed code version has changed and blocks the model switch with a “restart required” message. This prevents the model from changing when the running code is out of sync with the installed libraries. To opt out (useful in development):

session_manager.code_skew_guard = False

Helpers for custom tooling:

from praisonaiagents.gateway import detect_code_skew, read_code_fingerprint

fingerprint = read_code_fingerprint()
if detect_code_skew(fingerprint):
    print("Code has changed since gateway started — restart recommended")

Best Practices

Lock down empty allowlists

Leave allowed_users empty only with unknown_user_policy: "deny" for production. Pairing mode is fine for personal bots; public gateways need explicit allowlists.

Route by channel context

Map dm, group, and default to different agents when support and personal assistants should not share memory or tools. Isolated clones prevent cross-channel leakage.

Use environment variables for tokens

Reference tokens as ${TELEGRAM_BOT_TOKEN} in YAML — never commit secrets. Gateway resolves env vars at load time on all platforms including Windows.

Monitor via /health and /metrics

Poll the health endpoint during deploys and wire Gateway Metrics into Prometheus for message-flow visibility.

/undo in a bot chat reverts files in that chat’s workspace, not the gateway process cwd. This happens automatically — apply_bot_smart_defaults() calls Agent.set_snapshot_root(workspace.root) after attaching the Workspace. See File Snapshot → Bot / Gateway Workspaces.

Bind-Aware Auth

Token auth plus the bind-aware loopback bypass (permissive on loopback by default) for gateway operational endpoints.

Gateway Error Handling

Supervision, restarts, and error recovery in the gateway.

Gateway Metrics

Prometheus-format message-flow metrics from GET /metrics.

Correlation IDs

Join ingress, session, and agent-run logs on one stable id per message.

Restart Continuation

Re-drive interrupted turns and notify the originating channel after a restart.

Gateway & Bots

Quick Start

Supported Channels

Telegram

Discord

Slack

WhatsApp

Configuration Reference

Gateway Section

Agents Section

Channels Section

Channel Security

`observe`: passive group context

Shell execution

Startup warnings

Interactive presentations (optional)

Hot-Reload

CLI Commands

Python Usage

BotOS Options

Observability

Gateway Metrics

Correlation IDs

Gateway Tracing Hook

Code-Skew Guard

Best Practices

Bind-Aware Auth

Gateway Error Handling

Gateway Metrics

Correlation IDs

Restart Continuation

​Quick Start

​Supported Channels

Telegram

Discord

Slack

WhatsApp

​Configuration Reference

​Gateway Section

​Agents Section

​Channels Section

​Channel Security

​observe: passive group context

​Shell execution

​Startup warnings

​Interactive presentations (optional)

​Hot-Reload

​CLI Commands

​Python Usage

​BotOS Options

​Observability

Gateway Metrics

Correlation IDs

Gateway Tracing Hook

​Code-Skew Guard

​Best Practices

​Related

Bind-Aware Auth

Gateway Error Handling

Gateway Metrics

Correlation IDs

Restart Continuation

Quick Start

Supported Channels

Configuration Reference

Gateway Section

Agents Section

Channels Section

Channel Security

`observe`: passive group context

Shell execution

Startup warnings

Interactive presentations (optional)

Hot-Reload

CLI Commands

Python Usage

BotOS Options

Observability

Code-Skew Guard

Best Practices

Related