Telegram als vollwertiger Client direkt in Home Assistant — mit Chat-UI, REST-API und Webhook-Support.

Funktionen

MTProto-Login: Telefonnummer + SMS/App-Code, 2FA unterstützt
Web-UI: Chat-Liste, Konversationen, Nachrichten senden/empfangen direkt in der HA-Sidebar
Fotos: Empfangene Bilder anzeigen (optional, siehe download_media)
Datei-Upload: 📎-Button zum Senden von Bildern und Dokumenten aus dem Browser (max. 64 MB)
Chat-Filter: Tabs „Alle / Privat / Gruppen / Kanäle / Bots" in der Sidebar; Typ-Avatare 👥 📢 🤖
Chat-Export: 💾-Button im Chat-Header — exportiert alle Nachrichten als HTML-Datei (Bilder inline eingebettet)
Nachrichten löschen: Nachricht für alle entfernen (Hover → ✕)
Lesebestätigungen: ✓ gesendet (grau), ✓✓ gelesen (blau) bei eigenen Nachrichten
Ungelesene-Badge: Blauer Punkt in der Sidebar bei neuen Nachrichten
Emoji-Tastatur: 😊-Button in der Eingabe
Sprachauswahl: 🌐 DE / 🌐 EN Button in der Topbar — Sprache wird im Browser gespeichert
Persistente Session: Kein erneutes Anmelden nach Neustart
REST-API: Nachrichten aus Automatisierungen heraus senden
Webhook: Eingehende Nachrichten an eine URL weiterleiten

Einrichtung

1. API-Credentials besorgen

Auf my.telegram.org einloggen
→ API development tools
App erstellen (Name und Plattform beliebig)
App api_id und App api_hash notieren

2. Add-on konfigurieren und starten

Nach dem Start erscheint ein Code-Eingabefeld in der Web-UI. Telegram sendet einen Code per App-Benachrichtigung oder SMS — diesen Code eingeben, fertig.

Bei aktivierter 2-Faktor-Authentifizierung wird danach das Cloud-Passwort abgefragt.

Konfiguration

Option	Standard	Beschreibung
`api_id`	—	Numerische API-ID von my.telegram.org
`api_hash`	—	API-Hash von my.telegram.org
`phone_number`	—	Telefonnummer mit Ländervorwahl, z.B. `+4917612345678`
`dark_mode`	`true`	`true` = dunkles Theme, `false` = helles Theme
`download_media`	`false`	Empfangene Fotos automatisch herunterladen und anzeigen (funktioniert nur zuverlässig bei neu eingehenden Nachrichten, nicht für historische Nachrichten)
`fetch_messages_limit`	`50`	Nachrichten die beim ersten Öffnen eines Chats geladen werden (max. 300)
`webhook_incoming`	—	URL für eingehende Nachrichten (HA-Webhook-Trigger)
`debug_mode`	`false`	Ausführliches Logging für die Fehlersuche
`ha_notifications`	`false`	Persistente HA-Benachrichtigung bei neuen Nachrichten (ein pro Chat, wird überschrieben)
`ha_notifications_privacy`	`false`	Nur „Telegram / Neue Nachricht" anzeigen — kein Absender, kein Inhalt
`ha_notifications_skip_bots`	`false`	Keine HA-Benachrichtigung für Nachrichten von Bots

HA-Benachrichtigungen einrichten

Einfach ha_notifications aktivieren — sonst nichts. Das Add-on nutzt automatisch den vom Supervisor bereitgestellten Zugriff auf die Home-Assistant-API (homeassistant_api); ein manuell erstellter Access Token ist nicht mehr nötig.

REST-API

GET  /api/status                     → { status, name, id }
GET  /api/chats                      → [ { id, name, lastMsg, lastTime } ]
GET  /api/messages/:chatId           → [ { id, body, type, timestamp, fromMe } ]
POST /api/send                       → { to, message }
POST /api/send-media                 → multipart/form-data: file, to, caption (optional)
GET  /api/export/:chatId             → Chat als HTML-Datei herunterladen
DELETE /api/messages/:chatId/:msgId  → Nachricht für alle löschen
POST /api/submit-code                → { code } — Login-Code einreichen
POST /api/submit-password            → { password } — 2FA-Passwort einreichen
POST /api/logout                     → Abmelden und Session löschen

Nachricht senden

curl -X POST http://<HA-IP>:17778/api/send \
  -H "Content-Type: application/json" \
  -d '{"to": "123456789", "message": "Hallo aus HA!"}'

to ist die numerische Chat-ID (aus /api/chats → Feld id).

Webhook-Format (eingehende Nachrichten)

{
  "from": "123456789",
  "name": "Max Mustermann",
  "message": "Nachrichtentext",
  "timestamp": 1716123456000
}

HA-Automatisierung (Beispiel)

Nachricht senden aus einer Automatisierung

