Bot CLI

Deploy AI agents to messaging platforms via CLI

Start messaging bots with a single command. Supports Telegram, Discord, Slack, WhatsApp, Linear, Email, and AgentMail with full capability options.

Warning

praisonai bot is a wrapper-required command. It is only available when the full praisonai package is installed:

bash

pip install praisonai

If you installed only praisonai-code, this command will not appear in --help and will fail at dispatch time. See Package Structure for the six-package install model.

Quick Start

bash

# Telegram
praisonai bot telegram --token $TELEGRAM_BOT_TOKEN

# Discord
praisonai bot discord --token $DISCORD_BOT_TOKEN

# Slack (requires both tokens)
praisonai bot slack --token $SLACK_BOT_TOKEN --app-token $SLACK_APP_TOKEN

# WhatsApp Cloud API
praisonai bot whatsapp --token $WHATSAPP_ACCESS_TOKEN --phone-id $WHATSAPP_PHONE_NUMBER_ID

# WhatsApp Web Mode (no tokens needed — scan QR code)
praisonai bot whatsapp --mode web

# Linear (AgentSession webhooks)
praisonai bot linear --token $LINEAR_OAUTH_TOKEN --signing-secret $LINEAR_WEBHOOK_SECRET

# Email (IMAP/SMTP)
praisonai bot email --token $EMAIL_APP_PASSWORD --email user@gmail.com

# AgentMail (API-first, zero IMAP/SMTP config)
praisonai bot agentmail --token $AGENTMAIL_API_KEY

Command Reference

bash

praisonai bot <platform> [OPTIONS]

Platforms

Platform	Required Tokens
`telegram`	`--token`
`discord`	`--token`
`slack`	`--token` + `--app-token`
`whatsapp`	`--token` + `--phone-id` (Cloud API) or `--mode web` (no tokens)
`linear`	`--token` + `--signing-secret`
`email`	`--token` (App Password) + `--email`
`agentmail`	`--token` (API key)

Capability Options

Enable agent capabilities via CLI flags:

Model & Agent

Option	Description
`--agent FILE`	Agent YAML configuration file
`--model`, `-m MODEL`	LLM model (e.g., `gpt-4o`, `claude-sonnet-4-20250514`, `gemini/gemini-2.0-flash`). When `--browser` is enabled, this same model drives the browser tool’s internal decisions (defaults to `gpt-4o-mini` if omitted).
`--thinking MODE`	Thinking mode: `off`, `minimal`, `low`, `medium`, `high`

Browser

--browser prefers a local Playwright browser (no cloud API key) and falls back to the cloud BrowserBaseTool only when the local browser is unavailable.

Option	Description
`--browser`	Enable the browser tool. Prefers local Playwright automation; falls back to cloud.
`--browser-profile NAME`	Browser profile name (default: `default`). Currently accepted but not applied — the local Playwright agent uses a fresh context.
`--browser-headless`	Run the local Chromium without a visible window.

Note

Local automation needs the Playwright extra and a Chromium download:

bash

pip install "praisonai-browser[playwright]"
playwright install chromium

This playwright install chromium step is required — no browsers are downloaded automatically by pip install in any tier.

Without those, --browser falls back to the cloud BrowserBaseTool (which needs BrowserBase credentials), or — if neither is installed — becomes a no-op with a startup warning. See Bot Browser Automation for details.

Web Search

Option	Description
`--web`	Enable web search with provider-specific tools
`--web-provider PROVIDER`	Search provider: `duckduckgo`, `tavily`, `serper`

Tools & Skills

Option	Description
`--tools TOOL...`	Enable additional tools by name (e.g., `DuckDuckGoTool WikipediaTool`)
`--skills SKILL...`	Enable specific skills
`--skills-dir DIR`	Custom skills directory path

Memory & Knowledge

Option	Description
`--memory`	Enable persistent memory
`--memory-provider PROVIDER`	Memory provider (default: `default`)
`--knowledge`	Enable knowledge/RAG
`--knowledge-sources SOURCE...`	Knowledge sources to load
`--session-id ID`	Session ID for conversation continuity
`--user-id ID`	User ID for memory isolation

Execution

Option	Description
`--sandbox`	Enable sandbox execution mode
`--exec`	Enable exec tool explicitly
`--auto-approve`	Auto-approve all tool executions (skip confirmation prompts)

WhatsApp-Specific

Option	Description
`--mode MODE`	Connection mode: `cloud` (default) or `web` (QR code, no tokens)
`--phone-id ID`	WhatsApp Phone Number ID (Cloud API)
`--verify-token TOKEN`	Webhook verify token (Cloud API)
`--respond-to NUMBERS`	Allowlist phone numbers (Web mode, comma-separated)
`--respond-to-groups GROUPS`	Allowlist group JIDs (Web mode, comma-separated)
`--respond-to-all`	Respond to all messages (Web mode, default: self-chat only)
`--creds-dir DIR`	Custom credentials directory (Web mode, default: `~/.praisonai/whatsapp/`)

