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. Each Telegram user gets their own isolated session, and photos or files sent to the bot are saved locally for processing.
A Telegram bot is reachable by anyone who finds it. The adapter is built for that. A session has no tool loop, so — unlike gaia chat, which does have tools — a message cannot run a shell command, edit your files, or drive anything else on your machine. It answers with text. The one thing a message does write is its own attachments: photos and documents you send are saved to a temporary path and indexed so their contents can be read back. Access is restricted to an explicit list of Telegram user IDs, which is required to start the bot.

​
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 and the Telegram user IDs allowed to talk to it:
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. To find your own numeric user ID, message @userinfobot. Omitting --allowed-users is refused at startup:
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 long-lived service. It writes a PID file to ~/.gaia/telegram.pid, a start marker to ~/.gaia/telegram.log, and exposes a health endpoint on 127.0.0.1:8768. Runtime logs — including refusals — go to ~/.gaia/gaia.log:
The command does not detach on its own — it holds the terminal for as long as the adapter polls, so that gaia telegram stop has a live process to signal. Add & or run it under nohup/systemd to get your prompt back.

​
Restrict who can use the bot

--allowed-users takes a comma-separated list of numeric Telegram user IDs, and it is required — there is no way to run the bot open to everyone:
Anyone not on the list gets a short “not authorized” reply and their message is never sent to the model. Each refusal is logged with the rejected user’s ID, so if someone who should have access is being turned away, find their ID in ~/.gaia/gaia.log and add it to the list.
Changing the list means restarting the adapter — it is read once at startup.

​
Check status and stop

gaia telegram status checks 127.0.0.1:8768 by default. If you changed the health binding, point it at the right host and port with --health-host and --health-port. When running the adapter in the background, gaia telegram start also accepts --health-port to move the health server (e.g. when the default collides with another local service).

​
Command reference

​
How It Works

  • Allowlist first — every update, including /start, is checked against --allowed-users before a session is created or any model is called.
  • No tool loop — a Telegram session is a chat session, not an agent. There are no shell, file-write, or other action tools for a message to reach.
  • Per-user sessions — the adapter keeps one Agent SDK session per Telegram user ID, so conversation history stays separated between users. Sessions live in memory and are lost when the adapter restarts.
  • 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 their contents can be read into the conversation.
  • 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 full chat agent — RAG, memory, and tools — on your desktop.

Agent Memory

Persistent memory for the desktop agents.

Agent UI

The desktop front-end for the same agents.

All Guides

Browse every GAIA agent and adapter.