Bot Chat Commands

Built-in and custom chat commands for Telegram, Discord, Slack, and WhatsApp bots.

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.

/help

Lists all available commands (built-in + custom) with descriptions.

Quick Start

1. Install PraisonAI

   pip install praisonai
   
2. Set Your Bot Token

   export TELEGRAM_BOT_TOKEN=your_token_here
   
3. Start the Bot

   praisonai bot telegram --token $TELEGRAM_BOT_TOKEN
   
4. Send a Command

   Open your bot chat and type:

   /status
   

   You’ll see the agent name, model, platform, and uptime.

Platform Examples

Telegram

praisonai bot telegram --token $TELEGRAM_BOT_TOKEN

Command Details

/status

Shows current bot information:

Field	Description
Agent	Name of the AI agent
Model	LLM model being used
Platform	telegram, discord, slack, or whatsapp
Uptime	How long the bot has been running
Running	Whether the bot is currently active

/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

The /stop command requires Bot Run Control to be enabled. Set busy_mode to any value other than the default to enable this feature.

/help

Lists all available commands — both built-in and custom — with their descriptions.

Commands work the same way on all platforms — Telegram, Discord, Slack, and WhatsApp. The / prefix is the default command prefix.

---

Custom Commands

Register your own commands using register_command(). Available on all bot adapters.

from praisonai.bots import TelegramBot
from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Be helpful")
bot = TelegramBot(token="YOUR_TOKEN", agent=agent)

# Register a custom command
async def handle_ping(message):
    return "Pong! Bot is alive."

bot.register_command("ping", handle_ping, description="Check if bot is alive")

import asyncio
asyncio.run(bot.start())
# Now /ping is available alongside /status, /new, /stop, /help

register_command() API

bot.register_command(
    name="mycommand",           # Command name (without /)
    handler=my_handler,          # Async or sync callable
    description="What it does",  # Shown in /help
    usage="/mycommand <arg>",    # Optional usage string
    channels=["telegram"],       # Optional: restrict to specific platforms
)

Parameter	Type	Required	Description
name	str	Yes	Command name without / prefix
handler	Callable	Yes	Function to call. Receives a BotMessage argument
description	str	No	Human-readable description (shown in /help)
usage	str	No	Usage example string
channels	list[str]	No	Restrict to specific platforms (e.g., ["telegram", "slack"]). Empty = all platforms

list_commands()

Get all registered commands:

commands = bot.list_commands()
# Returns: [ChatCommandInfo(name="status", ...), ChatCommandInfo(name="new", ...), ...]

# Filter by platform
telegram_commands = bot.list_commands(platform="telegram")

---

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.

from praisonai.bots import TelegramBot
from praisonaiagents.bots import BotConfig
from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Be helpful")
bot = TelegramBot(
    token="YOUR_TOKEN",
    agent=agent,
    config=BotConfig(allowed_users=["123456789"]),  # Only this user
)

# /help, /status, /new from any other user are now silently ignored

For full allowlist setup, see the Bot Security guide. This security hardening was implemented in PR #1835.

---

Python Usage

Start bots programmatically — built-in commands are always available:

Telegram

from praisonai.bots import TelegramBot
from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Be helpful")
bot = TelegramBot(token="YOUR_TOKEN", agent=agent)

import asyncio
asyncio.run(bot.start())
# /status, /new, /stop, /help available automatically

Bot tokens should never be hardcoded. Use environment variables or a .env file to store them securely.