Telegram connection | Automata docs

Connect data sources

The included bridge links a personal Telegram account by QR code, stores its encrypted session, and syncs chats into a dedicated PostgreSQL schema.

Before you begin

Terms and consent matter

Telegram API and content-licensing terms restrict using platform data for artificial intelligence except where everyone in a chat has consented. Unofficial clients are monitored more closely, and violations can restrict or ban an account. Review the current Telegram terms before offering this connector.

Create your own API credentials at my.telegram.org under API development tools. Do not reuse published example credentials.

Configure the bridge

Set these values in .env:

TELEGRAM_API_ID=<from-my.telegram.org>
TELEGRAM_API_HASH=<from-my.telegram.org>
TELEGRAM_BRIDGE_ADMIN_KEY=<openssl-rand-hex-24>
TELEGRAM_SESSION_ENCRYPTION_KEY=<openssl-rand-hex-32>
NUXT_TELEGRAM_URL=http://localhost:8095
NUXT_TELEGRAM_ADMIN_KEY=<same-as-bridge-admin-key>
NUXT_TELEGRAM_DATABASE_URL=postgresql://<reader>@localhost:5432/evolution

Start the bridge profile and web app:

pnpm services:up:telegram
pnpm dev

Back up the encryption key

Every stored session is sealed with TELEGRAM_SESSION_ENCRYPTION_KEY. Losing or changing it unlinks every account. A database backup and this key together grant account access.

Link and sync

Create a Telegram account connection, choose Show QR code, and scan from Telegram → Settings → Devices → Link Desktop Device. Two-step verification, when enabled, is sent to Telegram and is not stored by Automata.

Sync behavior

The bridge syncs private chats, bots, groups, supergroups, forum topics, and channels. Live changes continue in real time while a deliberately paced backfill fetches older history.

Backfill stops at TELEGRAM_BACKFILL_MAX_PER_CHAT or TELEGRAM_BACKFILL_DAYS.
Broadcast channels are skipped unless TELEGRAM_BACKFILL_BROADCAST=true.
Secret chats are device-only and never visible.
Unlinking from Automata deletes synced chats; ending the device session in Telegram keeps them for relinking.

Run one bridge process. Two processes competing for one Telegram session can invalidate it, so keep one replica and no deployment overlap.

Bring your own bridge

Select Use my own Telegram bridge and provide its URL, administrator key, and optionally a database URL for message reads. User-supplied origins pass the same outbound host guard as Evolution servers.

View source