> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    User[👤 User] --> Wizard[🧙 Onboard Wizard]
    Wizard --> Platform{📱 Choose Platform}
    Platform --> Telegram[📱 Telegram]
    Platform --> Discord[💬 Discord]  
    Platform --> Slack[💼 Slack]
    Platform --> WhatsApp[📞 WhatsApp]
    Telegram --> Daemon[⚙️ Auto-install Daemon]
    Discord --> Daemon
    Slack --> Daemon
    WhatsApp --> Daemon
    Daemon --> Done[✅ Done Panel]
    
    classDef user fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef wizard fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef platform fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff
    
    class User user
    class Wizard wizard
    class Platform,Telegram,Discord,Slack,WhatsApp platform
    class Daemon,Done result
```

## Quick Start

<Steps>
  <Step title="Run the onboard wizard">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # 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>
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

***

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Wizard
    participant Platform
    participant Daemon
    
    User->>Wizard: praisonai onboard
    Wizard->>User: Choose platform
    User->>Wizard: Select platform
    Wizard->>Platform: Validate token
    Platform-->>Wizard: Token valid
    Wizard->>Daemon: Install service
    Daemon-->>Wizard: Service installed
    Wizard->>User: ✅ Done panel
```

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.

<Note>
  **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.
</Note>

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

***

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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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.

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

***

## Relationship to Setup

PraisonAI has two configuration commands that run in sequence:

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Install[Installer] --> Setup[praisonai setup<br/>LLM/API Keys]
    Setup --> Onboard[praisonai onboard<br/>Messaging Bots]
    Onboard --> Ready[✅ Ready to Use]
    
    classDef command fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff
    
    class Setup,Onboard command
    class Ready result
```

* **`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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Currently using Telegram, switch to Discord
praisonai onboard
# Choose Discord and enter Discord bot token
```

### Re-generate auth token

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Run onboarding again to get a fresh auth token
praisonai onboard
```

***

## Which Platform Should I Use?

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Start{What's your use case?}
    Start -->|Personal assistant| Telegram[🎯 Telegram<br/>Easy setup, great for individuals]
    Start -->|Team collaboration| Slack[🎯 Slack<br/>Integrates with team workflows]
    Start -->|Gaming/Community| Discord[🎯 Discord<br/>Rich features, voice support]
    Start -->|Business/Customer support| WhatsApp[🎯 WhatsApp<br/>Wide adoption, mobile-first]
    
    classDef platform fill:#189AB4,stroke:#7C90A0,color:#fff
    
    class Telegram,Slack,Discord,WhatsApp platform
```

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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Keep tokens secure">
    Bot tokens are stored in `~/.praisonai/.env`. Ensure this file has proper permissions (600) and exclude it from version control.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Use 'praisonai doctor' for troubleshooting">
    If bots aren't responding or services seem down, run `praisonai doctor` for diagnostic information and common fixes.
  </Accordion>
</AccordionGroup>

<Card title="Bind-Aware Authentication" icon="shield" href="/docs/features/gateway-bind-aware-auth">
  Gateway and UI security behavior based on bind interface
</Card>

***

## Related

<CardGroup cols={2}>
  <Card title="Installation Guide" icon="download" href="/docs/install/installer">
    Complete installer documentation including onboarding flow
  </Card>

  <Card title="Dashboard" icon="layout-dashboard" href="/docs/cli/dashboard">
    Web dashboard for managing agents and monitoring bots
  </Card>

  <Card title="Bot Security" icon="shield" href="/docs/best-practices/bot-security">
    Security best practices for messaging bots
  </Card>

  <Card title="Quick Install" icon="bolt" href="/docs/install/quickstart">
    One-liner installation including onboarding prompt
  </Card>
</CardGroup>