Messaging Bots enable your AI agents to interact with users across 11+ messaging platforms.
Quick Start Start a bot with a single command - no Python code required:
Set Environment Variables
# Telegram export TELEGRAM_BOT_TOKEN = "123456:ABC-DEF..." # Discord export DISCORD_BOT_TOKEN = "MTIz..." # Slack (requires both tokens) export SLACK_BOT_TOKEN = "xoxb-..." export SLACK_APP_TOKEN = "xapp-..."
Start the Bot
# Telegram praisonai bot telegram --token $TELEGRAM_BOT_TOKEN # Discord praisonai bot discord --token $DISCORD_BOT_TOKEN # Slack praisonai bot slack --token $SLACK_BOT_TOKEN --app-token $SLACK_APP_TOKEN
A default agent is created automatically with basic assistant capabilities.
(Optional) Custom Agent
# Use a custom agent configuration praisonai bot slack --token $SLACK_BOT_TOKEN --app-token $SLACK_APP_TOKEN --agent agents.yaml
agents.yaml: name : support-bot instructions : | You are a customer support assistant. Be helpful and concise. llm : gpt-4o-mini tools : - search_web
Full programmatic control with Python:
Create Agent
from praisonaiagents import Agent agent = Agent( name = "assistant" , instructions = "Help users with their questions" , llm = "gpt-4o-mini" )
Configure Bot
from praisonaiagents import BotConfig config = BotConfig( token = "your-bot-token" , command_prefix = "/" , typing_indicator = True , reply_in_thread = False , # Inline replies )
Start Bot
from praisonai.bots import SlackBot # or TelegramBot, DiscordBot bot = SlackBot( token = "xoxb-..." , app_token = "xapp-..." , agent = agent, config = config ) # Run the bot import asyncio asyncio.run(bot.start())
Tool Platform Env Variable SlackToolSlack SLACK_TOKENDiscordToolDiscord DISCORD_BOT_TOKEN or webhook URLTelegramToolTelegram TELEGRAM_BOT_TOKENWhatsAppToolWhatsApp Business WHATSAPP_TOKEN, WHATSAPP_PHONE_IDSignalToolSignal Requires signal-cli daemon LineToolLINE LINE_CHANNEL_ACCESS_TOKENiMessageTooliMessage (macOS only) No token needed TwilioToolSMS/Voice TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKENWebexToolWebex WEBEX_ACCESS_TOKENXToolX (Twitter) X_API_KEY, X_API_SECRETEmailToolEmail (Gmail/SMTP) EMAIL_USERNAME, EMAIL_PASSWORD
These tools are from praisonai-tools for sending outbound messages from agents.
For receiving messages via bot runtime, use the CLI or Python SDK shown above. Install: pip install praisonai-tools
How It Works Component Role Platform Telegram, Discord, or Slack Bot Message router and formatter Agent AI processing and response User End user on messaging app
Socket Mode vs Webhook PraisonAI bots support two connection modes:
Mode Use Case Requirements Socket Mode Local development, behind firewall App Token only Webhook Mode Production, high scale Public URL with HTTPS
Socket Mode works by opening an outbound WebSocket connection to Slack/Discord. No public URL or port forwarding is needed - your bot initiates the connection from behind NAT/firewall.
Configuration Options from praisonaiagents import BotConfig config = BotConfig( token = "bot-token" , # Bot authentication token webhook_url = None , # Webhook URL (optional) command_prefix = "/" , # Command prefix mention_required = True , # Require @mention in groups typing_indicator = True , # Show typing indicator max_message_length = 4096 , # Max message length allowed_users = [], # Allowed user IDs (empty = all) allowed_channels = [], # Allowed channel IDs reply_in_thread = False , # Reply in threads (default: inline) thread_threshold = 500 , # Auto-thread if response > N chars (0 = disabled) )
Option Type Default Description tokenstr""Bot authentication token webhook_urlstrNoneWebhook URL for webhook mode command_prefixstr"/"Prefix for bot commands mention_requiredboolTrueRequire @mention in channels (DMs never require mention) typing_indicatorboolTrueShow typing indicator max_message_lengthint4096Max message length allowed_userslist[]Allowed user IDs allowed_channelslist[]Allowed channel IDs timeoutint30Request timeout reply_in_threadboolFalseAlways reply in threads thread_thresholdint500Auto-thread responses longer than N chars (0 = disabled)
Reply behavior:
Default : Inline replies in the channelAuto-thread : Responses > 500 chars are automatically threadedForce thread : Set reply_in_thread=True to always use threads CLI Capabilities Enable powerful agent features directly from the command line:
Memory praisonai bot slack --memory
Bot remembers previous conversations
Knowledge/RAG praisonai bot slack --knowledge \ --knowledge-sources docs.pdf manual.txt
Answer from your documents
Skills praisonai bot slack --skills researcher writer
Load named skill modules
Extended Thinking praisonai bot slack --thinking high
Enable reflection mode (off/minimal/low/medium/high)
Full CLI Options Reference
Flag Description Example --memoryEnable conversation memory --memory--memory-providerMemory backend --memory-provider chroma--knowledgeEnable RAG/knowledge --knowledge--knowledge-sourcesSource files --knowledge-sources file.pdf--skillsSkill modules --skills researcher--thinkingThinking mode --thinking high--webEnable web search --web--web-providerSearch provider --web-provider duckduckgo--browserEnable browser --browser--toolsNamed tools --tools WikipediaTool--sandboxSandbox mode --sandbox--auto-approveAuto-approve tools --auto-approve
Message @BotFather on Telegram
Send /newbot and follow prompts
Copy the bot token
export TELEGRAM_BOT_TOKEN = "123456:ABC-DEF..." praisonai bot telegram --token $TELEGRAM_BOT_TOKEN
Go to Discord Developer Portal
Create new application → Bot → Reset Token
Enable Message Content Intent
Invite bot to server with proper permissions
export DISCORD_BOT_TOKEN = "MTIz..." praisonai bot discord --token $DISCORD_BOT_TOKEN
Create Slack App
Go to Slack API Console
Click Create New App → From scratch
Enter app name (e.g., “PraisonAI Bot”) and select workspace
Configure OAuth & Permissions
Go to OAuth & Permissions in the sidebar
Scroll to Scopes → Bot Token Scopes
Add these scopes:
Scope Purpose chat:writeSend messages app_mentions:readReceive @mentions im:historyRead DM history im:readAccess DMs channels:historyRead channel messages
Click Install to Workspace at the top
Copy the Bot User OAuth Token (xoxb-...)
Enable Socket Mode
Go to Socket Mode in the sidebar
Toggle Enable Socket Mode ON
When prompted, create an app-level token:
Token Name: socket-mode
Add scope: connections:write
Copy the App Token (xapp-...)
Subscribe to Events
This step is critical! Without event subscriptions, the bot won’t receive messages.
Go to Event Subscriptions in the sidebar
Toggle Enable Events ON
Scroll to Subscribe to bot events
Add these events:
Event Purpose app_mentionWhen someone @mentions your bot message.imDirect messages to your bot
Click Save Changes
Reinstall the app when prompted (or go to OAuth & Permissions → Reinstall)
Enable Messages Tab
Go to App Home in the sidebar
Scroll to Show Tabs → Messages Tab
Ensure Allow users to send Slash commands and messages from the messages tab is toggled ON
Start the Bot
export SLACK_BOT_TOKEN = "xoxb-..." # Bot User OAuth Token export SLACK_APP_TOKEN = "xapp-..." # App-Level Token praisonai bot slack --token $SLACK_BOT_TOKEN --app-token $SLACK_APP_TOKEN
You should see:
Test the Bot
Direct Message : Send a DM to your botChannel Mention : In any channel, type /invite @YourBotName first, then @YourBotName hello
Troubleshooting: Bot not responding
Check these in order:
Event Subscriptions enabled? → Must be ONBot events subscribed? → app_mention and message.im must be listedReinstalled after changes? → Required after adding scopes/eventsApp Token provided? → --app-token is required for Socket ModeBot invited to channel? → Use /invite @BotName before @mentioning
Scope Required For chat:writeSending messages app_mentions:read@mention events im:historyDM access im:readDM access channels:historyChannel message access connections:writeSocket Mode (app token)
Bot Commands Built-in commands users can send:
Command Description /helpShow available commands /statusCheck bot status /resetReset conversation /modelShow current model
Custom commands are automatically created from agent tools.
Common Patterns Restricted Access
Webhook Mode
Group Settings
from praisonaiagents import BotConfig config = BotConfig( token = "your-token" , allowed_users = [ "user123" , "user456" ], allowed_channels = [ "channel789" ] )
from praisonaiagents import BotConfig config = BotConfig( token = "your-token" , webhook_url = "https://your-domain.com/webhook" , webhook_path = "/telegram/webhook" )
from praisonaiagents import BotConfig config = BotConfig( token = "your-token" , mention_required = True , # Only respond when @mentioned command_prefix = "!" , # Use ! for commands )
CLI Commands # Start Telegram bot praisonai bot telegram --token $TOKEN # Start Discord bot praisonai bot discord --token $TOKEN # Start Slack bot praisonai bot slack --token $TOKEN --app-token $APP_TOKEN # With agent configuration praisonai bot telegram --token $TOKEN --agent agents.yaml
The Slack bot uses Slack Bolt , Slack’s official Python framework.
When running, you’ll see “⚡️ Bolt app is running!” - this confirms the bot is connected and listening. Docker Deployment Deploy bots using Docker for production environments:
# Create .env file cat > .env << EOF OPENAI_API_KEY=your-openai-key SLACK_BOT_TOKEN=xoxb-your-slack-bot-token SLACK_APP_TOKEN=xapp-your-slack-app-token EOF # Run with docker compose docker compose up slack-bot -d # View logs docker compose logs -f slack-bot
# Create .env file cat > .env << EOF OPENAI_API_KEY=your-openai-key DISCORD_BOT_TOKEN=your-discord-bot-token EOF # Run with docker compose docker compose up discord-bot -d
# Create .env file cat > .env << EOF OPENAI_API_KEY=your-openai-key TELEGRAM_BOT_TOKEN=your-telegram-bot-token EOF # Run with docker compose docker compose up telegram-bot -d
docker-compose.yml: version : '3.8' services : slack-bot : image : python:3.11-slim environment : OPENAI_API_KEY : ${OPENAI_API_KEY} SLACK_BOT_TOKEN : ${SLACK_BOT_TOKEN} SLACK_APP_TOKEN : ${SLACK_APP_TOKEN} command : > bash -c "pip install praisonai slack-bolt slack-sdk && praisonai bot slack" restart : unless-stopped
For production, build a dedicated Docker image instead of installing dependencies at runtime.
See the docker/bots folder for ready-to-use Dockerfiles. Production (Webhook Mode) For production deployments with a public URL, use webhook mode instead of Socket Mode:
from praisonaiagents import BotConfig from praisonai.bots import SlackBot config = BotConfig( token = "xoxb-your-slack-bot-token" , webhook_url = "https://your-domain.com" , webhook_path = "/slack/events" ) bot = SlackBot( config = config) bot.start() # Listens on /slack/events
Configure in Slack API Console:
Event Subscriptions → Enable EventsSet Request URL: https://your-domain.com/slack/events
Subscribe to bot events: app_mention, message.im
from praisonaiagents import BotConfig from praisonai.bots import DiscordBot # Discord uses Gateway (WebSocket) by default # For HTTP interactions, configure interaction endpoint: config = BotConfig( token = "your-discord-bot-token" , webhook_url = "https://your-domain.com" , webhook_path = "/discord/interactions" ) bot = DiscordBot( config = config) bot.start()
Configure in Discord Developer Portal:
General Information → Interactions Endpoint URLSet: https://your-domain.com/discord/interactions
from praisonaiagents import BotConfig from praisonai.bots import TelegramBot config = BotConfig( token = "your-telegram-bot-token" , webhook_url = "https://your-domain.com" , webhook_path = "/telegram/webhook" ) bot = TelegramBot( config = config) bot.start() # Automatically registers webhook with Telegram
Telegram automatically configures the webhook when you start the bot. Webhook mode requires:
Public HTTPS URL with valid SSL certificatePort 443 (or 80/88/8443 for Telegram)Firewall rules allowing inbound connections Best Practices
Never commit bot tokens to version control. Use environment variables or secure secret management.
Use allowlists in production
Set allowed_users and allowed_channels to prevent unauthorized access to your bot.
Enable mention requirement for groups
Set mention_required=True to prevent the bot from responding to every message in group chats.
Handle rate limits gracefully
Configure retry_attempts and implement exponential backoff for API rate limits.
Multi-Agent Configuration You can also define multiple agents in an agents.yaml file for complex workflows:
agents.yaml: agents : searcher : name : Researcher role : Web Researcher goal : Search the web for relevant information on the given topic instructions : | Search the web thoroughly for information on the user's query. Return comprehensive, accurate results with sources. tools : - search_web summarizer : name : Summarizer role : Content Summarizer goal : Create clear, concise summaries of information instructions : | Take the research findings and create a well-structured summary. Highlight key points and insights. Keep it concise but informative.
