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 Telegram 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: Store the Bot Token in the Vault

Store the bot token as a vault secret using the vault.set primitive or the vault API:

curl -X POST http://localhost:3000/v1/vault/secrets \
  -H "Authorization: Bearer mox_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key_name": "TELEGRAM_BOT_TOKEN",
    "value": "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz-123456",
    "policy_label": "channel"
  }'

Step 3: Create the Telegram Channel

Via CLI:

moxxy channel telegram

Or via API:

curl -X POST http://localhost:3000/v1/channels \
  -H "Authorization: Bearer mox_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "telegram",
    "config": {
      "bot_token_secret_ref": "secret-ref-uuid"
    }
  }'

Step 4: Pair an Agent to a Chat

Bind an agent to a specific Telegram chat using the pairing API:

curl -X POST http://localhost:3000/v1/channels/pair \
  -H "Authorization: Bearer mox_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent-uuid",
    "channel_id": "telegram-channel-uuid",
    "external_chat_id": "123456789"
  }'

Alternatively, use pairing codes for manual binding. Pairing codes are stored in the channel_pairing_codes table and allow users to bind an agent to their chat by sending the code to the bot.

Step 5: Test

Send a message to your bot in Telegram. The bound agent should respond.

How It Works

Moxxy uses a TelegramTransport that polls the Telegram Bot API for new messages. When a message arrives, the transport looks up the channel binding by external_chat_id (the Telegram chat ID) to determine which agent should handle it.

Channel Bindings

Bindings are stored in the channel_bindings table:

Field	Description
agent_id	The agent handling this chat
channel_id	The Telegram channel configuration
external_chat_id	The Telegram chat ID

Features

Bot Commands

Command	Description
/start	Initiate pairing or start interaction
/new	Start a fresh conversation session
/help	Show help message

Voice Messages

Telegram voice messages are supported. When a user sends a voice message, it is transcribed and processed by the bound agent.

Pairing Codes

Pairing codes provide a secure way to bind agents to chats:

1. A pairing code is generated and stored in channel_pairing_codes
2. The user sends the code to the bot in Telegram
3. The system validates the code and creates a channel binding
4. The agent is now bound to that chat

Customizing Your Bot

Set Bot Commands via BotFather

Send /setcommands to @BotFather and enter:

start - Start interacting with the bot
new - Start a new session
help - Show help

Set Bot Description

/setdescription - Set bot description
/setabouttext - Set about text
/setuserpic - Set bot avatar

Troubleshooting

Bot Not Responding

1. Verify the gateway is running on port 3000
2. Check that the channel was created: GET /v1/channels
3. Verify a binding exists for your chat ID
4. Confirm the bot token in the vault is valid

Pairing Failed

1. Ensure the pairing code has not expired
2. Verify the code matches exactly
3. Check that the channel and agent IDs are correct

Voice Transcription Issues

1. Verify that an LLM provider with transcription support is configured
2. Check that the agent has the necessary vault grants for API keys

Security

• Bot tokens are stored in the vault, encrypted at rest
• Pairing codes ensure only authorized chats are bound to agents
• The RedactionEngine scrubs secret values from all SSE events
• Use vault grants to control which agents can access the bot token