ATF
v2.2.4 · 14 implemented · 2 partial · 2 planned

Self-hosted Telegram Message Forwarding built for scale

One task, many sources, many targets. Per-task content rules, validated shortcodes, optional AI rewriting, ordered durable delivery and fail-closed multi-tenancy — running on your own infrastructure.

Get Started FreeInteractive PlaygroundStar on GitHub
  • Fail-closed isolation
  • 10 languages, 1:1 parity
  • AES-256-GCM at rest
  • MIT licensed
4
Services
78
gRPC methods
201
Test suites
Example pipeline tracedeliveredv2.2.4
14:00:07RECEIVED album of 3 · @MarketNews · update 4921
14:00:07VALIDATING duplicate fingerprint · fresh
14:00:08AUTHORIZED session · write access to target
14:00:08TRANSFORM cleaner 3 urls · header + footer rendered
14:00:09ACCEPTED queued lane #4 · correlation 9f3c…
14:00:09IN_PROGRESS copy delivery → @MyBroadcast
14:00:11SUCCEEDED target_msg_id 8812 · 3/3 parts
14:00:11[PIPELINE:DELIVERED]1 source in → 2 targets out · 0 retries
  1. Telegram MTProto
  2. policy gate
  3. transforms + AI
  4. durable queue
  5. copy · forward · hop

Illustrative trace over the real lifecycle states — RECEIVED → VALIDATING → AUTHORIZED → ACCEPTED → IN_PROGRESS → RETRY_WAIT → SUCCEEDED → FAILED → CANCELLED → OUTCOME_UNCONFIRMED. Nothing on the site reads from a running deployment.

Catalogued capabilities · read from the repository, not typed here

Create forwarding ruleUpdate forwarding rule (optimistic concurrency)Pause/resume rule with durable queue semanticsDurable message forwarding pipelineBranding hop (A -> C -> B) composed with every message transformSHA-256 content fingerprint deduplicationKeyword-triggered reply add-onCentral Logger gRPC microserviceCreate forwarding ruleUpdate forwarding rule (optimistic concurrency)Pause/resume rule with durable queue semanticsDurable message forwarding pipelineBranding hop (A -> C -> B) composed with every message transformSHA-256 content fingerprint deduplicationKeyword-triggered reply add-onCentral Logger gRPC microservice
Microservices
4
UI languages
10
Localized strings
1561
CLI command groups
29
gRPC methods
78
REST routes
102

Counted from this checkout during the build — 593 source files and 524 modules across 8 subsystems.

How it works

One message, five stages, no silent failures

Ingest, gate, transform, queue, deliver. Each stage is inspectable from the CLI and the dashboard, and each one has a defined answer for failure instead of hope.

  1. 1

    Ingest

    A session polls every source chat of every enabled task. Albums are aggregated into a single job and the channel cursor is committed atomically, so the poller cannot race the connection or replay a batch.

  2. 2

    Gate

    The policy engine decides cheapest-first: length gates, media allow/deny, Unicode-folded word-boundary blacklists and whitelists, then ReDoS-refused regex patterns. A SHA-256 fingerprint drops content already delivered.

  3. 3

    Transform

    The cleaner strips URLs, mentions, hashtags, phone numbers and emojis while UTF-16 entity offsets keep bold and italic spans intact. Literal and regex replacements run in one deterministic pass, then shortcodes render the header and footer, and the optional AI pass rewrites the body.

  4. 4

    Queue

    The delivery is persisted as a job and picked up by a lease-based worker with exponential backoff and jitter. Ordered lanes keep a burst in posted order; a failing job retries, then lands in the dead-letter queue where it can be inspected and replayed.

  5. 5

    Deliver

    Copy mode posts the content as your own message, direct forward keeps the native quote header, and the branding hop posts through an intermediate channel before the target. Edit and delete events follow the message; a Telegram timeout is recorded as OUTCOME_UNCONFIRMED rather than guessed at.

