Overview
The Telegram integration enables your elizaOS agent to interact with users through Telegram’s messaging platform. Your agent can send and receive messages, handle commands, work with inline keyboards, and more.
Prerequisites
Before setting up Telegram integration, you need:
Setup
Open Telegram and search for @BotFather
Start a chat and send the /newbot command
Follow the prompts to choose a name and username for your bot
BotFather will provide you with a token that looks like: 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
Copy this token - you’ll need it for configuration
Optional but recommended settings via BotFather:
/setdescription - Set a description that users see in the bot’s profile
/setabouttext - Set the “About” text
/setuserpic - Upload a profile picture
/setcommands - Define command list with descriptions
/setprivacy - Enable/disable privacy mode (affects group message access)
Set Environment Variables
Add the following to your .env file:
# Required
TELEGRAM_BOT_TOKEN=your_bot_token_here
In your character configuration file, add the Telegram plugin:
{
"name": "YourAgent",
"plugins": [
"@elizaos/plugin-telegram"
],
"settings": {
"channels": {
"telegram": {
"enabled": true
}
}
}
}
Configuration
Environment Variables
The Telegram integration supports the following environment variables:
| Variable | Required | Description |
|---|
TELEGRAM_BOT_TOKEN | Yes | Your bot token from BotFather |
TELEGRAM_TOKEN → TELEGRAM_BOT_TOKENTELEGRAM_API_TOKEN → TELEGRAM_BOT_TOKENTG_BOT_TOKEN → TELEGRAM_BOT_TOKEN
Character Settings
Configure Telegram-specific behavior in your character file:
{
"settings": {
"channels": {
"telegram": {
"enabled": true,
"parseMode": "Markdown",
"disableNotification": false,
"allowedUpdates": ["message", "callback_query", "inline_query"]
}
}
}
}
Features
Message Handling
Your agent automatically receives and can respond to messages:
// The agent receives messages and can respond
// Response format:
{
"chatId": 123456789,
"text": "Hello! How can I help you today?",
"parseMode": "Markdown"
}
Text Formatting
Telegram supports rich text formatting:
// Markdown format (default)
{
"text": "*bold* _italic_ `code` [link](https://example.com)"
}
// HTML format
{
"text": "<b>bold</b> <i>italic</i> <code>code</code> <a href='https://example.com'>link</a>",
"parseMode": "HTML"
}
// Send photo
{
"action": "sendPhoto",
"chatId": 123456789,
"photo": "https://example.com/image.jpg",
"caption": "Check out this image!"
}
// Send document
{
"action": "sendDocument",
"chatId": 123456789,
"document": "file:///path/to/document.pdf",
"caption": "Here's the document you requested"
}
// Send audio
{
"action": "sendAudio",
"chatId": 123456789,
"audio": "https://example.com/audio.mp3",
"title": "Audio File"
}
// Send video
{
"action": "sendVideo",
"chatId": 123456789,
"video": "https://example.com/video.mp4",
"caption": "Video content"
}
Inline Keyboards
Create interactive buttons:
{
"text": "Choose an option:",
"replyMarkup": {
"inline_keyboard": [
[
{ "text": "Option 1", "callback_data": "opt1" },
{ "text": "Option 2", "callback_data": "opt2" }
],
[
{ "text": "Visit Website", "url": "https://example.com" }
]
]
}
}
Commands
Handle slash commands:
// Common commands to implement:
// /start - Welcome new users
// /help - Show help information
// /settings - User preferences
// /about - Bot information
start - Start interacting with the bot
help - Get help and available commands
settings - Configure your preferences
about - Learn more about this bot
Reply and Quote
Reply to specific messages:
{
"chatId": 123456789,
"text": "Replying to your message",
"replyToMessageId": 987654321
}
Edit and Delete
Modify or remove messages:
// Edit message
{
"action": "editMessageText",
"chatId": 123456789,
"messageId": 987654321,
"text": "Updated message content"
}
// Delete message
{
"action": "deleteMessage",
"chatId": 123456789,
"messageId": 987654321
}
Chat Actions
Show typing indicator or other actions:
{
"action": "sendChatAction",
"chatId": 123456789,
"action": "typing" // typing, upload_photo, upload_video, etc.
}
Group Chat Features
Handle group interactions:
// Get chat information
{
"action": "getChat",
"chatId": 123456789
}
// Get chat member info
{
"action": "getChatMember",
"chatId": 123456789,
"userId": 987654321
}
// Leave chat
{
"action": "leaveChat",
"chatId": 123456789
}
Inline Queries
Respond to inline queries (when users mention your bot in other chats):
// This requires enabling inline mode in BotFather
// Use /setinline command to set placeholder text
Privacy and Security
Privacy Mode
By default, bots in groups only receive:
- Messages that start with
/ (commands)
- Messages that mention the bot
- Replies to the bot’s messages
Disable privacy mode in BotFather with /setprivacy if your bot needs to see all messages.
Only disable privacy mode if absolutely necessary for your bot’s functionality. Users can see whether privacy mode is enabled in the bot’s profile.
User Data
Best practices:
- Only store necessary user data
- Implement
/deletedata command for GDPR compliance
- Encrypt sensitive information
- Clear old data regularly
Plugin Auto-Loading
If you set TELEGRAM_BOT_TOKEN in your environment, the Telegram plugin will automatically load:
// From character.ts:249
const plugins = [
...(env.TELEGRAM_BOT_TOKEN?.trim() ? ["@elizaos/plugin-telegram"] : [])
];
Webhook vs Long Polling
Telegram supports two methods for receiving updates:
Long Polling (Default)
The bot regularly checks for new messages. Suitable for:
- Development and testing
- Bots without a public domain
- Simple deployments
Webhook (Production)
Telegram sends updates to your server URL. Better for:
- Production deployments
- High-traffic bots
- When you have a public HTTPS domain
To set webhook:
curl -X POST https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook \
-H "Content-Type: application/json" \
-d '{"url": "https://yourdomain.com/webhook"}'
Troubleshooting
Bot doesn’t respond
- Verify your
TELEGRAM_BOT_TOKEN is correct
- Check that you’ve sent
/start to the bot
- If in a group, ensure privacy mode settings are correct
- Check console logs for error messages
- Verify
parseMode is set correctly (“Markdown” or “HTML”)
- Check for special characters that need escaping
- Ensure markup syntax is valid
- Check file size limits (photos: 10MB, files: 50MB)
- Verify URL is publicly accessible
- For local files, use
file:///absolute/path
- Ensure file format is supported
Commands not working in groups
- Check privacy mode settings in BotFather
- Verify the bot has been added to the group
- Ensure commands are properly registered
Best Practices
- Respond quickly - Telegram users expect fast responses
- Use typing indicators - Show
typing action for longer processing
- Keep messages concise - Mobile users appreciate brevity
- Use inline keyboards - They’re more intuitive than custom keyboards
- Handle errors gracefully - Provide helpful error messages
- Test in private first - Create a test bot before going public
- Implement /help - Make it easy for users to discover features
- Use message editing - Update messages instead of sending new ones when possible
Rate Limits
Telegram has rate limits to prevent spam:
- Messages to same chat: 1 message per second
- Messages to different chats: 30 messages per second across all chats
- Bulk notifications: 30 messages per second
The Telegram API will return error code 429 if you exceed limits. Implement exponential backoff for retries.