goauthentik / goauthentik/authentik
Add native Telegram support: notification transport + authenticator stage
- Dominant language
- Python
- Stars
- 25.6k
- Forks
- 2k
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 644
Description
### Is your feature request related to a problem?
Right now, there's no built-in way to deliver messages to Telegram — neither for event notifications nor for MFA/OTP codes. Both use cases currently rely on the same workaround: setting up a generic Webhook transport (or repurposing the SMS authenticator stage) and building a separate relay service to translate the payload into a Telegram Bot API call. This means Telegram support only exists through third-party infrastructure that every self-hoster has to build and maintain themselves.
### Describe the solution you'd like
Two related additions:
1. Notification transport — a built-in "Telegram" transport type (similar to the existing Slack transport), where the admin provides a Bot Token and Chat ID, and Authentik sends event notifications directly via the Telegram Bot API (`sendMessage`), without any external relay. This direction is outbound-only and fits the existing transport model directly.
2. Authenticator stage — a native Telegram option for delivering MFA/verification codes, as an alternative to (or a proper mode of) the existing SMS authenticator stage. This direction also needs to receive an inbound message during enrollment (e.g. the user messages the bot, and Authentik links the resulting chat ID to their account). For the inbound part specifically, a webhook-based approach (Telegram's `setWebhook`, pushing updates to a publicly reachable Authentik endpoint) fits Authentik's architecture better than long polling (`getUpdates`). Polling would require a persistent, always-running process to continuously query Telegram's API, which doesn't map well onto Authentik's existing worker model (Celery tasks that run on schedule/event rather than holding an open loop). A webhook endpoint is also consistent with the pattern Authentik already has for the notification transport, just in the reverse direction — Telegram pushing in, instead of Authentik pushing out.
### Describe alternatives that you've considered
* Generic Webhook transport + a self-hosted relay to reformat the payload — works for notifications, but is a workaround requiring extra infrastructure and maintenance.
* Repurposing the SMS authenticator's generic webhook provider to send codes via Telegram instead of SMS — works, but is a workaround too: it means treating a chat ID as a "phone number" and requires custom prompts to explain that to non-technical users, with no first-class UX for it.
* Slack transport — not usable as-is for notifications, since Telegram doesn't accept Slack's payload format.
* Long polling for the authenticator's inbound enrollment step — technically simpler to prototype, but a poor architectural fit given Authentik's task-based worker model, and harder to run reliably at scale.
### Additional context
Telegram (and similar chat-based messengers) is a common channel for self-hosted/homelab setups, both for notifications and for delivering auth codes. This need keeps surfacing — see #6732, where a user relies on the SMS authenticator's generic webhook interface plus an external flow tool to deliver codes via Telegram and Signal, and #17312, where a user has a working Telegram notification webhook but hits a documentation/API gap trying to enrich the payload with more event context — both illustrate that people are already stretching the existing generic-webhook primitives to get chat-app delivery working.
Notably, Authentik already added a Telegram source for social login in release 2025.10 (login via the Telegram Login Widget / OAuth), which was one of the most-requested integrations at the time. This shows there's already precedent and working infrastructure in the codebase for talking to Telegram's APIs, which should lower the lift for the transport and authenticator additions proposed here.
Contributor guide
Research direction
Start by reading the existing Slack notification transport and SMS authenticator stage, then compare them with the Telegram source added in release 2025.10. Confirm how Celery workers and webhook endpoints are used before assessing the requested additions. Done means outbound sendMessage notifications and inbound webhook-based enrollment and code delivery work without relay infrastructure.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- api, authentication, backend-api-design
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100