Every state a delivery passes through is recorded: RECEIVED · VALIDATING · AUTHORIZED · ACCEPTED · IN_PROGRESS · RETRY_WAIT · SUCCEEDED · FAILED · CANCELLED · OUTCOME_UNCONFIRMED.

Architecture referenceObservability deep dive

Install

Running in one command, proven before it says done

The wizard detects the machine, asks only what it cannot work out itself, builds the four services and then probes each one before it reports success.

install · v2.2.4
# v2.2.4 — guided install (recommended)
git clone https://github.com/Opselon/AutoTelegramForward.git && cd AutoTelegramForward
./scripts/setup.sh

# Manual compose path
cp .env.example .env      # add your bot token + admin id
docker compose up -d
docker compose ps         # core, logger, api, web
Four containers — core, logger, api, web — behind one compose file.Docker guide
# One-line installer
curl -sSL https://raw.githubusercontent.com/Opselon/AutoTelegramForward/master/install.sh | bash

# Or the interactive wizard
git clone https://github.com/Opselon/AutoTelegramForward.git && cd AutoTelegramForward
./scripts/setup.sh
atf status                # live board with ports + reachability
Installer or wizard, then a systemd service that survives reboots.Linux guide
# PowerShell, no prerequisites beyond Python
irm https://raw.githubusercontent.com/Opselon/AutoTelegramForward/master/install.ps1 | iex

# Or bootstrap a checkout
git clone https://github.com/Opselon/AutoTelegramForward.git; cd AutoTelegramForward
python scripts\bootstrap.py
atf status
PowerShell installer, then the same wizard and the same CLI.Windows guide
git clone https://github.com/Opselon/AutoTelegramForward.git && cd AutoTelegramForward
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python3 -m core.main        # Python core on :50051
atf validate --strict       # layout, env, compose, catalog parity
Virtualenv, requirements, then run the services yourself.Install overview
Recommended

Guided setup script

Clones, creates the virtualenv, puts atf on PATH and starts the wizard that detects the platform, validates each answer and proves every service is serving.

./scripts/setup.shLinux · macOS · Windows

Zero-prerequisite installer

Installs Python and git when they are missing, clones the checkout and hands over to the same wizard. Nothing to prepare first.

curl -fsSL .../install.sh | bashContainer first

Docker Compose

Four containers from one compose file: Python core, Rust logger, Go API and Rust web gateway. Fill .env, bring it up, read the status board.

docker compose up -dNo install at all

Portable single file

Build dist/atf.pyz and carry the whole CLI to a host with only Python 3.11+ on it. Standard library only — no venv, no checkout.

atf release portable

What changed

Routing became a model, rules moved onto the task

Each capability below has a deep dive that states how it works, what it does under load, and where its limits are.

RoutingMulti-source → multi-target routingA single task can watch any number of source chats and deliver to any number of targets, with the primary pair mirrored and forum topics addressable per target.Read moreFilteringPer-task content rulesBlacklists, whitelists, link handling, regex gates, length limits and ordered replacements — evaluated cheapest-first, with per-source and per-target overrides.Read moreTransformationAI rewritingEnable or disable LLM rewriting per task, pick a provider, write your own prompts with version history, and keep forwarding even when the model is unreachable.Read moreOperationsObservability & log historyEvery delivery is attributable: the central logger stores queryable history with service, owner and correlation id, and dead letters can be replayed.Read moreReliabilityOrdered deliveryLease-based durable workers, per-channel delivery lanes that preserve post order, atomic cursor persistence, retry with jitter, and no duplicate sends.Read moreReliabilityDedup, replies & editsSHA-256 content and album fingerprinting kills duplicate forwards, reply chains stay linked, and edits and deletions propagate within a bounded window.Read moreInterfacesClients & interfacesTelegram bot UI, React dashboard behind a Rust Axum gateway, Flutter client and a REST/gRPC control plane — all enforced against the same contract fixtures.Read moreLocalizationMultilingual UIEnglish, Persian, Russian, Chinese, Portuguese, Uzbek, Indonesian, Spanish, French and Italian share one catalog with enforced 1:1 parity.Read moreOperationsDevOps CLI & upgrades29 command groups cover setup, tasks, logs, backups, docker, k8s and TLS, with a read-only validator for CI and an upgrade engine behind a health gate.Read more
Browse every capabilityRead the release notes

