Bot Onboarding

Set up Telegram, Discord, Slack, or WhatsApp bots in 60 seconds

python

from praisonaiagents import Agent

agent = Agent(name="onboard-agent", instructions="Onboard users and configure their environment.")
agent.start("Set up my PraisonAI environment with default settings.")

Interactive wizard that configures messaging bots and automatically installs the daemon service to run them in the background.

The user runs the wizard, picks a channel, and the daemon installs so bots stay online.

Diagram

Quick Start

Simple Usage
bash
```
# Zero prompts once you have the token — wizard configures the bot
# and installs the background daemon automatically.
praisonai onboard
```
Note
Once tokens are collected, the daemon is installed automatically by default. Run praisonai gateway uninstall if you don’t want it.

Note
The auto-installed unit already bounds crash-loops on the gateway’s fatal-config exit code (78, EX_CONFIG) — no manual RestartPreventExitStatus/KeepAlive tweaking needed. See Gateway Exit Codes.
With Configuration
The wizard guides you through channel setup with an interactive flow:
1. Choose first platform — Telegram, Discord, Slack, or WhatsApp
2. Enter bot token — Hidden input, validated against the platform API
3. Add another bot channel? — Create multiple bots on the same platform for different roles
4. Enter role (if adding more) — Role name like cfo, ops, content for specialized agents
5. Configure security — Allowed user IDs for each channel (comma-separated)
The wizard automatically generates environment variables following the `PLATFORM_

_BOT_TOKEN` convention.
You're done
The wizard writes bot configuration to ~/.praisonai/bot.yaml, stores tokens/secrets in ~/.praisonai/.env only (chmod 600), and shows the ✅ Done panel with your dashboard URL.

How It Works

Diagram

The onboarding process follows these phases:

Phase	Description
Platform Selection	Choose Telegram, Discord, Slack, or WhatsApp
Token Entry	Paste the bot token for your chosen platform and validate it against the platform API
Security Setup	Set allowed user IDs (or leave blank for open access)
Daemon Install	Sets up the platform daemon (launchd/systemd/Windows Task)
Configuration	Writes config files to `~/.praisonai/`
Completion	Shows the ✅ Done panel with all connection details

What The Wizard Writes

File	Contents
`~/.praisonai/bot.yaml`	Channel configurations, multi-platform/multi-role routing, token env-var references, specialized agents
`~/.praisonai/.env`	Bot token(s) with role-based naming, `*_ALLOWED_USERS`, `GATEWAY_AUTH_TOKEN` (chmod 600)

Component	Location	Purpose
Platform daemon	System service (launchd/systemd/Windows Task)	Keeps bot running in background
Bot configuration	`~/.praisonai/config/`	Stores tokens and settings
Gateway auth token	`~/.praisonai/.env` (mode `0600`)	Authentication for web dashboard
Dashboard URL	Printed in Done panel	Local web interface

Agent name (assistant) and instructions ("You are a helpful AI assistant.") use sensible defaults — edit ~/.praisonai/bot.yaml to customise. The file contains the full schema as inline documentation.

Generated bot.yaml example

yaml

channels:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}
    allowed_users: ${TELEGRAM_ALLOWED_USERS}
    ack_emoji: "⏳"            # Show processing indicator during long agent operations
    done_emoji: "✅"           # Replace ack_emoji when operation completes
    ack_scope: "group-mentions" # Who gets acked: off | direct | group-mentions | group-all | all

Ack and done emojis are pre-populated so freshly onboarded bots give visible feedback during long agent operations from the start. The scope defaults to group-mentions, so freshly onboarded bots stay quiet on ambient group chatter out of the box — set ack_scope: "all" to ack every message.

Tip

What runs next. praisonai gateway start now auto-discovers this ~/.praisonai/bot.yaml — no --config needed. It prints Using gateway config: <path> and binds with channels, so the happy path after onboarding is a two-command start:

bash

praisonai onboard        # writes ~/.praisonai/bot.yaml + ~/.praisonai/.env
praisonai gateway start  # discovers the onboarded file automatically
# → Using gateway config: /Users/you/.praisonai/bot.yaml

See Gateway Config Discovery for the full resolution order.

Step 5c: Verify the agent replies

After writing bot.yaml, the wizard runs a single "ping" turn against the first channel with a token — the same code path as gateway start --verify-turn. This confirms your model credential works at setup, not on the first user message.

Step 5c: Verify the agent replies
  Running one test turn ('ping')...
  ✓ Agent replied — model credentials work        # success
  ⚠ Agent did not reply: <detail>                  # failure (warn, do not abort)
    Set the model/provider API key (e.g. ANTHROPIC_API_KEY) in
    ~/.praisonai/.env, then re-run `praisonai onboard` or
    `praisonai gateway test --turn ping`.

The (e.g. ...) hint names the detected provider’s key env var, not always OPENAI_API_KEY. If the wizard resolved an Anthropic model it suggests ANTHROPIC_API_KEY; for Gemini, GEMINI_API_KEY; for a local Ollama endpoint, OLLAMA_HOST; and so on. See Provider auto-detection.

This step is best-effort — a failure prints a warning with a next step but never aborts onboarding. It is skipped when no channel has a token.

Opt out with an environment variable:

bash

PRAISONAI_NO_VERIFY_TURN=1 praisonai onboard

PRAISONAI_NO_VERIFY_TURN accepts 1, true, yes, or on.

Variable	Values	Effect
`PRAISONAI_NO_VERIFY_TURN`	`1` / `true` / `yes` / `on`	Skip the Step 5c real-turn check during onboarding.

The ✅ Done Panel

When onboarding completes, you’ll see a comprehensive summary panel with four main sections:

