Channel Configuration

Overview

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

Basic Configuration

string

Telegram bot token obtained from @BotFather.Policy: LOCKED - Critical authentication credential.Environment variable: TELEGRAM_TOKEN

boolean

default:false

Enable automatic replies to all messages without requiring /commands.

Getting Started

Create a bot with BotFather

Open Telegram and search for @BotFather
Send /newbot and follow the prompts
Copy the bot token provided

Configure OrcBot

orcbot.config.yaml

telegramToken: 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
telegramAutoReplyEnabled: true

Or use environment variable:

.env

TELEGRAM_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

Start the bot

orcbot run

Find your user ID

Send a message to your bot, then check logs or use the /admin command to see your Telegram user ID.

Add yourself as admin

orcbot.config.yaml

adminUsers:
  telegram:
    - "123456789"  # Your Telegram user ID

Commands

array

List of available Telegram commands displayed in the bot menu.

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

Rich Features

OrcBot provides enhanced Telegram UX through specialized skills:

Inline Buttons

Send messages with interactive inline keyboard buttons.

telegram_send_buttons(chatId, "Choose an option:", [["Yes", "No"]])

Polls

Create native Telegram polls.

telegram_send_poll(chatId, "Favorite color?", ["Red", "Blue", "Green"])

Reactions

React with emoji (falls back to reply if blocked).

telegram_react(chatId, messageId, "👍")

Message Editing

Edit previously sent messages.

telegram_edit_message(chatId, messageId, "Updated text")

Pin Messages

Pin important messages in chats.

telegram_pin_message(chatId, messageId)

Progress Indicators

Show typing indicators during processing.

progressFeedbackTypingOnly: true

Example Configuration

orcbot.config.yaml

# 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

Basic Configuration

boolean

default:false

Enable WhatsApp channel integration.Policy: LOCKED - Channel configuration affects system architecture.

string

default:"~/.orcbot/whatsapp-session"

Path to WhatsApp session storage directory (for Baileys multi-device).

boolean

default:false

Enable automatic replies to all WhatsApp messages.

string

Owner JID for WhatsApp (format: 1234567890@s.whatsapp.net).

Feature Flags

boolean

default:false

Enable replies to WhatsApp status updates.

boolean

default:false

Enable automatic reactions to messages.

boolean

default:false

Enable context profiling for better conversation understanding.

Getting Started

Enable WhatsApp

orcbot.config.yaml

whatsappEnabled: true
whatsappAutoReplyEnabled: true

Start OrcBot

orcbot run

A QR code will be displayed in the terminal.

Scan QR code

Open WhatsApp on your phone
Go to Settings → Linked Devices
Tap “Link a Device”
Scan the QR code shown in the terminal

Find your JID

Send a message to the bot, then check logs for your JID (format: 1234567890@s.whatsapp.net).

Set owner and admins

orcbot.config.yaml

whatsappOwnerJID: 1234567890@s.whatsapp.net

adminUsers:
  whatsapp:
    - "1234567890@s.whatsapp.net"

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

orcbot.config.yaml

# 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

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.

Discord

Basic Configuration

string

Discord bot token obtained from the Discord Developer Portal.Policy: LOCKED - Critical authentication credential.Environment variable: DISCORD_TOKEN

boolean

default:false

Enable automatic replies to all messages (not just mentions).

Getting Started

Create Discord application

Go to Discord Developer Portal
Click “New Application”
Name your bot and create it

Create bot user

Go to the “Bot” section
Click “Add Bot”
Enable these Privileged Gateway Intents:
- Presence Intent
- Server Members Intent
- Message Content Intent (required)

Get bot token

Under the “Bot” section, click “Reset Token” and copy the token.

Configure OrcBot

orcbot.config.yaml

discordToken: MTIzNDU2Nzg5MDEyMzQ1Njc4OQ.GaBcDe.FgHiJkLmNoPqRsTuVwXyZ123456789
discordAutoReplyEnabled: true

Or use environment variable:

.env

DISCORD_TOKEN=MTIzNDU2Nzg5MDEyMzQ1Njc4OQ.GaBcDe.FgHiJkLmNoPqRsTuVwXyZ123456789

Invite bot to server

Go to “OAuth2” → “URL Generator”
Select scopes: bot, applications.commands
Select permissions: Send Messages, Read Messages, Attach Files
Copy the generated URL and open it to invite the bot

Find your user ID

Enable Developer Mode in Discord (Settings → Advanced)
Right-click your username and select “Copy User ID”

Add yourself as admin

orcbot.config.yaml

adminUsers:
  discord:
    - "123456789012345678"

Example Configuration

orcbot.config.yaml

# Discord Configuration
discordToken: MTIzNDU2Nzg5MDEyMzQ1Njc4OQ.GaBcDe.FgHiJkLmNoPqRsTuVwXyZ123456789
discordAutoReplyEnabled: true

# Admin users
adminUsers:
  discord:
    - "123456789012345678"

# Autonomy
autonomyAllowedChannels:
  - discord

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.

Slack

Basic Configuration

string

Slack bot token (starts with xoxb-).Policy: LOCKED - Critical authentication credential.Environment variable: SLACK_BOT_TOKEN

string

Slack app-level token for Socket Mode (starts with xapp-).Policy: LOCKED - Critical authentication credential.Environment variable: SLACK_APP_TOKEN