Capability parity across clients

One control plane, four interfaces. Verified, not assumed.

CapabilityBot UIWeb dashboardMobile appREST API
Channel / group / PV forwarding
Multi-source → multi-target tasks
Interactive login (phone / OTP / 2FA)
Content policy (cleaner, filters, regex)
Per-source / per-target policy overrides
AI rewriting + prompt templates
Deduplication, reply & edit sync
Delays, scheduling & auto-delete
Localization (10 languages)
Log explorer, stats & DLQ control
Live topology & health probing
Encrypted backup & migration (.atf)
Production Architecture

Multi-Service Resilient Forwarding Engine

Decoupled microservice topology with asynchronous non-blocking event loops, lease-based durable queues, and fail-closed tenant boundaries.

1. Ingestion

Telegram MTProto

Asynchronous client pool connects to DC2/DC4 via user sessions and bot tokens.

• Raw Updates
• Album Aggregator
• FloodWait Detector
2. Core Pipeline

Python Core (50051)

Strict stage-by-stage pipeline executing domain filtering, cleaning & shortcodes.

• [PIPELINE:NORMALIZE]
• [PIPELINE:ROUTE]
• [PIPELINE:FILTER]
• [PIPELINE:TRANSFORM]
3. Durable Queue

Lease Workers

Lease-based jobs with exponential backoff, jitter, and automatic account resume.

• Backpressure control
• Restricted bypass
• [PIPELINE:DELIVERED]
4. APIs & UI

Go API & Web (8080/8088)

High-performance REST API, interactive Telegram Bot UI, and React dashboard.

• Fail-Closed Auth
• Bot Manager FSM
• Logger (50052)
Storage Support:SQLite (WAL Mode with Busy Timeout) & PostgreSQL (Connection Pooling)
Multi-Tenant Isolation: Enforced Fail-Closed

Four surfaces, one contract

Drive it from wherever you already are

The bot, the dashboard, the mobile app and the API expose the same surface, and a contract gate fails the build when they drift apart.

Telegram bot

Button-driven panels and FSM wizards inside the chat

Web dashboard

React SPA served by the Rust gateway

Mobile app

Flutter client exposing the same system surface

REST API & CLI

102 routes · 29 CLI command groups

How the shared surface is kept honest

Honest status

What is done, what is partial, what is not built

Every row below is read from the repository's own feature catalog at build time — 18 catalogued capabilities with their completion condition and the entry points that implement them. Nothing on this page is asserted by the website.

Implemented14

14 of 18 catalogued capabilities

Partial2

2 of 18 catalogued capabilities

Planned2

2 of 18 catalogued capabilities

Implemented14 entries
  • Create forwarding ruleclients: web · bot · mobile · miniapp
  • Update forwarding rule (optimistic concurrency)
  • Pause/resume rule with durable queue semantics
  • Durable message forwarding pipeline
  • Branding hop (A -> C -> B) composed with every message transform
  • SHA-256 content fingerprint deduplication
  • Keyword-triggered reply add-on
  • Central Logger gRPC microservice
  • End-to-end correlation ID propagation
  • Web DevOps log explorer with live stream, filters, stats, purge
  • Field-aware secret redaction in logs/errors
  • Dead-letter queue inspect/replay/purge with tenant scoping
  • Telegram timeout classified as OUTCOME_UNCONFIRMED (never silent success/failure)
  • Service topology live health probing
