Bot platform adapters now ship in the
praisonai-bot package. praisonai bot serve still works exactly as documented here; for a standalone install see praisonai-bot Migration.On Telegram and Discord, every command below appears in the native
/ autocomplete menu automatically. See Slash Command Menu.Command Picker
Every PraisonAI bot comes with built-in chat commands. Just type a command in your chat — no setup required.Built-in Commands
/status
Shows agent name, model, platform, and uptime.
/new
Resets the conversation session. Starts a fresh chat with the agent.
/stop
Cancels the current agent task. Requires run control to be enabled.
/sethome
Mark this chat as the platform home channel for scheduled deliveries.
/help
Lists all available commands (built-in + custom) with descriptions. Output is filtered to commands the caller is allowed to run.
/whoami
Shows your user ID, role, and the commands you are allowed to run.
/model
Switch the LLM model for this conversation (session-scoped).
/usage
Show token usage and estimated cost for this session.
/compress
Summarise older messages to free context window space.
/queue
Queue a follow-up message to run after the current task.
/learn
Distil a grounded skill from sources you describe (repo, docs, PDFs, or this chat). Privileged — admin-only by default when a policy is configured. Authored via
skill_manage with the same approval gate as other agent-created skills. See Learn a Skill from Sources and Command Access Control./undo
Undo the last turn’s file changes. Requires the agent to track changes (
autonomy with track_changes)./sessions
List the caller’s saved sessions/checkpoints. Scoped to the requesting user — never enumerates other users’ sessions.
/resume
Switch to a saved session:
/resume <id>. Use /sessions to list available IDs./retry
Re-run your last message through the normal chat path.
/reasoning
Toggle whether extended-thinking output is shown in this conversation (per user).
/automations
List pending automation suggestions with inline Accept/Dismiss buttons. Telegram only today.
/blueprint
Create an automation from a template:
/blueprint <name> [slot=value ...]. Telegram only today.Per-Command Access Control
Restrict which commands each user may run withadmin_users and user_allowed_commands on Telegram, Slack, and Discord — admins get full access, regular users only run commands you list. All built-in commands, including the new runtime controls, are gated by this policy.
Command Access Control
Admin users, per-command allowlists, and /whoami
Quick Start
1
Install PraisonAI
2
Set Your Bot Token
3
Start the Bot
4
Send a Command
Open your bot chat and type:You’ll see the agent name, model, platform, and uptime.
Platform Examples
Voice notes are transcribed automatically — see Voice Notes.
Command Details
/status
Shows current bot information:/whoami
Shows permission information for the caller:
Example output:
/new
Resets the conversation:- Clears all previous messages from the agent’s session
- Replies with a confirmation message
- Next message starts a completely new conversation
/stop
Cancels the current agent task immediately:- Immediately interrupts the current agent processing
- Clears any pending messages in the queue
- Replies with confirmation that the task was cancelled
- Next message starts a fresh task
/stop works out of the box on any bot using the default BotSessionManager — Telegram, Discord, Slack, and WhatsApp all register it. Enabling Bot Run Control with busy_mode adds mid-run interruption plus pending-message handling on top of basic cancellation./sethome
Mark this chat as the platform’s home channel for scheduled deliveries. Jobs using--deliver <platform> or --deliver all land here.
Persists to ~/.praisonai/state/home_channels.json. See Proactive Delivery.
/help
Lists all available commands — both built-in and custom — with their descriptions./model
Switches the LLM model for your conversation, or reports which model is currently active. Show current model —/model with no argument:
/model <name>:
git pull or pip install -U against the running checkout), /model <name> refuses the switch instead of risking a half-loaded module:
The override is scoped to your conversation only — other users keep their own model. On each turn the original model is restored after your message is processed, so a shared agent never leaks one user’s model to another concurrent user.
/usage
Reports token usage and a rough estimated cost for the session.
Example output:
/compress
Compresses your conversation history to free context-window space.- Requires at least 10 messages — shorter histories get:
"ℹ️ Conversation too short to compress (need at least 10 messages)." - Targets ~50% token reduction, always preserving the most recent 10 messages and all system messages
- Reports messages removed and tokens freed:
- If the context optimizer library is unavailable, falls back to keeping system messages and the last 10 messages
- On failure the history is left untouched:
"❌ Compression failed: {error}"
/queue
Adds a follow-up message that runs after the current task completes. Check pending queue —/queue with no argument:
/queue requires Bot Run Control to be enabled with busy_mode. Without it, the bot replies: "ℹ️ Message queuing isn't enabled for this bot. Just send your message and it will be processed."/undo
Rewinds the last turn’s file changes viaAgent.undo().
- Requires change tracking — enable
autonomywithtrack_changeson the agent - Returns
"✅ Reverted the last turn."when files were restored,"ℹ️ Nothing to undo."when there is nothing to revert - Degrades gracefully when undo is unavailable:
"❌ This agent does not support undo (change tracking not enabled)."
/sessions
Lists recent saved sessions for the requesting user only. Session lookups are scoped via the per-user storage key so one caller cannot enumerate another user’s sessions. Example output:"No saved sessions yet." when nothing is stored.
/resume
Switches to a previously saved session.- Usage:
/resume <id>— run/sessionsfirst to see IDs - Returns
"❌ Session {id} not found."when the ID is unknown - When the session manager lacks a
resume_sessionprimitive, the bot reports honestly rather than claiming a switch succeeded
/retry
Re-runs your most recent user message through the normalsession.chat(...) path.
"ℹ️ Nothing to retry — no previous message found." when the history is empty.
/reasoning
Toggles whether extended-thinking output is shown for this user in this conversation. The preference is stored per user on the session manager.is_reasoning_visible() when rendering responses.
/learn
Authors a grounded, reusableSKILL.md from sources you name — a codebase, API docs, PDFs, configs, or the current chat.
- Calls
agent.learn_skill(request)which gathers the named sources with the agent’s existing tools and writes one groundedSKILL.mdviaskill_manage - Admin-only by default when a
CommandAccessPolicyis configured (admin_usersoruser_allowed_commandsset) — it belongs toPRIVILEGED_COMMANDSbecause it reads host sources and alters future agent behaviour - Available to all users when no policy is configured (backward-compatible)
Learn Skill
Full guide: sources, grounding rules, async API, bot usage
/automations
Lists pending automation suggestions, one message per suggestion, each with its own✓ Accept / ✕ Dismiss inline keyboard. Telegram only today.
- Header when suggestions exist:
💡 You have 1 pending automation suggestion:(pluralised by count) - Header when empty:
You have no pending automation suggestions.\nUse /blueprint to create one from a template. - Each Accept button carries
sug:accept:<id>; each Dismiss carriessug:dismiss:<id> - The
automationspermission is re-checked on every button tap. A denied user sees⛔ You are not permitted to manage automationsappended to the message - When the scheduler extra isn’t installed:
❌ Automations are not available (scheduler not installed).
/blueprint
Creates an automation directly from a blueprint template. Telegram only today. Three call shapes:/blueprint(no args) → lists available blueprints + usage:
/blueprint <name>→ creates a job with blueprint defaults/blueprint <name> hour=8 weekdays=mon-fri→ slot overrides
key=value grammar. Integer-looking values are coerced to int, so hour, minute, and interval_minutes resolve correctly (_parse_slot_args).
Success and error strings from _automations.create_from_blueprint:
/automations and /blueprint are generic names, so if your app registers a custom @bot.on_command handler of the same name, that handler wins and the built-in steps aside — unlike every other built-in, which always takes precedence. See Automation Suggestions.Custom Commands
Register your own commands usingregister_command(). Available on all bot adapters.
register_command() API
The
description you pass here IS the label users see in the native / menu on Telegram and Discord. See Slash Command Menu.
list_commands()
Get all registered commands:Security & Allowlists
Built-in commands (/status, /new, /help) and custom commands registered via register_command() go through the same security pipeline as regular text messages. If allowed_users is set and the sender is not in it, the command is silently dropped with no reply. If unknown_user_policy="pair", unknown senders get the pairing flow before the command runs. If group_policy="mention_only", commands in groups still need a mention.
Python Usage
Start bots programmatically — built-in commands are always available:Native / Autocomplete (Telegram + Discord)
Typing / in Telegram or Discord surfaces the bot’s commands with descriptions through each platform’s native menu — no configuration needed.
The bot publishes the menu automatically on startup — no user code required:
Design Guarantees
The menu is a discoverability layer that never changes how commands run.Additive. The native menu sits on top of the existing text-command path.
on_message still dispatches every command exactly as before — the menu only makes commands easier to find.Best-effort. Publishing is wrapped in
try/except. A missing SDK, network error, or unsupported platform is logged at debug and swallowed, so startup is never blocked.Per-Platform Behaviour
Out-of-range names are skipped; over-length descriptions are truncated.
Discord shim caveat. Registered Discord slash commands are thin shims. Tapping
/status in Discord replies with Type /status as a message to run this command. — the text-command path remains the execution route. This is intentional so the change stays additive; the slash menu never runs the handler directly.Best Practices
Restrict privileged commands
Restrict privileged commands
Configure
admin_users and user_allowed_commands before enabling /learn, /stop, or /queue in production. See Command Access Control.Enable run control for /stop and /queue
Enable run control for /stop and /queue
/stop and /queue need Bot Run Control with busy_mode for mid-run cancellation and follow-up queuing — without it, users get informational fallbacks only.Compress before long sessions
Compress before long sessions
Run
/compress when conversations exceed ~20 turns. It preserves recent context whilst reclaiming window space for research or coding tasks.Document custom commands in /help
Document custom commands in /help
Always pass a
description to register_command(). Users discover extensions through /help, which filters to commands they are allowed to run.Make /automations and /blueprint admin-only
Make /automations and /blueprint admin-only
The suggestion store is single-tenant — every gateway user shares one pending list. Add
automations and blueprint to admin_users (not user_allowed_commands) for multi-user bots. See Automation Suggestions.Bot tokens should never be hardcoded. Use environment variables or a
.env file to store them securely.Related
Connect your agent to Telegram, Discord, Slack, and WhatsApp.
Understand per-platform message limits, editing, and rate-limit behaviour.
Slash Command Menu
Native
/ autocomplete for Telegram and Discord.Command Access Control
Restrict who can run which commands.
Transcribe inbound voice messages on Telegram, Slack, and WhatsApp.

