GAIA on Telegram Talk to GAIA, manage todos, and run workflows directly inside Telegram. The bot works in private chats and supports standard Telegram slash commands with autocomplete via BotFather.
Start Chatting on Telegram Search for the GAIA bot on Telegram and open a private chat — no group or server needed.
Message GAIA on Telegram Open a private chat with GAIA on Telegram
Telegram DMs are fully private — only you and GAIA see the conversation. You can send free-text messages at any time without using a command prefix.
Getting Started (Users) 1. Start the Bot Send the /start command to begin:
You’ll see a welcome message with an overview of available commands.
2. Link Your GAIA Account Click the link provided, log in to your GAIA account, and your Telegram identity will be connected.
3. Start Chatting /gaia What's on my todo list?
You can also send a free-text message directly — the bot will forward it to GAIA automatically.
Available Commands Chat Command Description /startStart the bot and see the welcome message /gaia <message>Send a message to GAIA /helpShow all available commands
Todos Command Description /todo listShow all active todos /todo add <title>Create a new todo /todo complete <id>Mark a todo as done /todo delete <id>Delete a todo
Workflows Command Description /workflow listList all your workflows /workflow get <id>View workflow details /workflow execute <id>Trigger a workflow manually
Conversations & Utilities Command Description /conversationsBrowse your GAIA conversation history /newStart a fresh conversation /stopStop the current response and start fresh /statusCheck bot and API status /settingsView your GAIA settings and integrations /authLink your Telegram account to GAIA /unlinkDisconnect your account from GAIA
Notes
Commands begin with / as is standard in Telegram
Free-text messages (without a command prefix) are automatically sent to GAIA as chat messages
Rich formatting like embeds is limited compared to Discord/Slack — responses use plain text and Markdown
Developer Setup This section is for developers who want to self-host the GAIA Telegram bot.
Prerequisites 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.
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
The bot uses long polling — no webhook or public URL is required.
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