Partial2 entries

  • Database query error/latency events

    Tracked in the catalog as PARTIALLY_IMPLEMENTED with an entry point that does not exist yet.

  • Transactional audit / outbox for business mutations

    Tracked in the catalog as PARTIALLY_IMPLEMENTED with an entry point that does not exist yet.

Planned2 entries

  • Slow-query threshold monitoring with configurable limits

    Tracked in the catalog as NOT_IMPLEMENTED with an entry point that does not exist yet.

  • Bounded-label metrics aggregation (per-feature latency, error rates)

    Tracked in the catalog as NOT_IMPLEMENTED with an entry point that does not exist yet.

Full status boardRelease notes

Generated from docs/feature_catalog.json on every build.

Derived from the source

See the whole system, then watch it run

The architecture below is computed from this repository on every build: 593source files, 524 modules, 1,869 import links and 23 runtime connections. Explore it as a dependency atlas, or orbit it in 3D and replay a real message path packet by packet.

  1. 01

    Telegram MTProto

    updates in, copies out

    0 files · 0 loc

  2. 02

    Ingestion & sessions

    albums, flood control

    28 files · 19,008 loc

  3. 03

    Pipeline & rules

    filter, clean, rewrite

    24 files · 9,604 loc

  4. 04

    Durable queue

    leases, retries, DLQ

    23 files · 10,833 loc

  5. 05

    REST control plane

    tenancy, logs, admin

    46 files · 11,580 loc

8

Subsystems — 187k lines of source

78

gRPC surface — 13 services · 141 messages

23

Verified connections — 5 checked absences

Open the system atlasReplay a message in 3DDependency atlas

Try it in the browser

See the transformation before you install

Paste a real post, toggle the cleaner, write a header and footer with shortcodes, and watch the delivery preview update instantly. Nothing leaves your browser.

⚡ Interactive Message Transformation Sandbox

Test AutoTelegramForward's cleaner engine, header/footer templates, and shortcode interpolation in real time.

2. Content Cleaner Options
[[ORIGIN_NAME]]
[[ORIGIN_NAME_URL]]
Transformed Output Preview
Telegram Message Preview0 chars
💡 Validated Shortcodes: [[ORIGIN_NAME]], [[ORIGIN_TEXT]], [[ORIGIN_POST_ID]], [[ORIGIN_USERNAME]], [[ORIGIN_POST_DATE]], [[ORIGIN_NAME_URL]], [[FORWARD_FROM_CHAT]].

Security

Isolation you can hand to a customer

Multi-tenant from the database up, with the failure mode chosen deliberately: an unproven scope denies instead of widening.

Fail-closed tenancy

Every read and write is scoped to the authenticated numeric Telegram user id across bot, dashboard, mobile, REST and gRPC. An unproven scope denies instead of widening.

Encrypted at rest

AES-256-GCM for sessions, bot tokens, AI keys and backup bundles. Secrets are field-aware redacted in log lines and error traces.

Private internals

Core and logger bind to internal interfaces only, and the internal gRPC surface requires a shared credential — it is not a public port.

Single-use login links

A dashboard link carries a random, hashed code with a ten-minute TTL that is burned on first use — never a session token — so a link that outlives its click is worthless.

Security modelHow account linking works

Documentation

Read the page you actually need

Every guide below is written against this repository's implementation, with commands and endpoints you can paste as they are.

Guide

Quickstart

From nothing to a verified stack and a first delivered message.

Guide

Create a task

Field by field: sources, targets, modes, policies and simulate.

Guide

Account linking

Login codes, the exchange endpoint, cooldowns and re-authentication.

Guide

AI rewriting

Providers, prompt templates, per-task toggles and failure behaviour.

Guide

API authentication

Tokens, bearer headers, rate limits, error codes and curl recipes.

Guide

Troubleshooting

Symptom, cause and fix — plus what to collect before asking for help.

Tutorials & recipesREST API referenceCLI reference

Coverage

Every Telegram message class, handled

