Telegram Bot Agent

This skill enables Claude to act as a Telegram bot, managing accounts, sending messages, and automating Telegram interactions with a natural, name-based contact system.

Prerequisites

Before using this skill, ensure the following are installed:

pip install python-telegram-bot python-dotenv

Workflow

1. Bot Creation and Setup

When the user wants to create or configure a Telegram bot:

Guide them to create a bot via @BotFather on Telegram:
- Send /newbot to @BotFather
- Provide a name and username for the bot
- Save the API token provided by BotFather
Run the initialization script:
```
python scripts/init_bot.py
```
This will prompt for the bot token and create a .env file with configuration.
Verify the bot is working:
```
python scripts/test_connection.py
```

Import contacts (IMPORTANT - do this early):

# First, have users message the bot
# Then import all chats as named contacts
python scripts/contacts.py import

2. Contact Management

CRITICAL: Users speak naturally using names like "message John" or "chat with the dev team", NOT "send to chat_id 123456789". Always use the contact system to enable natural interactions.

Import contacts from recent chats (recommended first step):

python scripts/contacts.py import

Add a contact manually:

python scripts/contacts.py add "John" 123456789
python scripts/contacts.py add "Dev Team" -100123456789 --type supergroup

List all contacts:

python scripts/contacts.py list

Search for a contact:

python scripts/contacts.py search john

Get chat ID by name (if needed):

python scripts/contacts.py get "John"

Remove a contact:

python scripts/contacts.py remove "John"

3. Sending Messages

IMPORTANT: When users say "message John" or "send to the team", use contact names with --to:

To a contact by name (PREFERRED METHOD):

python scripts/send_message.py --to "John" -m "Hey, how are you?"
python scripts/send_message.py --to "Dev Team" -m "Deployment complete!"
python scripts/send_message.py --to "mom" -m "Love you!"

To a chat ID (only if contact not saved):

python scripts/send_message.py --to 123456789 -m "Hello!"

Using default contact:

python scripts/send_message.py --use-default -m "Quick update"

With formatting:

python scripts/send_message.py --to "John" -m "**Important** update" --format markdown
python scripts/send_message.py --to "Team" -m "<b>Bold</b> text" --format html

4. Other Operations

Get bot information:

python scripts/bot_info.py

List recent chats (for debugging):

python scripts/list_chats.py

Get specific chat info:

python scripts/get_chat_info.py --chat-id 123456789

5. Joining Groups

To join a group or channel:

The bot must be added to the group by a group admin
Use the invite link or have an admin add the bot directly
Import the group as a contact:
```
python scripts/contacts.py import
```

Send messages by group name:

python scripts/send_message.py --to "Project Team" -m "Hello everyone!"

6. Advanced Features

Send formatted messages:

python scripts/send_message.py --to "John" -m "**Bold** _italic_" --format markdown

Send messages with buttons:

python scripts/send_with_buttons.py --to "John" -m "Choose option" --buttons "Yes,No,Maybe"

Send files/photos:

python scripts/send_file.py --to "John" --file path/to/file.pdf
python scripts/send_photo.py --to "John" --photo path/to/photo.jpg --caption "Check this out!"

Natural Language Translation

When users make requests in natural language, translate them to contact-based commands:

User Says	Command to Use
"Message John"	`send_message.py --to "John" -m "..."`
"Send this to the dev team"	`send_message.py --to "dev team" -m "..."`
"Chat with mom"	`send_message.py --to "mom" -m "..."`
"Tell Sarah about the update"	`send_message.py --to "Sarah" -m "update"`
"Notify everyone in the group"	`send_message.py --to "group name" -m "..."`

Configuration

All bot configuration is stored in .env:

TELEGRAM_BOT_TOKEN=your_bot_token_here
DEFAULT_CHAT_ID=your_default_chat_id

Contacts are stored in contacts.json (created automatically).

Important Notes

Always Use Contact Names: When a user says "message John", use --to "John" not --to 123456789. This is more natural and user-friendly.
Contact Import Workflow:
- Have users message the bot first (or add bot to groups)
- Run python scripts/contacts.py import to auto-import all chats with names
- Users can then reference everyone by name
Natural Language: Translate natural requests to commands:
- "chat with the dev team" → --to "dev team"
- "message John" → --to "John"
- "send to everyone" → loop through contacts
Group IDs: Group chat IDs are negative numbers (e.g., -100123456789). The contact system handles this automatically.
Privacy Mode: By default, bots in groups only receive messages that:
- Start with / (commands)
- Are replies to the bot's messages
- Use @mentions of the bot
To receive all messages, disable privacy mode via @BotFather.
Rate Limits: Telegram enforces rate limits (30 messages/second). The scripts include basic rate limiting.
Contact Names Are Case-Insensitive: "John", "john", and "JOHN" all work the same way.

Reference Documentation

For detailed API information and advanced usage:

See references/telegram_api.md for complete Telegram Bot API reference
See references/examples.md for common usage patterns and code examples

Security Best Practices

Never commit the .env file or contacts.json (contains chat IDs)
Never share the bot token
Validate all user inputs before sending messages
Use environment variables for all sensitive configuration
Rotate bot tokens regularly via @BotFather if compromised

Troubleshooting

Contact not found:

Run python scripts/contacts.py list to see all contacts
Run python scripts/contacts.py import to import from recent chats
Add manually: python scripts/contacts.py add "Name" chat_id

Bot not receiving messages:

Check privacy mode settings with @BotFather
Verify the bot is in the group/chat
Ensure the bot hasn't been blocked

"Unauthorized" errors:

Verify the bot token is correct in .env
Check if the token has been revoked via @BotFather

Cannot send to group:

Confirm the bot is a member of the group
Check bot has permission to send messages
Import the group: python scripts/contacts.py import

Examples

Quick Setup for Natural Messaging

# 1. Initialize bot
python scripts/init_bot.py

# 2. Have people message your bot or add it to groups

# 3. Import all contacts with names
python scripts/contacts.py import

# 4. Now send messages naturally by name
python scripts/send_message.py --to "John" -m "Hey!"
python scripts/send_message.py --to "Dev Team" -m "Deploy complete"
python scripts/send_message.py --to "mom" -m "Love you"

Integration Example

# In your Python code
import subprocess

def message_contact(name, text):
    """Send message to a contact by name"""
    subprocess.run([
        'python', 'scripts/send_message.py',
        '--to', name,
        '-m', text
    ])

# Usage
message_contact("John", "Task completed!")
message_contact("Dev Team", "Build successful!")

telegram-bot-agent