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

# Multi-Channel Bots

> Run multiple bots on one platform — one per role (CFO, Ops, Content) — with per-channel tokens

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(name="multi-channel-bot", instructions="Respond across Telegram, Slack, and Discord.")
agent.start("Handle the same question from users on all three platforms.")
```

The user deploys role-specific bots on one platform; each token routes to its agent.

Deploy multiple specialized bots on the same platform with unique tokens and role-specific routing.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Multi-Channel Bot Workforce"
        User[👤 User] --> CFO[🤖 @company_cfo_bot]
        User --> Ops[🤖 @company_ops_bot]
        User --> Content[🤖 @company_content_bot]
        CFO --> CFOAgent[💼 CFO Agent]
        Ops --> OpsAgent[⚙️ Ops Agent]
        Content --> ContentAgent[✏️ Content Agent]
    end
    
    classDef user fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef bot fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef agent fill:#10B981,stroke:#7C90A0,color:#fff
    
    class User user
    class CFO,Ops,Content bot
    class CFOAgent,OpsAgent,ContentAgent agent
```

## Quick Start

> [!TIP]
>
> `Bot(...).run()` auto-reconnects on a dropped connection by default — see [Auto-reconnect on `long-running-bots`](https://praison.ai/docs/docs/features/long-running-bots#auto-reconnect-default).

**1. Run onboard wizard**

Start the wizard and choose your platform:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai onboard
```

Choose `telegram` for your first platform, then when prompted "Add another bot channel?" answer `Yes` and enter roles like `cfo`, `ops`, `content`.

**2. Configure tokens**

The wizard generates unique environment variables for each channel:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Tokens are saved to ~/.praisonai/.env automatically
TELEGRAM_CFO_BOT_TOKEN=123456789:ABC...
TELEGRAM_OPS_BOT_TOKEN=987654321:DEF...
TELEGRAM_CONTENT_BOT_TOKEN=456789123:GHI...
TELEGRAM_ALLOWED_USERS=123456789,987654321
```

> [!NOTE]
>
> If you leave `TELEGRAM_ALLOWED_USERS` empty, you must also set `unknown_user_policy: "allow"` for the bot to reply to anyone (since [PR #1885](https://github.com/MervinPraison/PraisonAI/pull/1885)). For production, set `TELEGRAM_ALLOWED_USERS` to your user IDs and leave `unknown_user_policy` at the default `"deny"`. This applies to **both** `praisonai gateway start` and `praisonai bot start` ([PR #5111](https://github.com/MervinPraison/PraisonAI/pull/5111)). For the single-bot YAML shape, see [Standalone Bot YAML → Admission policy](https://praison.ai/docs/features/standalone-bot-yaml.md#admission-policy-unknown-user-policy-owner-user-id).

**3. Start the gateway**

Launch all bots simultaneously:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai gateway start
```

All configured bots will connect and route to their specialized agents.

***

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant CFOBot as @company_cfo_bot
    participant Gateway as Gateway
    participant CFOAgent as CFO Agent
    
    User->>CFOBot: "What's our Q4 budget?"
    CFOBot->>Gateway: Route to cfo channel
    Gateway->>CFOAgent: Process with CFO instructions
    CFOAgent-->>Gateway: Financial analysis response
    Gateway-->>CFOBot: Return response
    CFOBot-->>User: CFO expertise reply
```

Multi-channel setup routes each bot to its specialized agent based on the channel configuration.

***

## Environment Variable Convention

Follow this exact naming pattern for multiple bots on the same platform:

| Channel key | Environment Variable | Bot Purpose |
| - | - | - |
| `telegram_cfo` | `TELEGRAM_CFO_BOT_TOKEN` | CFO-related tasks |
| `telegram_ops` | `TELEGRAM_OPS_BOT_TOKEN` | Operations tasks |
| `telegram_content` | `TELEGRAM_CONTENT_BOT_TOKEN` | Content creation |
| `telegram_support` | `TELEGRAM_SUPPORT_BOT_TOKEN` | Customer support |

**Pattern**: `<PLATFORM>_<ROLE>_BOT_TOKEN` (uppercase, role separated by underscore).

***

## Example Configuration

This `bot.yaml` shows a complete multi-channel workforce setup:

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
gateway:
  host: "127.0.0.1"
  port: 8765

agents:
  cfo:
    instructions: "You are a CFO agent. Help with financial analysis, budget planning, and cost optimization."
    model: gpt-4o-mini
    memory: false
  ops:
    instructions: "You are an ops agent. Help with system monitoring, deployment, and infrastructure."
    model: gpt-4o-mini
    memory: false
  content:
    instructions: "You are a content agent. Help with writing, editing, and content strategy."
    model: gpt-4o-mini
    memory: false

channels:
  telegram_cfo:
    platform: telegram
    token: ${TELEGRAM_CFO_BOT_TOKEN}
    group_policy: mention_only
    allowed_users: ${TELEGRAM_ALLOWED_USERS}
    routes:
      default: cfo
  telegram_ops:
    platform: telegram
    token: ${TELEGRAM_OPS_BOT_TOKEN}
    group_policy: mention_only
    allowed_users: ${TELEGRAM_ALLOWED_USERS}
    routes:
      default: ops
  telegram_content:
    platform: telegram
    token: ${TELEGRAM_CONTENT_BOT_TOKEN}
    group_policy: mention_only
    allowed_users: ${TELEGRAM_ALLOWED_USERS}
    routes:
      default: content
```

> [!NOTE]
>
> `group_policy` accepts any of `mention_only`, `command_only`, `respond_all`, or `observe` per channel, and each value behaves the same on Telegram, Discord and Slack. `observe` keeps unmentioned Telegram, Discord and Slack group messages as passive context. See [`observe`: passive group context](https://praison.ai/docs/docs/features/bot-gateway#observe-passive-group-context).

***

## Common Patterns

> [tab] Single platform, multiple roles
>
> Deploy multiple specialized bots on one platform:
>
> ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> channels:
>   telegram_finance:
>     platform: telegram
>     token: ${TELEGRAM_FINANCE_BOT_TOKEN}
>     routes:
>       default: finance_agent
>
>   telegram_hr:
>     platform: telegram
>     token: ${TELEGRAM_HR_BOT_TOKEN}
>     routes:
>       default: hr_agent
>
>   telegram_marketing:
>     platform: telegram
>     token: ${TELEGRAM_MARKETING_BOT_TOKEN}
>     routes:
>       default: marketing_agent
> ```

> [tab] Cross-platform workforce
>
> Distribute roles across different platforms:
>
> ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> channels:
>   telegram_cfo:
>     platform: telegram
>     token: ${TELEGRAM_CFO_BOT_TOKEN}
>     routes:
>       default: cfo
>
>   discord_ops:
>     platform: discord
>     token: ${DISCORD_OPS_BOT_TOKEN}
>     routes:
>       default: ops
>
>   slack_content:
>     platform: slack
>     token: ${SLACK_CONTENT_BOT_TOKEN}
>     routes:
>       default: content
> ```

> [tab] Local + remote continuity
>
> Add the built-in `local` channel next to a remote one — start a conversation in your terminal and keep the same session going from your phone.
>
> ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> channels:
>   local: {}
>   telegram:
>     platform: telegram
>     token: ${TELEGRAM_BOT_TOKEN}
>
> agents:
>   assistant:
>     instructions: "You are a helpful assistant."
> ```
>
> ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> praisonai-bot gateway start
> ```
>
> Both surfaces share one resolved session id via the identity resolver and delivery router. See [Local (Terminal) Channel](https://praison.ai/docs/features/local-channel.md).

***

## Validation with `praisonai doctor`

The `multi_channel_tokens` check validates your setup:

### PASS Conditions

* Each channel has a unique environment variable
* Each environment variable resolves to a unique token value
* Follows `PLATFORM_<ROLE>_BOT_TOKEN` naming convention

### WARN Conditions

* Environment variable doesn't follow naming convention
* Environment variable is unset but referenced in config

### FAIL Conditions

* Two channels point to the same environment variable
* Two environment variables resolve to the same token value

**Sample output:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
$ praisonai doctor
✓ Multi-Channel Token Configuration: Multi-channel configuration looks good (3 channels)
```

**Remediation:** Each channel must have a unique bot token. Create separate bots in @BotFather and use unique environment variables.

***

## Best Practices

> [accordion] Use unique tokens per role
>
> Create a separate bot in @BotFather for each role. Never reuse the same token across multiple channels as this will cause conflicts and validation failures.

> [accordion] Follow naming convention
>
> Stick to the `PLATFORM_<ROLE>_BOT_TOKEN` pattern so the doctor check passes. This makes it clear which token belongs to which channel and role.

> [accordion] Secure token storage
>
> Keep all role tokens in `~/.praisonai/.env` with chmod 600 permissions. Never commit tokens to version control or share them publicly.

> [accordion] Role-specific access control
>
> Each role can have its own `allowed_users` environment variable for granular access control. For example, only finance team members should access the CFO bot.

***

## When to Use Multi-Channel

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Start[Need multiple bots?] --> SamePlatform{Same platform?}
    SamePlatform -->|Yes| MultiChannel[Use Multi-Channel<br/>Multiple roles, one platform]
    SamePlatform -->|No| MultiPlatform[Use Multi-Platform<br/>One bot per platform]
    
    MultiChannel --> UseCase1[• Department-specific bots<br/>• Role-based expertise<br/>• Workflow separation]
    MultiPlatform --> UseCase2[• Reach different audiences<br/>• Platform-specific features<br/>• Redundancy across platforms]
    
    Start --> SingleBot{Just one bot?}
    SingleBot -->|Yes| SimpleSetup[Standard single bot setup]
    
    classDef decision fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef solution fill:#10B981,stroke:#7C90A0,color:#fff
    classDef usecase fill:#6366F1,stroke:#7C90A0,color:#fff
    
    class Start,SamePlatform,SingleBot decision
    class MultiChannel,MultiPlatform,SimpleSetup solution
    class UseCase1,UseCase2 usecase
```

***

## Related

> [card] [Bot Onboarding](https://praison.ai/docs/features/onboard.md)
>
> Set up your first bot with the interactive wizard

> [card] [Messaging Bots](https://praison.ai/docs/features/messaging-bots.md)
>
> Core bot functionality and platform integration

> [card] [Bot Routing](https://praison.ai/docs/features/bot-routing.md)
>
> Advanced routing patterns and agent selection

> [card] [Bot Security](https://praison.ai/docs/best-practices/bot-security.md)
>
> Security best practices for bot deployments


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.