Bot Onboarding

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

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

Quick Start

1. Run the onboard wizard

   # Zero prompts once you have the token — wizard configures the bot
   # and installs the background daemon automatically.
   praisonai onboard
   

   Once tokens are collected, the daemon is installed automatically by default. Run praisonai gateway uninstall if you don’t want it.

2. Answer 4 questions

   The wizard asks exactly 4 questions — everything else uses sensible defaults:

   1. Which platform(s)? — Telegram, Discord, Slack, WhatsApp (multi-select)
   2. Paste your bot token — hidden input, validated against the platform API
   3. Allowed user IDs — comma-separated allowlist (security). Leave blank for open access (not recommended).
   4. Install as background service? — Y on desktop, auto-skipped on CI/headless.
3. 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

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	Platform routing, token env-var references, allowlist, agent defaults
~/.praisonai/.env	Bot token(s), *_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.

Upgrading? Older bot.yaml files may contain a home_channel key (for example, home_channel: ${TELEGRAM_HOME_CHANNEL} or the equivalent for Discord / Slack / WhatsApp). This was never read by the gateway and is safe to delete. Re-running praisonai onboard and accepting the overwrite regenerates a clean file.

Auth token is now auto-persisted to ~/.praisonai/.env with secure permissions (mode 0600) and shown as fingerprint gw_****XXXX in logs for security.

---

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      # run in foreground (no daemon) │
│   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:

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

If the daemon is already installed, re-running praisonai onboard is a no-op for the daemon service. Only configuration files are updated.

---

Relationship to Setup

PraisonAI has two configuration commands that run in sequence:

• 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

# 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

# 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

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

Re-generate auth token

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

---

Which Platform Should I Use?

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.

Bind-Aware Authentication

Gateway and UI security behavior based on bind interface

---

Related

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