Skip to main content
First time here? Complete the Setup guide first to install GAIA and its dependencies.
The Telegram adapter lets you talk to GAIA from the Telegram app on any device. It runs a bot that receives messages, runs each one through a local GAIA chat session, and streams the response back to the chat — so your phone becomes a front-end for the same agent you run on your desktop. It’s a messaging adapter, not a separate agent: every conversation is backed by the standard Agent SDK, so RAG, memory, and tool use behave exactly as they do in gaia chat. Each Telegram user gets their own isolated session, and photos or files sent to the bot are saved locally for the agent to process.

​
Prerequisites

1

Install the Telegram extra

The adapter depends on python-telegram-bot, which ships in the telegram extra:
2

Create a bot and get its token

In Telegram, open a chat with @BotFather, send /newbot, and follow the prompts. BotFather returns a bot token that looks like 123456789:ABCdef.... Keep it secret — anyone with the token can control your bot.
3

Make sure a local model is available

The adapter runs inference through your local Lemonade backend, the same as gaia chat. If you haven’t set up a model yet, run gaia init first.

​
Quick Start

Start the adapter in the foreground, passing the token from BotFather:
The bot begins polling Telegram immediately. Open your bot in the Telegram app, send it a message, and you’ll get a streamed reply. Press Ctrl+C to stop.
The token is supplied only via --token — there is no environment variable for it. Wrap the command in a script or shell history that keeps the token out of shared logs.

​
Core Usage

​
Run in the background

Use --background to run the adapter as a daemon. It writes a PID file to ~/.gaia/telegram.pid, logs to ~/.gaia/telegram.log, and exposes a health endpoint on 127.0.0.1:8765:

​
Restrict who can use the bot

By default the bot replies to anyone who messages it. Pass --allowed-users with a comma-separated list of numeric Telegram user IDs to lock it down:
To find your own Telegram user ID, message @userinfobot. Messages from anyone not on the allow-list are ignored.

​
Check status and stop

gaia telegram status checks 127.0.0.1:8765 by default. If you changed the health binding, point it at the right host and port with --health-host and --health-port.

​
Command reference

​
How It Works

  • Per-user sessions — the adapter keeps one Agent SDK session per Telegram user ID, so conversation history and memory stay separated between users.
  • Streaming replies — responses stream back into the Telegram chat as the model generates them.
  • Attachments — photos and files sent to the bot are saved to a temporary path so the agent can read or analyze them.
  • Local inference — all model calls go through your local Lemonade backend; message content is processed on your machine.
Implementation lives in src/gaia/messaging/telegram.py.

​
Next Steps

Document Q&A

The chat agent that backs every Telegram session — RAG, memory, and tools.

Agent Memory

Give your Telegram bot a persistent memory across conversations.

Agent UI

The desktop front-end for the same agents.

All Guides

Browse every GAIA agent and adapter.