Telegram Channel

Connect your Moxxy agent to Telegram as a bot.

Prerequisites

1. A Telegram account
2. Access to @BotFather on Telegram

Setup

Step 1: Create a Bot

1. Open Telegram and search for @BotFather
2. Send /newbot
3. Follow the prompts:
   • Choose a bot name (e.g., "My Moxxy Bot")
   • Choose a username (e.g., "mymoxxy_bot")
4. Save the bot token you receive:

   1234567890:ABCdefGHIjklMNOpqrsTUVwxyz-123456

Step 2: Connect to Moxxy

moxxy channel telegram --agent default

You'll be prompted for:

• Bot token - From @BotFather
• Pairing code - After sending /start

Step 3: Pair Your Account

1. Open your bot in Telegram
2. Send /start
3. You'll receive a 6-digit pairing code
4. Enter the code in the terminal:

   ? Pairing code: 123456

Step 4: Done!

Your agent is now connected. Send a message to your bot to test.

Bot Commands

Command	Description
/start	Pair your account with the bot
/skills	List available skills
/new	Start a fresh conversation session
/help	Show help message

Voice Messages

Telegram voice messages are automatically transcribed:

1. Send a voice message to your bot
2. Moxxy uses OpenAI Whisper to transcribe
3. Agent responds to the transcribed text

Configure Whisper Model

moxxy run --agent default --prompt "Store 'whisper-1' in vault as whisper_model"

Configuration Options

CLI Options

moxxy channel telegram --agent <name> [--token <token>] [--pair-code <code>]

Option	Description
--agent, -a	Agent to connect (default: "default")
--token	Bot token (prompts if omitted)
--pair-code, -c	Pre-entered pairing code

Vault Configuration

Key	Description
telegram_token	Bot token from @BotFather
telegram_admin_id	Allowed Telegram user ID
whisper_model	Whisper model for voice

Environment Variables

export TELEGRAM_BOT_TOKEN="1234567890:ABC..."

Security

Pairing Mechanism

The pairing system ensures only you can use your bot:

1. Unpaired: Bot only accepts /start
2. Pairing: 6-digit code verification
3. Paired: Full bot access

Admin Restrictions

Limit bot access to specific users:

moxxy run --agent default --prompt "Store '123456789' in vault as telegram_admin_id"

Get your Telegram user ID from @userinfobot.

Security Best Practices

1. Never share your bot token
2. Set admin_id to restrict access
3. Use HTTPS webhook in production
4. Monitor logs for suspicious activity
5. Regenerate token if compromised

Webhooks vs Polling

Polling (Default)

Bot actively fetches new messages:

Telegram Server ← Bot: "Any new messages?"
Telegram Server → Bot: "Yes, here they are"

Pros:

• Simple setup
• Works behind NAT
• No public URL needed

Cons:

• Higher latency
• More API calls

Webhooks

Telegram pushes messages to your server:

User → Telegram → Your Server → Bot

Setup:

moxxy run --agent default --prompt "Store 'https://your-domain.com/telegram/webhook' in vault as telegram_webhook_url"

Pros:

• Lower latency
• Fewer API calls
• Real-time updates

Cons:

• Requires public HTTPS URL
• More complex setup

Advanced Features

Custom Commands

Define custom bot commands via @BotFather:

1. Send /setcommands to @BotFather
2. Enter:

   start - Pair your account
   skills - List available skills
   new - Start new session
   help - Show help

Bot Description

Set bot info via @BotFather:

/setdescription
/about
/setavatar

Inline Mode

Enable inline queries:

moxxy run --agent default --prompt "Store 'true' in vault as telegram_inline_enabled"

Users can then: @your_bot search query

Group Chats

Add your bot to groups:

1. Add bot to group
2. Give it permissions
3. Mention or reply to trigger

Note: Bot only responds to mentions/replies in groups.

Troubleshooting

Bot Not Responding

1. Check gateway status:

   moxxy gateway status

2. Check logs:

   moxxy logs | grep -i telegram

3. Verify token:

   moxxy run --agent default --prompt "What is my telegram_token?"

Pairing Failed

1. Ensure you sent /start first
2. Check code is 6 digits
3. Try again (code expires in 5 minutes)

Rate Limited

Telegram limits: ~30 messages/second

If rate limited:

• Reduce message frequency
• Add delays between messages
• Check for broadcast loops

Voice Transcription Failed

1. Verify Whisper API key:

   moxxy doctor

2. Check OpenAI API status

3. Verify audio format (OGG expected)

API Reference

Webhook Endpoint

POST /api/webhooks/telegram

Payload: Telegram Update Object

Send Message

curl -X POST http://localhost:17890/api/agents/default/telegram/send \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "123456789",
    "text": "Hello from Moxxy!"
  }'

Send Photo

curl -X POST http://localhost:17890/api/agents/default/telegram/send \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "123456789",
    "photo": "https://example.com/image.jpg",
    "caption": "Check this out!"
  }'

Examples

Basic Interaction

User: Hello!

Bot: Hi! I'm your Moxxy assistant. How can I help you today?

User: What's the weather?

Bot: Let me check the weather for you.
[Uses web_crawler skill]
The current weather in your area is sunny, 72°F.

Using Skills

User: Check my server status

Bot: I'll check your server status.
[Uses host_shell skill]
Your server is up and running:
- CPU: 23%
- Memory: 4.2GB / 16GB
- Disk: 120GB / 500GB

Scheduled Notifications

User: Send me a daily summary at 9am

Bot: I'll schedule a daily summary for you.
[Uses scheduler skill]
Done! You'll receive a daily summary at 9am.