Verified against the Telegram layer, including the awkward cases: albums, video notes and protected content.

  • Text Messages

    Formatting entities, emojis, links and styling preserved through the cleaner

    Full Support

  • Photos & Images

    Direct forward, clean copy without the forward tag, or download-and-reupload

    Full Support

  • Photo / Video Albums

    Media groups aggregated into one atomic job and delivered together

    Full Support

  • Videos & MP4

    Streamed upload with caption, thumbnail and quality preserved

    Full Support

  • Documents & PDFs

    Arbitrary documents and archives up to the Telegram size limit

    Full Support

  • Audio & Music

    MP3/M4A tracks with artist, title and cover metadata

    Full Support

  • Voice Messages

    OGG Opus voice notes with waveform and duration

    Full Support

  • Video Notes

    Round video messages forwarded as native video notes

    Full Support

  • Stickers & Animations

    Static WEBP, animated TGS and video WEBM stickers

    Full Support

  • Polls & Quizzes

    Standard polls, multiple answers and quiz mode, results preserved

    Full Support

  • Locations & Contacts

    Geolocations, venues and vCard contacts

    Full Support

  • Protected Content

    ChatForwardsRestricted channels re-uploaded through the media path

    Bypass Supported

Headers and footers, personalized

  • [[ORIGIN_TEXT]]Message body after the cleaner and policy passes
  • [[ORIGIN_NAME]]Title of the source channel or supergroup
  • [[ORIGIN_USERNAME]]Public @handle of the source channel
  • [[ORIGIN_USERID]]Numeric Telegram id of the sender
  • [[ORIGIN_POST_ID]]Original post id inside the source channel
  • [[ORIGIN_CHAT_ID]]Numeric id of the source channel
All twelve shortcodes

Ten languages, one catalog

  • English
  • Español
  • فارسی
  • Français
  • Bahasa Indonesia
  • Italiano
  • Português
  • Русский
  • Oʻzbekcha
  • 中文

Parity is enforced by an audit that fails the build when a key is missing in any language, and English is the only fallback.

How localization is verified

Answers

Questions people actually ask

What exactly is AutoTelegramForward?

A self-hosted Telegram message routing platform. A task watches one or more source chats and delivers to one or more targets, applying per-task content rules, templates and an optional AI rewriting pass on the way. It ships as four microservices you run yourself.

Can one task read several channels and post to several destinations?

Yes. Sources and targets are lists, so a single task can route many channels into many destinations. The primary source and target are derived from the lists and always kept consistent.

How do I link my Telegram account to the dashboard?

Ask the bot for the dashboard. It mints a single-use login code, the link opens the dashboard once, and the code is burned on first use with a ten-minute TTL. No password is created and no Telegram id is ever accepted in the exchange.

Do I need an AI provider to use it?

No. AI rewriting is an optional per-task toggle. Without it the cleaner, filters and templates still work exactly the same, and a provider that is down never blocks delivery.

How do I install it?

Clone the repository and run ./scripts/setup.sh on Linux or macOS, python scripts\bootstrap.py on Windows, or the zero-prerequisite installers. Each path ends in the same guided wizard that builds the stack and proves every service is serving.

Is it multi-tenant?

Yes, and isolation is fail-closed: every read and write is scoped to the authenticated numeric Telegram user id, across the bot, dashboard, mobile app, REST API and gRPC services.

How do I know which features are actually finished?

The status board is generated from the repository's own feature catalog on every build: 14 implemented, 2 partial and 2 planned. Nothing is presented as done unless the catalog says so.

Which Telegram content types are supported?

Text, photos, albums, video, documents, audio, voice notes, video notes, stickers, polls, locations, contacts and copy-protected content that is re-uploaded rather than forwarded.

Read the full FAQ

Ship your routing in one command

The setup wizard detects your platform, validates every answer, builds the four services and then proves each one is serving before it says done.

Installation guideCLI reference

MIT licensed · 4 services · 10 languages · 78 gRPC methods · 102 REST routes