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

# Channel Configuration

> Configure Telegram, WhatsApp, Discord, Slack, and Email channels

## Overview

OrcBot supports multiple communication channels with per-channel configuration for auto-reply, admin permissions, and channel-specific features.

## Telegram

### Basic Configuration

<ParamField path="telegramToken" type="string">
  Telegram bot token obtained from [@BotFather](https://t.me/botfather).

  **Policy:** LOCKED - Critical authentication credential.

  **Environment variable:** `TELEGRAM_TOKEN`
</ParamField>

<ParamField path="telegramAutoReplyEnabled" type="boolean" default={false}>
  Enable automatic replies to all messages without requiring /commands.
</ParamField>

### Getting Started

<Steps>
  <Step title="Create a bot with BotFather">
    1. Open Telegram and search for [@BotFather](https://t.me/botfather)
    2. Send `/newbot` and follow the prompts
    3. Copy the bot token provided
  </Step>

  <Step title="Configure OrcBot">
    ```yaml orcbot.config.yaml theme={null}
    telegramToken: 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
    telegramAutoReplyEnabled: true
    ```

    Or use environment variable:

    ```bash .env theme={null}
    TELEGRAM_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
    ```
  </Step>

  <Step title="Start the bot">
    ```bash theme={null}
    orcbot run
    ```
  </Step>

  <Step title="Find your user ID">
    Send a message to your bot, then check logs or use the `/admin` command to see your Telegram user ID.
  </Step>

  <Step title="Add yourself as admin">
    ```yaml orcbot.config.yaml theme={null}
    adminUsers:
      telegram:
        - "123456789"  # Your Telegram user ID
    ```
  </Step>
</Steps>

### Commands

<ParamField path="telegramCommands" type="array">
  List of available Telegram commands displayed in the bot menu.

  ```yaml theme={null}
  telegramCommands:
    - command: status
      description: Check agent health and current activity
    - command: queue
      description: View pending and active tasks
    - command: cancel
      description: Cancel the current running task
    - command: reset
      description: Reset conversation context
    - command: models
      description: List available LLM models
    - command: help
      description: Show all available commands
  ```
</ParamField>

### Rich Features

OrcBot provides enhanced Telegram UX through specialized skills:

<CardGroup cols={2}>
  <Card title="Inline Buttons" icon="square-check">
    Send messages with interactive inline keyboard buttons.

    ```yaml theme={null}
    telegram_send_buttons(chatId, "Choose an option:", [["Yes", "No"]])
    ```
  </Card>

  <Card title="Polls" icon="chart-simple">
    Create native Telegram polls.

    ```yaml theme={null}
    telegram_send_poll(chatId, "Favorite color?", ["Red", "Blue", "Green"])
    ```
  </Card>

  <Card title="Reactions" icon="face-smile">
    React with emoji (falls back to reply if blocked).

    ```yaml theme={null}
    telegram_react(chatId, messageId, "👍")
    ```
  </Card>

  <Card title="Message Editing" icon="pen-to-square">
    Edit previously sent messages.

    ```yaml theme={null}
    telegram_edit_message(chatId, messageId, "Updated text")
    ```
  </Card>

  <Card title="Pin Messages" icon="thumbtack">
    Pin important messages in chats.

    ```yaml theme={null}
    telegram_pin_message(chatId, messageId)
    ```
  </Card>

  <Card title="Progress Indicators" icon="spinner">
    Show typing indicators during processing.

    ```yaml theme={null}
    progressFeedbackTypingOnly: true
    ```
  </Card>
</CardGroup>

### Example Configuration

```yaml orcbot.config.yaml theme={null}
# Telegram Configuration
telegramToken: 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
telegramAutoReplyEnabled: true

# Admin users
adminUsers:
  telegram:
    - "123456789"
    - "987654321"

# Autonomy settings
autonomyAllowedChannels:
  - telegram

# Progress feedback
progressFeedbackEnabled: true
progressFeedbackTypingOnly: true
```

## WhatsApp

### Basic Configuration

<ParamField path="whatsappEnabled" type="boolean" default={false}>
  Enable WhatsApp channel integration.

  **Policy:** LOCKED - Channel configuration affects system architecture.
</ParamField>

<ParamField path="whatsappSessionPath" type="string" default="~/.orcbot/whatsapp-session">
  Path to WhatsApp session storage directory (for Baileys multi-device).
</ParamField>

<ParamField path="whatsappAutoReplyEnabled" type="boolean" default={false}>
  Enable automatic replies to all WhatsApp messages.
</ParamField>

<ParamField path="whatsappOwnerJID" type="string">
  Owner JID for WhatsApp (format: `1234567890@s.whatsapp.net`).
</ParamField>

### Feature Flags

<ParamField path="whatsappStatusReplyEnabled" type="boolean" default={false}>
  Enable replies to WhatsApp status updates.
</ParamField>

<ParamField path="whatsappAutoReactEnabled" type="boolean" default={false}>
  Enable automatic reactions to messages.
</ParamField>

<ParamField path="whatsappContextProfilingEnabled" type="boolean" default={false}>
  Enable context profiling for better conversation understanding.
</ParamField>

### Getting Started

<Steps>
  <Step title="Enable WhatsApp">
    ```yaml orcbot.config.yaml theme={null}
    whatsappEnabled: true
    whatsappAutoReplyEnabled: true
    ```
  </Step>

  <Step title="Start OrcBot">
    ```bash theme={null}
    orcbot run
    ```

    A QR code will be displayed in the terminal.
  </Step>

  <Step title="Scan QR code">
    1. Open WhatsApp on your phone
    2. Go to Settings → Linked Devices
    3. Tap "Link a Device"
    4. Scan the QR code shown in the terminal
  </Step>

  <Step title="Find your JID">
    Send a message to the bot, then check logs for your JID (format: `1234567890@s.whatsapp.net`).
  </Step>

  <Step title="Set owner and admins">
    ```yaml orcbot.config.yaml theme={null}
    whatsappOwnerJID: 1234567890@s.whatsapp.net

    adminUsers:
      whatsapp:
        - "1234567890@s.whatsapp.net"
    ```
  </Step>
</Steps>

### Multi-Modal Support

WhatsApp channels support:

* **Text messages** - Standard text communication
* **Voice notes** - Send TTS-generated voice messages
* **Images** - Send and analyze images
* **Documents** - Send files and documents
* **Reactions** - React to messages with emoji

### Example Configuration

```yaml orcbot.config.yaml theme={null}
# WhatsApp Configuration
whatsappEnabled: true
whatsappAutoReplyEnabled: true
whatsappSessionPath: ~/.orcbot/whatsapp-session
whatsappOwnerJID: 1234567890@s.whatsapp.net
whatsappStatusReplyEnabled: false
whatsappAutoReactEnabled: true
whatsappContextProfilingEnabled: true

# Admin users
adminUsers:
  whatsapp:
    - "1234567890@s.whatsapp.net"

# Autonomy
autonomyAllowedChannels:
  - whatsapp
```

<Warning>
  WhatsApp uses the Baileys library which requires a persistent session. Do not delete the `whatsappSessionPath` directory or you'll need to re-link the device.
</Warning>

## Discord

### Basic Configuration

<ParamField path="discordToken" type="string">
  Discord bot token obtained from the Discord Developer Portal.

  **Policy:** LOCKED - Critical authentication credential.

  **Environment variable:** `DISCORD_TOKEN`
</ParamField>

<ParamField path="discordAutoReplyEnabled" type="boolean" default={false}>
  Enable automatic replies to all messages (not just mentions).
</ParamField>

### Getting Started

<Steps>
  <Step title="Create Discord application">
    1. Go to [Discord Developer Portal](https://discord.com/developers/applications)
    2. Click "New Application"
    3. Name your bot and create it
  </Step>

  <Step title="Create bot user">
    1. Go to the "Bot" section
    2. Click "Add Bot"
    3. Enable these Privileged Gateway Intents:
       * **Presence Intent**
       * **Server Members Intent**
       * **Message Content Intent** (required)
  </Step>

  <Step title="Get bot token">
    Under the "Bot" section, click "Reset Token" and copy the token.
  </Step>

  <Step title="Configure OrcBot">
    ```yaml orcbot.config.yaml theme={null}
    discordToken: MTIzNDU2Nzg5MDEyMzQ1Njc4OQ.GaBcDe.FgHiJkLmNoPqRsTuVwXyZ123456789
    discordAutoReplyEnabled: true
    ```

    Or use environment variable:

    ```bash .env theme={null}
    DISCORD_TOKEN=MTIzNDU2Nzg5MDEyMzQ1Njc4OQ.GaBcDe.FgHiJkLmNoPqRsTuVwXyZ123456789
    ```
  </Step>

  <Step title="Invite bot to server">
    1. Go to "OAuth2" → "URL Generator"
    2. Select scopes: `bot`, `applications.commands`
    3. Select permissions: `Send Messages`, `Read Messages`, `Attach Files`
    4. Copy the generated URL and open it to invite the bot
  </Step>

  <Step title="Find your user ID">
    1. Enable Developer Mode in Discord (Settings → Advanced)
    2. Right-click your username and select "Copy User ID"
  </Step>

  <Step title="Add yourself as admin">
    ```yaml orcbot.config.yaml theme={null}
    adminUsers:
      discord:
        - "123456789012345678"
    ```
  </Step>
</Steps>

### Example Configuration

```yaml orcbot.config.yaml theme={null}
# Discord Configuration
discordToken: MTIzNDU2Nzg5MDEyMzQ1Njc4OQ.GaBcDe.FgHiJkLmNoPqRsTuVwXyZ123456789
discordAutoReplyEnabled: true

# Admin users
adminUsers:
  discord:
    - "123456789012345678"

# Autonomy
autonomyAllowedChannels:
  - discord
```

<Warning>
  **Message Content Intent is required.** Without it, the bot cannot read message content. Enable it in the Discord Developer Portal under Bot → Privileged Gateway Intents.
</Warning>

## Slack

### Basic Configuration

<ParamField path="slackBotToken" type="string">
  Slack bot token (starts with `xoxb-`).

  **Policy:** LOCKED - Critical authentication credential.

  **Environment variable:** `SLACK_BOT_TOKEN`
</ParamField>

<ParamField path="slackAppToken" type="string">
  Slack app-level token for Socket Mode (starts with `xapp-`).

  **Policy:** LOCKED - Critical authentication credential.

  **Environment variable:** `SLACK_APP_TOKEN`
</ParamField>

<ParamField path="slackSigningSecret" type="string">
  Slack signing secret for webhook verification.

  **Policy:** LOCKED - Critical authentication credential.

  **Environment variable:** `SLACK_SIGNING_SECRET`
</ParamField>

<ParamField path="slackAutoReplyEnabled" type="boolean" default={false}>
  Enable automatic replies to all messages (not just mentions).
</ParamField>

### Getting Started

<Steps>
  <Step title="Create Slack app">
    1. Go to [Slack API](https://api.slack.com/apps)
    2. Click "Create New App" → "From scratch"
    3. Name your app and select a workspace
  </Step>

  <Step title="Enable Socket Mode">
    1. Go to "Socket Mode" in the sidebar
    2. Enable Socket Mode
    3. Generate an app-level token with `connections:write` scope
    4. Copy the token (starts with `xapp-`)
  </Step>

  <Step title="Configure bot scopes">
    Go to "OAuth & Permissions" → "Scopes" and add:

    * `chat:write` - Send messages
    * `channels:read` - View channels
    * `channels:history` - Read messages in public channels
    * `groups:history` - Read messages in private channels
    * `im:history` - Read direct messages
    * `mpim:history` - Read group messages
    * `users:read` - View users
    * `files:write` - Upload files
  </Step>

  <Step title="Enable event subscriptions">
    1. Go to "Event Subscriptions"
    2. Enable events
    3. Subscribe to bot events:
       * `message.channels`
       * `message.groups`
       * `message.im`
       * `message.mpim`
  </Step>

  <Step title="Install to workspace">
    1. Go to "Install App"
    2. Click "Install to Workspace"
    3. Copy the Bot User OAuth Token (starts with `xoxb-`)
  </Step>

  <Step title="Get signing secret">
    Go to "Basic Information" → "App Credentials" and copy the Signing Secret.
  </Step>

  <Step title="Configure OrcBot">
    ```yaml orcbot.config.yaml theme={null}
    slackBotToken: xoxb-your-bot-token
    slackAppToken: xapp-your-app-token
    slackSigningSecret: your-signing-secret
    slackAutoReplyEnabled: true
    ```

    Or use environment variables:

    ```bash .env theme={null}
    SLACK_BOT_TOKEN=xoxb-your-bot-token
    SLACK_APP_TOKEN=xapp-your-app-token
    SLACK_SIGNING_SECRET=your-signing-secret
    ```
  </Step>

  <Step title="Find your user ID">
    1. Click on your profile in Slack
    2. Click "More" → "Copy member ID"
  </Step>

  <Step title="Add yourself as admin">
    ```yaml orcbot.config.yaml theme={null}
    adminUsers:
      slack:
        - "U0123456789"
    ```
  </Step>
</Steps>

### Example Configuration

```yaml orcbot.config.yaml theme={null}
# Slack Configuration
slackBotToken: xoxb-1234567890-1234567890-abcdefghijklmnopqrstuvwx
slackAppToken: xapp-1-ABCD-1234567890-1234567890-abcdefghijklmnopqrstuvwxyz
slackSigningSecret: 1234567890abcdefghijklmnopqrstuv
slackAutoReplyEnabled: true

# Admin users
adminUsers:
  slack:
    - "U0123456789"

# Autonomy
autonomyAllowedChannels:
  - slack
```

<Note>
  OrcBot uses Socket Mode for Slack, which doesn't require exposing a public endpoint. This makes it easier to run behind firewalls.
</Note>

## Email

### Basic Configuration

<ParamField path="emailEnabled" type="boolean" default={false}>
  Enable email channel integration (SMTP + IMAP).
</ParamField>

<ParamField path="emailAutoReplyEnabled" type="boolean" default={false}>
  Enable automatic replies to incoming emails.
</ParamField>

<ParamField path="emailAddress" type="string">
  Email address for the bot.

  **Environment variable:** `EMAIL_ADDRESS`
</ParamField>

<ParamField path="emailFromName" type="string">
  Display name for outgoing emails.
</ParamField>

<ParamField path="emailDefaultSubject" type="string" default="OrcBot response">
  Default subject line for outgoing emails.
</ParamField>

<ParamField path="emailSocketTimeoutMs" type="number" default={15000}>
  Socket timeout for email operations in milliseconds.

  **Environment variable:** `EMAIL_SOCKET_TIMEOUT_MS`
</ParamField>

### SMTP Configuration (Sending)

<ParamField path="smtpHost" type="string">
  SMTP server hostname (e.g., `smtp.gmail.com`).

  **Environment variable:** `SMTP_HOST`
</ParamField>

<ParamField path="smtpPort" type="number" default={587}>
  SMTP server port (587 for TLS, 465 for SSL).

  **Environment variable:** `SMTP_PORT`
</ParamField>

<ParamField path="smtpSecure" type="boolean" default={false}>
  Use SSL/TLS for SMTP connection (port 465).

  **Environment variable:** `SMTP_SECURE`
</ParamField>

<ParamField path="smtpStartTls" type="boolean" default={true}>
  Use STARTTLS for SMTP connection (port 587).

  **Environment variable:** `SMTP_STARTTLS`
</ParamField>

<ParamField path="smtpUsername" type="string">
  SMTP authentication username.

  **Environment variable:** `SMTP_USERNAME`
</ParamField>

<ParamField path="smtpPassword" type="string">
  SMTP authentication password.

  **Environment variable:** `SMTP_PASSWORD`
</ParamField>

### IMAP Configuration (Receiving)

<ParamField path="imapHost" type="string">
  IMAP server hostname (e.g., `imap.gmail.com`).

  **Environment variable:** `IMAP_HOST`
</ParamField>

<ParamField path="imapPort" type="number" default={993}>
  IMAP server port (993 for SSL).

  **Environment variable:** `IMAP_PORT`
</ParamField>

<ParamField path="imapSecure" type="boolean" default={true}>
  Use SSL for IMAP connection.

  **Environment variable:** `IMAP_SECURE`
</ParamField>

<ParamField path="imapUsername" type="string">
  IMAP authentication username.

  **Environment variable:** `IMAP_USERNAME`
</ParamField>

<ParamField path="imapPassword" type="string">
  IMAP authentication password.

  **Environment variable:** `IMAP_PASSWORD`
</ParamField>

### Example Configuration (Gmail)

<Steps>
  <Step title="Create app password">
    1. Go to [Google Account Security](https://myaccount.google.com/security)
    2. Enable 2-Step Verification if not already enabled
    3. Go to "App passwords"
    4. Generate a new app password for "Mail"
  </Step>

  <Step title="Configure OrcBot">
    ```yaml orcbot.config.yaml theme={null}
    # Email Configuration
    emailEnabled: true
    emailAutoReplyEnabled: true
    emailAddress: yourbot@gmail.com
    emailFromName: OrcBot

    # SMTP (Sending)
    smtpHost: smtp.gmail.com
    smtpPort: 587
    smtpStartTls: true
    smtpUsername: yourbot@gmail.com
    smtpPassword: your-app-password

    # IMAP (Receiving)
    imapHost: imap.gmail.com
    imapPort: 993
    imapSecure: true
    imapUsername: yourbot@gmail.com
    imapPassword: your-app-password
    ```

    Or use environment variables:

    ```bash .env theme={null}
    EMAIL_ADDRESS=yourbot@gmail.com
    SMTP_HOST=smtp.gmail.com
    SMTP_USERNAME=yourbot@gmail.com
    SMTP_PASSWORD=your-app-password
    IMAP_HOST=imap.gmail.com
    IMAP_USERNAME=yourbot@gmail.com
    IMAP_PASSWORD=your-app-password
    ```
  </Step>

  <Step title="Add admins">
    ```yaml orcbot.config.yaml theme={null}
    adminUsers:
      email:
        - "admin@example.com"
    ```
  </Step>
</Steps>

<Warning>
  **Use app-specific passwords.** Most email providers require app-specific passwords for third-party applications. Do not use your main account password.
</Warning>

## Admin Permissions

<ParamField path="adminUsers" type="object">
  Per-channel admin user allowlists. Admins have access to elevated commands and skills.

  **Policy:** LOCKED - Security-critical configuration.

  ```yaml theme={null}
  adminUsers:
    telegram:
      - "123456789"
      - "987654321"
    whatsapp:
      - "1234567890@s.whatsapp.net"
    discord:
      - "123456789012345678"
    slack:
      - "U0123456789"
    email:
      - "admin@example.com"
  ```
</ParamField>

### Admin-Only Skills

These skills require admin privileges:

* `run_command` - Execute shell commands
* `create_custom_skill` - Create executable plugins
* `manage_config` - Modify configuration
* `spawn_agent` - Create worker agents
* `delegate_task` - Orchestrate tasks
* `system_check` - Verify system dependencies
* `self_repair_skill` - Repair broken plugins

<Note>
  Admin status is checked per-channel. A user who is admin on Telegram is not automatically admin on Discord.
</Note>

## Multi-Channel Strategy

Configure multiple channels simultaneously:

```yaml orcbot.config.yaml theme={null}
# All channels enabled
telegramToken: your-telegram-token
telegramAutoReplyEnabled: true

whatsappEnabled: true
whatsappAutoReplyEnabled: true

discordToken: your-discord-token
discordAutoReplyEnabled: true

slackBotToken: your-slack-bot-token
slackAppToken: your-slack-app-token
slackSigningSecret: your-signing-secret
slackAutoReplyEnabled: true

emailEnabled: true
emailAutoReplyEnabled: false  # Email usually needs explicit replies

# Per-channel admins
adminUsers:
  telegram: ["123456789"]
  whatsapp: ["1234567890@s.whatsapp.net"]
  discord: ["123456789012345678"]
  slack: ["U0123456789"]
  email: ["admin@example.com"]

# Autonomy on select channels
autonomyAllowedChannels:
  - telegram
  - discord
```

## Session Scope

<ParamField path="sessionScope" type="enum" default="per-channel-peer">
  Conversation session isolation:

  * `main` - Single global session (all users share memory)
  * `per-peer` - Separate session per user (user's Telegram and Discord are same session)
  * `per-channel-peer` - Separate session per channel-user (user's Telegram and Discord are different sessions)

  ```yaml theme={null}
  sessionScope: per-channel-peer  # Recommended for privacy
  ```
</ParamField>

## Identity Linking

<ParamField path="identityLinks" type="object" default={{}}>
  Link user identities across channels so the agent recognizes the same person.

  ```yaml theme={null}
  identityLinks:
    telegram:123456789: whatsapp:1234567890@s.whatsapp.net
    discord:987654321: telegram:123456789
    slack:U0123456789: email:admin@example.com
  ```

  This allows:

  * Shared user profile across channels
  * Consistent conversation context
  * Cross-channel admin permissions
</ParamField>

<Note>
  Identity linking is useful when `sessionScope: per-peer` but you want specific users to be recognized across channels.
</Note>