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; Telegram refuses them.

The credentials are optional, but set both or neither. With neither, the bridge still starts, /health reports "telegram": "unconfigured", and Add a connection explains what to set. Setting both later and restarting the bridge turns Telegram on.

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://<user>@localhost:5432/evolution

NUXT_TELEGRAM_DATABASE_URL can use the owner credential; a restricted reader role is optional (see Where the data lives). Until NUXT_TELEGRAM_URL and NUXT_TELEGRAM_ADMIN_KEY are set, creating a Telegram connection is refused with a message that no Telegram bridge is available.

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.

Where the data lives

The bridge uses the same Postgres as Evolution and the web app, in its own telegram schema, which it creates on first start. It connects with the owner credential. To give the app less, create a LOGIN-only role, set TELEGRAM_READER_ROLE to its name on the bridge, and use that role in NUXT_TELEGRAM_DATABASE_URL. The bridge re-grants column-level SELECT at every start, never on sessions, access hashes, or phone numbers.

One bridge process

Run one bridge process. Two processes competing for one Telegram session can invalidate it, so keep one replica and no deployment overlap. A second process waits on the session lock and takes over once the first exits.

Telegram test servers

Set TELEGRAM_TEST_SERVERS=true to use Telegram's separate test environment. Test-server accounts are distinct from real accounts, which makes this the safest way to try the connector end to end.

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