configuration.yaml:

rest_command:
  telegram_send:
    url: http://localhost:17778/api/send
    method: POST
    content_type: application/json
    payload: '{"to": "{{ to }}", "message": "{{ message }}"}'

Automatisierung:

action:
  - service: rest_command.telegram_send
    data:
      to: "123456789"
      message: "Bewegung erkannt!"

Webhook — auf eingehende Nachrichten reagieren

1. Add-on konfigurieren:

webhook_incoming: http://homeassistant:8123/api/webhook/telegram

2. Automatisierung in HA anlegen:

Wichtig: local_only: false setzen — Anfragen aus dem Docker-Netzwerk werden sonst blockiert.

Benachrichtigung bei jeder eingehenden Nachricht:

alias: Telegram eingehend
triggers:
  - trigger: webhook
    webhook_id: telegram
    allowed_methods:
      - POST
    local_only: false
actions:
  - action: notify.persistent_notification
    data:
      title: "Telegram von {{ trigger.json.name }}"
      message: "{{ trigger.json.message }}"

Auf ein Schlüsselwort reagieren (z.B. „Licht an"):

alias: Telegram Licht steuern
triggers:
  - trigger: webhook
    webhook_id: telegram
    local_only: false
conditions:
  - condition: template
    value_template: "{{ 'licht an' in (trigger.json.message | lower) }}"
actions:
  - action: light.turn_on
    target:
      entity_id: light.wohnzimmer

Verfügbare Variablen im Webhook:

Variable	Inhalt
`trigger.json.from`	Absender (Chat-ID, z.B. `123456789`)
`trigger.json.name`	Name des Absenders
`trigger.json.message`	Nachrichtentext
`trigger.json.timestamp`	Unix-Zeitstempel (Millisekunden)

Updates

Dieses Add-on wird von Home Assistant lokal gebaut — es gibt kein vorgefertigtes Image. Bei jedem Build wird automatisch die neueste kompatible Version von GramJS installiert.

Falls Telegram sein Protokoll ändert und das Add-on nicht mehr funktioniert:

Einstellungen → Add-ons → Telegram → Neu aufbauen

Das reicht aus, um die aktuelle Bibliotheksversion zu laden.

Hinweise

Basiert auf GramJS (offizielle MTProto-Implementierung für JavaScript)
Session wird in /data/session.txt gespeichert und überlebt Neustarts
Chats und Nachrichten werden in /data/chats.json und /data/messages.json gespeichert
Medien werden in /data/media/ gespeichert
Das Sidebar-Logo (phu:telegram) erfordert custom-brand-icons

→ Changelog

Telegram (English)

Telegram as a full client directly in Home Assistant — with chat UI, REST API and webhook support.

Features

MTProto login: Phone number + SMS/app code, 2FA supported
Web UI: Chat list, conversations, send/receive messages directly in the HA sidebar
Photos: Display received images (optional, see download_media)
File upload: 📎 button to send images and documents from the browser (max. 64 MB)
Chat filter: Tabs "All / Private / Groups / Channels / Bots" in the sidebar; type avatars 👥 📢 🤖
Chat export: 💾 button in the chat header — exports all messages as an HTML file (images embedded inline)
Delete messages: Remove a message for everyone (hover → ✕)
Read receipts: ✓ sent (grey), ✓✓ read (blue) on outgoing messages
Unread badge: Blue dot in the sidebar for new messages
Emoji keyboard: 😊 button in the input field
Language switcher: 🌐 DE / 🌐 EN button in the topbar — language is saved in the browser
Persistent session: No re-login after restart
REST API: Send messages from automations
Webhook: Forward incoming messages to a URL

Setup

1. Get API credentials

Log in at my.telegram.org
→ API development tools
Create an app (name and platform are arbitrary)
Note the App api_id and App api_hash

2. Configure and start the add-on

After starting, a code input field appears in the Web UI. Telegram sends a code via app notification or SMS — enter this code and you're done.

If two-factor authentication is enabled, the cloud password will be requested afterwards.

Configuration

Option	Default	Description
`api_id`	—	Numeric API ID from my.telegram.org
`api_hash`	—	API hash from my.telegram.org
`phone_number`	—	Phone number with country code, e.g. `+4917612345678`
`dark_mode`	`true`	`true` = dark theme, `false` = light theme
`download_media`	`false`	Automatically download and display received photos (only works reliably for newly incoming messages, not for historical ones)
`fetch_messages_limit`	`50`	Messages loaded when a chat is first opened (max. 300)
`webhook_incoming`	—	URL for incoming messages (HA webhook trigger)
`debug_mode`	`false`	Verbose logging for troubleshooting
`ha_notifications`	`false`	Persistent HA notification for new incoming messages (one per chat, overwritten by newer messages)
`ha_notifications_privacy`	`false`	Show only "Telegram / New message" — no sender name, no content
`ha_notifications_skip_bots`	`false`	Skip HA notifications for messages from bots

Setting up HA notifications

Just enable ha_notifications — nothing else. The add-on automatically uses the Home Assistant API access provided by the Supervisor (homeassistant_api); a manually created access token is no longer required.

REST API

GET  /api/status                     → { status, name, id }
GET  /api/chats                      → [ { id, name, lastMsg, lastTime } ]
GET  /api/messages/:chatId           → [ { id, body, type, timestamp, fromMe } ]
POST /api/send                       → { to, message }
POST /api/send-media                 → multipart/form-data: file, to, caption (optional)
GET  /api/export/:chatId             → Download chat as HTML file
DELETE /api/messages/:chatId/:msgId  → Delete message for everyone
POST /api/submit-code                → { code } — Submit login code
POST /api/submit-password            → { password } — Submit 2FA password
POST /api/logout                     → Log out and delete session

Send a message

curl -X POST http://<HA-IP>:17778/api/send \
  -H "Content-Type: application/json" \
  -d '{"to": "123456789", "message": "Hello from HA!"}'

to is the numeric chat ID (from /api/chats → field id).

Webhook payload (incoming messages)

{
  "from": "123456789",
  "name": "John Doe",
  "message": "Message text",
  "timestamp": 1716123456000
}

HA Automation (example)

Send a message from an automation

configuration.yaml:

rest_command:
  telegram_send:
    url: http://localhost:17778/api/send
    method: POST
    content_type: application/json
    payload: '{"to": "{{ to }}", "message": "{{ message }}"}'

Automation:

action:
  - service: rest_command.telegram_send
    data:
      to: "123456789"
      message: "Motion detected!"

Webhook — react to incoming messages

1. Configure the add-on:

webhook_incoming: http://homeassistant:8123/api/webhook/telegram

2. Create an automation in HA:

Important: Set local_only: false — requests from the Docker network are otherwise blocked.

Notification on every incoming message:

alias: Telegram incoming
triggers:
  - trigger: webhook
    webhook_id: telegram
    allowed_methods:
      - POST
    local_only: false
actions:
  - action: notify.persistent_notification
    data:
      title: "Telegram from {{ trigger.json.name }}"
      message: "{{ trigger.json.message }}"

React to a keyword (e.g. "lights on"):

alias: Telegram control lights
triggers:
  - trigger: webhook
    webhook_id: telegram
    local_only: false
conditions:
  - condition: template
    value_template: "{{ 'lights on' in (trigger.json.message | lower) }}"
actions:
  - action: light.turn_on
    target:
      entity_id: light.living_room

Available variables in the webhook:

Variable	Content
`trigger.json.from`	Sender (chat ID, e.g. `123456789`)
`trigger.json.name`	Sender name
`trigger.json.message`	Message text
`trigger.json.timestamp`	Unix timestamp (milliseconds)

Updates

This add-on is built locally by Home Assistant — there is no pre-built image. Every build automatically installs the latest compatible version of GramJS.

If Telegram changes its protocol and the add-on stops working:

Settings → Add-ons → Telegram → Rebuild

That's all it takes to pull the current library version.

Notes

Based on GramJS (official MTProto implementation for JavaScript)
Session is stored in /data/session.txt and survives restarts
Chats and messages are stored in /data/chats.json and /data/messages.json
Media files are stored in /data/media/
The sidebar icon (phu:telegram) requires custom-brand-icons

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Telegram

Funktionen

Einrichtung

1. API-Credentials besorgen

2. Add-on konfigurieren und starten

Konfiguration

HA-Benachrichtigungen einrichten

REST-API

Nachricht senden

Webhook-Format (eingehende Nachrichten)

HA-Automatisierung (Beispiel)

Nachricht senden aus einer Automatisierung

Webhook — auf eingehende Nachrichten reagieren

Updates

Hinweise

Telegram (English)

Features

Setup

1. Get API credentials

2. Configure and start the add-on

Configuration

Setting up HA notifications

REST API

Send a message

Webhook payload (incoming messages)

HA Automation (example)

Send a message from an automation

Webhook — react to incoming messages

Updates

Notes

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Telegram

Funktionen

Einrichtung

1. API-Credentials besorgen

2. Add-on konfigurieren und starten

Konfiguration

HA-Benachrichtigungen einrichten

REST-API

Nachricht senden

Webhook-Format (eingehende Nachrichten)

HA-Automatisierung (Beispiel)

Nachricht senden aus einer Automatisierung

Webhook — auf eingehende Nachrichten reagieren

Updates

Hinweise

Telegram (English)

Features

Setup

1. Get API credentials

2. Configure and start the add-on

Configuration

Setting up HA notifications

REST API

Send a message

Webhook payload (incoming messages)

HA Automation (example)

Send a message from an automation

Webhook — react to incoming messages

Updates

Notes