Standalone Bot YAML

Describe your agent, gateway, and channel platforms in a single YAML file — no Python required.

from praisonaiagents import Agent

agent = Agent(name="bot-agent", instructions="Reply to users across chat channels.")
agent.start("Answer incoming messages from Telegram and Discord.")

The user defines a bot.yaml; the gateway loads it and connects the agent to every configured channel.

How It Works

Config Structure

Quick Start

Install

pip install praisonaiagents "praisonai-bot[gateway,bot]"

Set credentials

export OPENAI_API_KEY=your_openai_api_key
export TELEGRAM_BOT_TOKEN=your_telegram_token

Create bot.yaml

agent:
  name: assistant
  instructions: You are a helpful assistant.
  llm: gpt-4o-mini

gateway:
  host: 127.0.0.1
  port: 8765

platforms:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}

Start the gateway with your YAML

praisonai-bot gateway start --config bot.yaml

The gateway registers the agent and starts all configured channel bots automatically.

Config Options Reference

`agent` section

Key	Type	Default	Description
`agent.name`	`str`	required	Agent display name, used as the `agent_id` for gateway routing
`agent.instructions`	`str`	required	System prompt / instructions for the agent
`agent.llm`	`str`	`"gpt-4o-mini"`	LLM model identifier (e.g. `gpt-4o`, `gpt-4o-mini`)

`gateway` section

Key	Type	Default	Description
`gateway.host`	`str`	`"127.0.0.1"`	Host to bind the WebSocket server
`gateway.port`	`int`	`8765`	Port to listen on

`platforms` section

Each key under platforms is a platform name. Use ${VAR_NAME} for environment variable interpolation.

Key pattern	Type	Description
`platforms.<name>.token`	`str`	Bot token for the platform. Supports `${ENV_VAR}` substitution
`platforms.slack.app_token`	`str`	Slack App-Level Token (`xapp-...`) for Socket Mode. Required for Slack when Socket Mode is used. Supports `${ENV_VAR}` and secret references.

Supported platforms: telegram, discord, slack, whatsapp, and any platform registered via entry points.

Single-platform shorthand

For one platform, declare a top-level platform: (and optionally token:) instead of a platforms: map:

platform: telegram
token: "${TELEGRAM_BOT_TOKEN}"

token: is optional — omit it and the declared platform: resolves the platform’s own documented env var (TELEGRAM_BOT_TOKEN, DISCORD_BOT_TOKEN, etc.):

platform: telegram

The declared platform always wins. If other platform credentials are exported in the environment, bot start refuses to auto-enable them and logs a warning:

WARNING Config declares 'platform: telegram'; NOT auto-enabling discord, slack
despite their credentials being present in the environment. The declared
platform wins. To run them too, list them under 'channels:' explicitly.

Earlier versions could silently start the wrong platform if unrelated credentials were set. Now the declared platform always wins — list multiple platforms under channels: explicitly to run them together.

Admission policy (`unknown_user_policy` / `owner_user_id`)

Control who may DM a single-bot instance directly from bot.yaml. Since PR #5111, praisonai bot start wires unknown_user_policy and owner_user_id into the running bot for telegram / discord / slack — matching the gateway path exactly.

# bot.yaml — single-bot admission policy
platform: telegram
token: ${TELEGRAM_BOT_TOKEN}
unknown_user_policy: allow        # deny (default) | pair | allow
owner_user_id: 987654321          # required when unknown_user_policy: pair
agent:
  name: Assistant
  instructions: Reply to incoming messages.

Both fields also work at the channel level for the multi-channel shape:

# bot.yaml — channel-level admission policy
channels:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}
    unknown_user_policy: pair
    owner_user_id: 987654321
agent:
  name: Assistant
  instructions: Reply to incoming messages.

Value	Meaning
`deny`	Default. Silently drop inbound DMs from users not on `allowed_users`.
`pair`	Route unknown users through the owner-approval / pairing flow. Requires `owner_user_id`.
`allow`	Open DMs to everyone. Trusted networks / open bots only.

Values are case-insensitive on load (ALLOW normalises to allow) and whitespace is trimmed. An unquoted numeric owner_user_id (e.g. 987654321) is coerced to a string automatically.

On startup, praisonai bot start prints the resolved policy so you can confirm it at a glance:

unknown_user_policy: allow

The line reflects the YAML value, or deny when omitted — the secure default is now visible rather than silent. It only prints on platforms that actually wire the policy (telegram / discord / slack).

A misspelled policy (alow, deney, …) fails closed at load time rather than silently reverting to deny:

Invalid unknown_user_policy 'alow'. Must be one of: allow, deny, pair

Treat this error as intended — fix the typo and restart.

Unknown-User Pairing

Full owner-approval flow, inline buttons, and CLI fallback.

Slack single-bot shorthand

Slack Socket Mode also needs an app-level token, so add a top-level app_token: alongside token::

platform: slack
token: "${SLACK_BOT_TOKEN}"
app_token: "${SLACK_APP_TOKEN}"

app_token: accepts the same three forms as token: — plaintext, ${ENV} interpolation, and the { source, id } secret reference.

app_token is Slack-specific. When platform: is anything other than slack, a top-level app_token: is ignored — this keeps a strict non-Slack adapter from rejecting an unexpected keyword. For the multi-channel form, set app_token under the Slack entry in channels: (see Messaging Bots).