Email-Specific

Option	Description
`--email ADDRESS`	Bot email address (or `EMAIL_ADDRESS` env var)
`--imap-server HOST`	IMAP server (default: auto-detected from email domain)
`--smtp-server HOST`	SMTP server (default: auto-detected from email domain)

Linear-Specific

Option	Description
`--signing-secret SECRET`	Linear webhook signing secret (or `LINEAR_WEBHOOK_SECRET`)
`--port PORT`	Webhook server port (default: `8080`)

AgentMail-Specific

Option	Description
`--mode MODE`	Reception mode: `poll` (default), `ws`, `webhook`, `hybrid`
`--inbox INBOX_ID`	Existing inbox to connect to (or `AGENTMAIL_INBOX_ID`)
`--domain DOMAIN`	Custom domain for new inboxes (or `AGENTMAIL_DOMAIN`)

Audio (TTS/STT)

Option	Description
`--tts`	Enable TTS tool for text-to-speech
`--tts-voice VOICE`	TTS voice: `alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`
`--tts-model MODEL`	TTS model (default: `openai/tts-1`)
`--auto-tts`	Auto-convert all responses to speech
`--stt`	Enable STT tool for speech-to-text
`--stt-model MODEL`	STT model (default: `openai/whisper-1`)

Streaming (progressive replies)

Option	Description
`--stream`	Enable progressive streaming responses (bot edits the message live as tokens arrive)
`--stream-edit-interval MS`	Minimum interval between edits in milliseconds (default: `700`)

Examples

Basic Bot

bash

praisonai bot telegram --token $TELEGRAM_BOT_TOKEN

With Custom Agent

bash

praisonai bot slack --token $SLACK_BOT_TOKEN --app-token $SLACK_APP_TOKEN --agent agents.yaml

agents.yaml:

yaml

name: support-bot
instructions: |
  You are a customer support assistant.
  Be helpful and concise.
llm: gpt-4o-mini
tools:
  - search_web

With Full Capabilities

bash

praisonai bot telegram --token $TOKEN \
  --agent agents.yaml \
  --browser \
  --web \
  --memory \
  --model gpt-4o

With Specific Tools

bash

praisonai bot discord --token $TOKEN \
  --tools DuckDuckGoTool WikipediaTool GitHubTool

With Knowledge Base

bash

praisonai bot slack --token $SLACK_BOT_TOKEN --app-token $SLACK_APP_TOKEN \
  --knowledge \
  --memory

With Auto-Approve (Trusted Environment)

bash

# Auto-approve all tool executions - useful for trusted environments
praisonai bot slack --token $SLACK_BOT_TOKEN --app-token $SLACK_APP_TOKEN \
  --auto-approve \
  --exec \
  --web

With Live Streaming Replies

bash

# Default streaming (edits every 700ms)
praisonai bot telegram --token $TELEGRAM_BOT_TOKEN --stream

# Slower edits for stricter rate limits
praisonai bot telegram --token $TELEGRAM_BOT_TOKEN \
  --stream \
  --stream-edit-interval 1500

With TTS/STT (Voice)

bash

# Enable TTS tool - agent can convert text to speech
praisonai bot telegram --token $TOKEN --tts

# Auto-convert all responses to speech
praisonai bot telegram --token $TOKEN --auto-tts --tts-voice nova

# Full voice capabilities
praisonai bot telegram --token $TOKEN --tts --stt --memory

WhatsApp Cloud API

bash

# Cloud API mode (requires Meta developer account)
praisonai bot whatsapp --token $WHATSAPP_ACCESS_TOKEN --phone-id $WHATSAPP_PHONE_NUMBER_ID

WhatsApp Web Mode

bash

# Web mode — scan QR code, no tokens needed
praisonai bot whatsapp --mode web

# With specific allowed contacts
praisonai bot whatsapp --mode web --respond-to 1234567890,9876543210

# With memory and web search
praisonai bot whatsapp --mode web --memory --web

Email Bot

bash

# IMAP/SMTP email bot
praisonai bot email --token $EMAIL_APP_PASSWORD --email bot@gmail.com

# With memory and web search
praisonai bot email --token $EMAIL_APP_PASSWORD --email bot@gmail.com --memory --web

AgentMail Bot

bash

# API-first email (auto-creates inbox)
praisonai bot agentmail --token $AGENTMAIL_API_KEY

# With specific inbox
praisonai bot agentmail --token $AGENTMAIL_API_KEY --inbox you@agentmail.to

# With custom domain
praisonai bot agentmail --token $AGENTMAIL_API_KEY --domain mycompany.com

# WebSocket mode (sub-second latency)
praisonai bot agentmail --token $AGENTMAIL_API_KEY --mode ws

# Hybrid mode (recommended for production)
praisonai bot agentmail --token $AGENTMAIL_API_KEY --mode hybrid

