stack/plugins/telegram/README.md

@mosaic/telegram-plugin

@mosaic/telegram-plugin connects a Telegram bot to the Mosaic gateway chat namespace so Telegram chats can participate in the same conversation flow as the web, TUI, and Discord channels.

Required Environment Variables

• TELEGRAM_BOT_TOKEN: Bot token issued by BotFather
• TELEGRAM_GATEWAY_URL: Base URL for the Mosaic gateway, for example http://localhost:3000

What It Does

• Launches a Telegram bot with telegraf
• Connects to ${TELEGRAM_GATEWAY_URL}/chat with socket.io-client
• Maps Telegram chat.id values to Mosaic conversationId values
• Forwards inbound Telegram text messages to the gateway as user messages
• Buffers agent:start / agent:text / agent:end socket events and sends the completed response back to the Telegram chat

Getting a Bot Token

1. Open Telegram and start a chat with @BotFather
2. Run /newbot
3. Follow the prompts to name the bot and choose a username
4. Copy the generated token and assign it to TELEGRAM_BOT_TOKEN