Run a Slack bot in three lines plus the agent block:

# bot.yaml — Slack Socket Mode single-bot shorthand
platform: slack
token: "${SLACK_BOT_TOKEN}"
app_token: "${SLACK_APP_TOKEN}"

agent:
  name: assistant
  instructions: Reply to Slack mentions.
  llm: gpt-4o-mini

export SLACK_BOT_TOKEN=xoxb-...
export SLACK_APP_TOKEN=xapp-...
praisonai bot start --config bot.yaml

Bot startup exit codes: praisonai bot start now exits 1 on any startup failure (bad config path, missing token, unknown platform). This makes systemd Restart=on-failure and if praisonai bot start ... ; then scripting work as expected.

Shell execution keys

Add these per-channel keys to let a bot run shell commands with approval routing.

Key pattern	Type	Default	Description
`<name>.allow_shell`	`bool`	`False`	Opt in shell execution. Injects `execute_command`, lifts the deny-list entry, and appends a permission-grant line to instructions.
`<name>.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 `<name>.auto_approve_shell_acknowledge_exposed`).
`<name>.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.
`<name>.approval_channel`	`str`	`None`	Where the approval prompt is delivered (platform-specific ID).
`<name>.approval_users`	`str` \| `list[str]`	`None`	Approver allowlist. Comma-separated string or list.
`<name>.approval_mode`	`str`	`None` (= `channel`)	Backend selector: `channel`, `gateway`, `http`, `webhook`. Typos raise `ValueError`.
`<name>.approval_webhook_url`	`str`	`None`	HTTPS URL for `approval_mode: webhook`.
`<name>.approval_http_host`	`str`	`"127.0.0.1"`	HTTP dashboard host for `approval_mode: http`.
`<name>.approval_http_port`	`int`	`8899`	HTTP dashboard port for `approval_mode: http`.

Bot Shell Execution

Full routing ladder, per-platform ID resolution, and recipes.

Environment Variable Interpolation

Values in the form ${VAR_NAME} are resolved from the current environment at startup:

platforms:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}   # reads os.environ["TELEGRAM_BOT_TOKEN"]
  discord:
    token: ${DISCORD_BOT_TOKEN}    # reads os.environ["DISCORD_BOT_TOKEN"]

Tokens stored in ~/.praisonai/.env (written by praisonai-bot onboard) are loaded automatically before interpolation.

When to Pick YAML vs Python

Scenario	Use
Operations team manages tokens	YAML — credentials stay out of code
Static single-agent setup	YAML — fewer moving parts
Dynamic agents (created at runtime)	Python — full control over `register_agent()`
Custom gateway middleware or hooks	Python — subclass or extend `WebSocketGateway`
Multiple environments (dev / staging / prod)	YAML — per-environment files with env vars

Common Patterns

Multi-platform setup

agent:
  name: assistant
  instructions: You are a helpful assistant.
  llm: gpt-4o-mini

gateway:
  host: 0.0.0.0
  port: 8765

platforms:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}
  discord:
    token: ${DISCORD_BOT_TOKEN}
  slack:
    token: ${SLACK_BOT_TOKEN}

Custom port from environment

gateway:
  host: 0.0.0.0
  port: 9000

Or set the GATEWAY_PORT environment variable — the CLI reads it automatically when --port is not passed.

Best Practices

Always use ${...} for tokens

Never hardcode tokens in YAML. Use environment variables and store them in ~/.praisonai/.env (written by praisonai-bot onboard) or your secrets manager.

# Good
platforms:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}

# Never do this
platforms:
  telegram:
    token: 1234567890:ABCdef...

Run praisonai-bot gateway doctor before going live

praisonai-bot gateway doctor --config bot.yaml

This validates every channel token before starting, so a bad token fails fast instead of silently reconnecting. It also prints a credential availability table for token, app_token, and verify_token — including the secret-reference form — without revealing any value.

Use separate YAML files per environment

Keep dev.yaml, staging.yaml, and prod.yaml — each referencing different environment variables. Pass the right one with --config.

Standalone Bot Gateway (Python)

Python API equivalent — register agents programmatically

Gateway CLI

Full list of gateway CLI commands

BotOS

Multi-platform bot orchestration

praisonai-bot SDK

Full bot-tier SDK reference

​How It Works

​Config Structure

​Quick Start

​Config Options Reference

​agent section

​gateway section

​platforms section

​Single-platform shorthand

​Admission policy (unknown_user_policy / owner_user_id)

Unknown-User Pairing

​Slack single-bot shorthand

​Shell execution keys

Bot Shell Execution

​Environment Variable Interpolation

​When to Pick YAML vs Python

​Common Patterns

​Multi-platform setup

​Custom port from environment

​Best Practices

​Related

Standalone Bot Gateway (Python)

Gateway CLI

BotOS

praisonai-bot SDK

How It Works

Config Structure

Quick Start

Config Options Reference

`agent` section

`gateway` section

`platforms` section

Single-platform shorthand

Admission policy (`unknown_user_policy` / `owner_user_id`)

Slack single-bot shorthand

Shell execution keys

Environment Variable Interpolation

When to Pick YAML vs Python

Common Patterns

Multi-platform setup

Custom port from environment

Best Practices

Related