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

Node.js 18+ and pnpm
A Telegram account
GAIA API running (see Self-Hosting Guide)

Step 1: Create a Telegram Bot

Open Telegram and search for @BotFather
Send /newbot
Follow the prompts to choose a name and username for your bot
Copy the bot token BotFather gives you

Step 2: Register Commands (Optional but Recommended)

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

Problem	Solution
Bot doesn’t respond	Check the bot token is correct and the process is running
Commands not showing autocomplete	Run `/setcommands` with BotFather
Authentication fails	Ensure `GAIA_BOT_API_KEY` matches the API config and the API is reachable

Getting Started

Self-Hosting

CLI

Contributing

Bot Development

Conventions

Telegram Bot

Telegram Bot Development

Prerequisites

Step 1: Create a Telegram Bot

Step 2: Register Commands (Optional but Recommended)

Step 3: Configure Environment Variables

Step 4: Start the Bot

Troubleshooting

​Telegram Bot Development

​Prerequisites

​Step 1: Create a Telegram Bot

​Step 2: Register Commands (Optional but Recommended)

​Step 3: Configure Environment Variables

​Step 4: Start the Bot

​Troubleshooting

Telegram Bot Development

Prerequisites

Step 1: Create a Telegram Bot

Step 2: Register Commands (Optional but Recommended)

Step 3: Configure Environment Variables

Step 4: Start the Bot

Troubleshooting