string

Slack signing secret for webhook verification.Policy: LOCKED - Critical authentication credential.Environment variable: SLACK_SIGNING_SECRET

boolean

default:false

Enable automatic replies to all messages (not just mentions).

Getting Started

Create Slack app

Go to Slack API
Click “Create New App” → “From scratch”
Name your app and select a workspace

Enable Socket Mode

Go to “Socket Mode” in the sidebar
Enable Socket Mode
Generate an app-level token with connections:write scope
Copy the token (starts with xapp-)

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

Enable event subscriptions

Go to “Event Subscriptions”
Enable events
Subscribe to bot events:
- message.channels
- message.groups
- message.im
- message.mpim

Install to workspace

Go to “Install App”
Click “Install to Workspace”
Copy the Bot User OAuth Token (starts with xoxb-)

Get signing secret

Go to “Basic Information” → “App Credentials” and copy the Signing Secret.

Configure OrcBot

orcbot.config.yaml

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

Or use environment variables:

.env

SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_APP_TOKEN=xapp-your-app-token
SLACK_SIGNING_SECRET=your-signing-secret

Find your user ID

Click on your profile in Slack
Click “More” → “Copy member ID”

Add yourself as admin

orcbot.config.yaml

adminUsers:
  slack:
    - "U0123456789"

Example Configuration

orcbot.config.yaml

# 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

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

Email

Basic Configuration

boolean

default:false

Enable email channel integration (SMTP + IMAP).

boolean

default:false

Enable automatic replies to incoming emails.

string

Email address for the bot.Environment variable: EMAIL_ADDRESS

string

Display name for outgoing emails.

string

default:"OrcBot response"

Default subject line for outgoing emails.

number

default:15000

Socket timeout for email operations in milliseconds.Environment variable: EMAIL_SOCKET_TIMEOUT_MS

SMTP Configuration (Sending)

string

SMTP server hostname (e.g., smtp.gmail.com).Environment variable: SMTP_HOST

number

default:587

SMTP server port (587 for TLS, 465 for SSL).Environment variable: SMTP_PORT

boolean

default:false

Use SSL/TLS for SMTP connection (port 465).Environment variable: SMTP_SECURE

boolean

default:true

Use STARTTLS for SMTP connection (port 587).Environment variable: SMTP_STARTTLS

string

SMTP authentication username.Environment variable: SMTP_USERNAME

string

SMTP authentication password.Environment variable: SMTP_PASSWORD

IMAP Configuration (Receiving)

string

IMAP server hostname (e.g., imap.gmail.com).Environment variable: IMAP_HOST

number

default:993

IMAP server port (993 for SSL).Environment variable: IMAP_PORT

boolean

default:true

Use SSL for IMAP connection.Environment variable: IMAP_SECURE

string

IMAP authentication username.Environment variable: IMAP_USERNAME

string

IMAP authentication password.Environment variable: IMAP_PASSWORD

Example Configuration (Gmail)

Create app password

Go to Google Account Security
Enable 2-Step Verification if not already enabled
Go to “App passwords”
Generate a new app password for “Mail”

Configure OrcBot

orcbot.config.yaml

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

.env

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

Add admins

orcbot.config.yaml

adminUsers:
  email:
    - "admin@example.com"

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

Admin Permissions

object

Per-channel admin user allowlists. Admins have access to elevated commands and skills.Policy: LOCKED - Security-critical configuration.

adminUsers:
  telegram:
    - "123456789"
    - "987654321"
  whatsapp:
    - "1234567890@s.whatsapp.net"
  discord:
    - "123456789012345678"
  slack:
    - "U0123456789"
  email:
    - "admin@example.com"

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

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

Multi-Channel Strategy

Configure multiple channels simultaneously:

orcbot.config.yaml

# 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

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)

sessionScope: per-channel-peer  # Recommended for privacy

Identity Linking

object

default:{}

Link user identities across channels so the agent recognizes the same person.

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

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

CLI Commands

Core Skills

Configuration

Channel Configuration

Overview

Telegram

Basic Configuration

Getting Started

Commands

Rich Features

Inline Buttons

Polls

Reactions

Message Editing

Pin Messages

Progress Indicators

Example Configuration

WhatsApp

Basic Configuration

Feature Flags

Getting Started

Example Configuration

Discord

Basic Configuration

Getting Started

Example Configuration

Slack

Basic Configuration

Getting Started

Example Configuration

Email

Basic Configuration

SMTP Configuration (Sending)

IMAP Configuration (Receiving)

Example Configuration (Gmail)

Admin Permissions

Admin-Only Skills

Multi-Channel Strategy

Session Scope

Identity Linking

Overview

Telegram

Basic Configuration

Getting Started

Commands

Rich Features

Inline Buttons

Polls

Reactions

Message Editing

Pin Messages

Progress Indicators

Example Configuration

WhatsApp

Basic Configuration

Feature Flags

Getting Started

Multi-Modal Support

Example Configuration

Discord

Basic Configuration

Getting Started

Example Configuration

Slack

Basic Configuration

Getting Started

Example Configuration

Email

Basic Configuration

SMTP Configuration (Sending)

IMAP Configuration (Receiving)

Example Configuration (Gmail)

Admin Permissions

Admin-Only Skills

Multi-Channel Strategy

Session Scope

Identity Linking