> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heygaia.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Telegram Bot

> Self-host the GAIA Telegram bot: create a bot with BotFather, register commands, and run it against your GAIA API.

# 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.

<Note>
  Looking to use GAIA on Telegram as a user? See [Using GAIA on Telegram](/guides/telegram-bot).
</Note>

## Prerequisites

* Node.js 18+ and pnpm
* A Telegram account
* GAIA API running (see [Self-Hosting Guide](/self-hosting/overview))

## Step 1: Create a Telegram Bot

1. Open Telegram and search for [@BotFather](https://t.me/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

## 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/`:

```bash theme={null}
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

```bash theme={null}
# 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 |