Environment Variables

Variable	Description
`TELEGRAM_BOT_TOKEN`	Telegram bot token from @BotFather
`DISCORD_BOT_TOKEN`	Discord bot token
`SLACK_BOT_TOKEN`	Slack Bot User OAuth Token (`xoxb-...`)
`SLACK_APP_TOKEN`	Slack App-Level Token (`xapp-...`)
`WHATSAPP_ACCESS_TOKEN`	WhatsApp Cloud API access token
`WHATSAPP_PHONE_NUMBER_ID`	WhatsApp Business phone number ID
`WHATSAPP_VERIFY_TOKEN`	Webhook verification token (any secret string)
`WHATSAPP_CREDS_DIR`	Custom credentials directory for Web mode
`EMAIL_ADDRESS`	Email bot address
`EMAIL_APP_PASSWORD`	Email App Password
`EMAIL_IMAP_SERVER`	IMAP server (auto-detected by default)
`EMAIL_SMTP_SERVER`	SMTP server (auto-detected by default)
`AGENTMAIL_API_KEY`	AgentMail API key
`AGENTMAIL_INBOX_ID`	AgentMail inbox to connect to
`AGENTMAIL_DOMAIN`	Custom domain for new AgentMail inboxes
`OPENAI_API_KEY`	OpenAI API key for LLM

Agent YAML Schema

yaml

name: my-bot
instructions: |
  You are a helpful assistant.
  Be concise and friendly.
llm: gpt-4o-mini
tools:
  - search_web
  - DuckDuckGoTool
memory: true
knowledge:
  - ./docs/

Troubleshooting

Diagram

409 Conflict — bot stops replying

Symptom. The bot starts, then messages stop being answered, or start-up exits with a non-zero code. Logs show:

[telegram] Another process is already polling this token
(only one instance per token is allowed).
Stop the other bot/gateway/UI-channel instance first.

Cause. A second poller (CLI bot telegram, a gateway telegram channel, Claw Channels, or an orphaned process) is using the same token. Telegram’s getUpdates API allows only one active consumer per bot token, so every extra poller receives HTTP 409 Conflict. The adapter fails fast on a confirmed 409 instead of silently looping.

Fix.

macOS / Linux

bash

# 1. Find every Python process that mentions praisonai
ps aux | grep -i praisonai | grep -v grep

# 2. Kill duplicates (replace <PID>)
kill <PID>

# 3. Confirm webhook is not set (long-polling mode)
curl "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getWebhookInfo"

# 4. Restart exactly one bot
praisonai bot telegram --token $TELEGRAM_BOT_TOKEN

Windows (PowerShell)

powershell

# 1. Find running Python processes
Get-Process python | Format-Table Id, CPU, StartTime -AutoSize

# 2. Stop all Python processes (careful — kills every python.exe)
Get-Process python -ErrorAction SilentlyContinue | Stop-Process -Force
Start-Sleep -Seconds 3

# 3. Restart exactly one bot
$env:TELEGRAM_BOT_TOKEN = "..."
praisonai bot telegram --token $env:TELEGRAM_BOT_TOKEN

Prevention.

Use one token per environment (dev / staging / prod).
Prefer webhook mode in production — multiple processes can share the same webhook target without conflict.
Don’t run praisonai bot telegram and Claw Channels against the same token at the same time.

Inspecting the outbound queue

Operator inspection of the durable outbound queue lives under praisonai gateway outbox …, not praisonai bot …. To list, retry, or purge stuck outbound replies, use the Outbox Operator CLI — praisonai gateway outbox list|stats|retry|purge. Inbound failures instead go through praisonai bot dlq … (see Inbound DLQ).

Messaging Bots

Full messaging bots documentation

Audio Tools

TTS and STT tools

Browser CLI

Browser control commands

Bot Browser Automation

Give a bot a local Playwright browser with --browser

Bot Streaming Replies

Progressive live replies with --stream

Bot vs Gateway

Choose the right deployment model

Outbox Operator CLI

Inspect, retry, and purge the outbound queue with praisonai gateway outbox

Bot CLI

Quick Start

Command Reference

Platforms

Capability Options

Model & Agent

Browser

Web Search

Tools & Skills

Memory & Knowledge

Execution

WhatsApp-Specific

Email-Specific

Linear-Specific

AgentMail-Specific

Audio (TTS/STT)

Streaming (progressive replies)

Examples

Basic Bot

With Custom Agent

With Full Capabilities

With Specific Tools

With Knowledge Base

With Auto-Approve (Trusted Environment)

With Live Streaming Replies

With TTS/STT (Voice)

WhatsApp Cloud API

WhatsApp Web Mode

Email Bot

AgentMail Bot

Environment Variables

Agent YAML Schema

Troubleshooting

409 Conflict — bot stops replying

macOS / Linux

Windows (PowerShell)

Inspecting the outbound queue

Related