Skip to main content

​
Telegram Bot Development

Run your own instance of the GAIA Telegram bot. The bot uses long polling, so no webhook or public URL is required.
Looking to use GAIA on Telegram as a user? See Using GAIA on Telegram.

​
Prerequisites

​
Step 1: Create a Telegram Bot

  1. Open Telegram and search for @BotFather
  2. Send /newbot
  3. Follow the prompts to choose a name and username for your bot
  4. Copy the bot token BotFather gives you
Send /setcommands to BotFather, select your bot, then paste: 
start - Start the bot
gaia - Chat with GAIA
auth - Link your Telegram account
todo - Manage todos
workflow - Manage workflows
conversations - View conversations
new - Start a new conversation
stop - Stop current response and start fresh
status - Check bot status
settings - View your GAIA settings
help - Show help message
unlink - Disconnect your account
This enables Telegram’s command autocomplete for users.

​
Step 3: Configure Environment Variables

Create a .env file in apps/bots/telegram/: 
TELEGRAM_BOT_TOKEN=your_telegram_bot_token
GAIA_API_URL=http://localhost:8000
GAIA_BOT_API_KEY=your_secure_bot_api_key

​
Step 4: Start the Bot

# Development (hot reload)
nx dev bot-telegram

# Production
nx build bot-telegram && nx start bot-telegram

​
Troubleshooting

ProblemSolution
Bot doesn’t respondCheck the bot token is correct and the process is running
Commands not showing autocompleteRun /setcommands with BotFather
Authentication failsEnsure GAIA_BOT_API_KEY matches the API config and the API is reachable