╭─ ✅ Done ──────────────────────────────────────────────────────╮
│ Setup complete! Your bot is now running in the background.     │
│                                                                │
│ 🦞 Dashboard UI:                                               │
│   praisonai claw          → http://127.0.0.1:8082              │
│                                                                │
│ Gateway endpoints:                                             │
│   Health (public):  http://127.0.0.1:8765/health               │
│   Info (authed):    http://127.0.0.1:8765/info?token=…         │
│   Token abcd…wxyz stored in ~/.praisonai/.env as               │
│   GATEWAY_AUTH_TOKEN                                           │
│                                                                │
│ Manage the daemon:                                             │
│   praisonai gateway status     # is it running?                │
│   praisonai gateway logs       # tail the logs                 │
│   launchctl kickstart -k gui/$(id -u)/ai.praison.bot           │
│   praisonai gateway uninstall  # remove the daemon             │
│                                                                │
│ Re-run or reconfigure:                                         │
│   praisonai onboard            # change tokens / add platforms │
│   praisonai gateway start      # foreground; discovers bot.yaml │
│   praisonai doctor             # diagnose the whole stack      │
╰────────────────────────────────────────────────────────────────╯

The headline changes based on daemon install success:

Success: “Setup complete! Your bot is now running in the background.”
Failed: “Setup complete! Configuration complete.”

Re-running Onboarding

The wizard is idempotent – safe to run multiple times:

bash

# Update an existing bot's token
praisonai onboard

# Switch from Telegram to Discord
praisonai onboard

Re-running the wizard will:

Update tokens and configurations in place
Skip daemon installation if already installed and running (prints ✓ Daemon already installed and running)
Preserve existing chat histories and agent memory

The config file path is always ~/.praisonai/bot.yaml (no longer prompted for). When re-running, the overwrite prompt now says {path} exists. Overwrite with fresh config? with Kept existing file on decline.

Adding Multiple Bots on the Same Platform

The wizard now supports creating multiple specialized bots on the same platform for different roles:

bash

# Example wizard flow
praisonai onboard
# Choose telegram
# Enter first bot token
# "Add another bot channel?" → Yes
# "Role for this Telegram bot?" → cfo
# Enter CFO bot token
# "Add another bot channel?" → Yes  
# "Role for this Telegram bot?" → ops
# Enter Ops bot token

This creates environment variables with role-based naming:

env

TELEGRAM_BOT_TOKEN=123456789:ABC...          # Main bot
TELEGRAM_CFO_BOT_TOKEN=987654321:DEF...     # CFO bot
TELEGRAM_OPS_BOT_TOKEN=456789123:GHI...     # Ops bot
TELEGRAM_ALLOWED_USERS=123456789,987654321

The generated bot.yaml will contain multiple channels routing to specialized agents. See the Multi-Channel Bots guide for complete documentation.

Relationship to Setup

PraisonAI has two configuration commands that run in sequence:

Diagram

praisonai setup – Configures LLM providers (OpenAI, Anthropic, etc.)
praisonai onboard – Configures messaging bots (Telegram, Discord, etc.)

Both are called automatically by the installer, but can be run independently.

Common Patterns

Skip onboarding during install

bash

# Skip during installation
curl -fsSL https://praison.ai/install.sh | bash -s -- --no-onboard

# Or via environment variable
PRAISONAI_NO_ONBOARD=1 curl -fsSL https://praison.ai/install.sh | bash

Run onboarding separately later

bash

# Install first without onboarding
curl -fsSL https://praison.ai/install.sh | bash -s -- --no-onboard

# Set up LLM keys
praisonai setup

# Set up messaging bot when ready
praisonai onboard

Switch platforms

bash

# Currently using Telegram, switch to Discord
praisonai onboard
# Choose Discord and enter Discord bot token

Re-generate auth token

bash

# Run onboarding again to get a fresh auth token
praisonai onboard

Which Platform Should I Use?

Diagram

Choose based on:

Platform	Best For	Setup Difficulty	Features
Telegram	Personal use, experimentation	Easy	Rich bot API, inline keyboards
Discord	Gaming communities, developer teams	Medium	Voice channels, rich embeds
Slack	Business teams, professional workflows	Medium	Thread support, workspace integration
WhatsApp	Customer support, global reach	Hard	Business accounts required

Best Practices

Start with Telegram for testing

Telegram has the simplest setup process and most permissive API limits. Use it for initial testing before moving to your target platform.

Keep tokens secure

Bot tokens are stored in ~/.praisonai/.env. Ensure this file has proper permissions (600) and exclude it from version control.

Test the dashboard connection

After onboarding, visit the dashboard URL from the Done panel to confirm the web interface is working and authentication is set up correctly.

Use 'praisonai doctor' for troubleshooting

If bots aren’t responding or services seem down, run praisonai doctor for diagnostic information and common fixes. If you onboarded multiple bots on one platform and see Unknown channel 'telegram_<role>' from praisonai doctor, upgrade to a release that includes PR #1772. Older releases incorrectly rejected the multi-channel YAML their own onboard wizard produced.

Bind-Aware Authentication

Gateway and UI security behavior based on bind interface

Setup Wizard

Configure LLM provider credentials with auto-detect, key validation, and a smoke test

Installation Guide

Complete installer documentation including onboarding flow

Dashboard

Web dashboard for managing agents and monitoring bots

Bot Security

Security best practices for messaging bots

Quick Install

One-liner installation including onboarding prompt

Bot Onboarding

Quick Start

How It Works

What The Wizard Writes

Generated bot.yaml example

Step 5c: Verify the agent replies

The ✅ Done Panel

Re-running Onboarding

Adding Multiple Bots on the Same Platform

Relationship to Setup

Common Patterns

Skip onboarding during install

Run onboarding separately later

Switch platforms

Re-generate auth token

Which Platform Should I Use?

Best Practices

Related