TelegramBot: Unterschied zwischen den Versionen

TelegramBot
Zweck / Funktion
	Senden und Empfangen von Nachrichten (Text und Fotos) mit dem freien Messagingdienst Telegram
Allgemein
Typ	Gerätemodul
Details
Dokumentation	EN / DE; Thema
Support (Forum)	Unterstützende Dienste
Modulname	50_TelegramBot.pm
Ersteller	Viegener (Forum / Wiki)
	Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref!

Version vom 19. Dezember 2015, 22:02 Uhr

Das TelegramBot-Modul ermöglicht das Senden und Empfangen von Nachrichten über den Telegram-instant messaging Dienst (https://telegram.org/). Es entsteht eine Möglichkeit Benachrichtungen aus Fhem zu versenden, zum Beispiel Alarmmeldungen. Ausserdem können auch Kommandos über Telegram an Fhem gesendet werden um Steuerungsbefehle in Fhem auszulösen.

Das TelegramBot-Modul benötigt keine Zusatzsoftware auf dem Fhem-Server (anders als die Variante Telegram), sondern verwendet das TelegramBot-API über https-Aufrufe.

Über Telegram Instant Messaging

Telegram-IDs und Versand/Empfang von Nachrichten sind kostenfrei. Clients sind für gängige Smartphonesysteme erhältlich (iOS iPhone und Tablet, Android, Windows Phone) und können auch aus dem WebBrowser verwendet werden. Es gibt auch einen Kommandozeilen-Client für Linux, der die Grundlage dieses Moduls darstellt. Mehrfachanmeldungen, auch parallel mit verschiedenen Geräten (z.B. Tablet und Smartphone), sind möglich. Gruppenchats und Chats mit End-2-End-Verschlüsselung werden ebenfalls unterstützt.

Für die Unterstützung von WhatsApp siehe Modul yowsup.

Features

Unterstützt werden:

Versand von Textnachrichten
Versand von Bildern
Empfang von Textnachrichten von beliebigen Kontakten
Kommandos in Fhem über Telegram-Nachrichten von aussen auslösen

Eine detaillierte Beschreibung des Moduls ist im Fhem Forum und in der (englischen) Dokumentation zum Modul in der Commandref diesem Diskussionsthread zu finden. Seit Oktober 2015 wird das Modul offiziell über Fhem-Update verteilt.

Die jeweils aktuellste Entwicklungs-Version des Moduls ist in Github 50_TelegramBot.pm verfügbar.

Hinweise zum Betrieb mit Fhem

Achtung: Dieses Authtoken ist die einzige Authentifizierung für den Bot und sollte deshalb nicht aus der Hand gegeben werden. Die verwendeten Urls sind deshalb auch in den Log-Files nicht enthalten, da diese das Authtoken in Klartext enthalten. Auch im Forum sollte dieses Token nicht aufgenommen werden.

Für die Anlage eines TelegramBot Devices in Fhem ist ein Authtoken erforderlich. Dieses Token wird über Anlegen eines neuen Bots im BotFather erzeugt. Dort mit dem Telegram-Befehl /newbot einen neuen Bot anlegen und mit einem Namen versehen. Hinweis: Die Namen für Bots müssen auf "Bot" enden.

Das Anlegen eines TelegramBot devices erfolgt durch die Angabe dieses Tokens:

define <name> TelegramBot <token>

Beispiel: define teleBot TelegramBot 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw

Das Empfangen von Nachrichten (polling) erfordert die Einstellung des Attributes pollingTimeout auf einen Wert der grösser als Null ist. Beim Wert 0 oder ohne Setzen des Attributes findet kein Polling und damit auch kein Empfang statt.

Der TelegramBot kann erst dann Nachrichten an einen telegram user schicken, wenn dieser zuerst an den telegram bot eine Nachricht gesendet hat.

Tipps

Privacyeinstellungen

Damit der TelegramBot auch Meldungen in Gruppen sieht, müssen über den BotFather die Privacy-Einstellungen geändert werden.

Kontakte

Der Bot merkt sich die bereits bekannten Kontakte im Reading Contacts. Dabei werden die einzelnen Kontakte jeweils als 3-teilige Einträge bestehend aus UserID, Vor- und Nachname des Benutzers (mit _ verbunden) und dem Username (mit vorangestelltem @).

Beispiel: 123456:Ralf_Mustermann:@ralf

Verschiedene Einträge werden durch Leerzeichen getrennt.

Man kann die Kontakte auch manuell überschreiben (z.B. wenn das Reading fehlerhaft oder verloren sein sollte). Dazu gibt es den Set-Befehl replaceContacts. Dieser nimmt die Kontakte ebenfalls in der gleichen Form wie oben beschrieben entgegen.

Die Kontaktliste wird ansonsten nur durch den Empfang von Nachrichten erweitert, da es im TelegramBot-API keine Möglichkeit gibt Kontaktdaten von Telegram abzufragen (siehe auch pollingTimeout)

Reset

Es ist möglich den Bot im laufenden Betrieb zurückzusetzen (Set-Befehl reset). Dabei werden noch nicht abgeschlossene Übetragungen entfernt und die internen Zustände des Devices zurückgesetzt.

Beispielszenarien

Benachrichtigungen über Ereignisse

Das einfachste Szenario für die Integration von Messaging-Diensten mit Fhem ist zur Benachrichtigung über Ereignisse. Diese Funktion kann zum Beispiel verwendet werden, um über einen erfolgten Neustart von Fhem zu informieren:

define notify_fhem_reload notify global:INITIALIZED set telebotdevice message fhem newly started - just now !

In diesem Beispiel wird der Nachrichtentext "fhem newly started - just now !" an den als default eingestellten Kontakt (Attribut: defaultPeer) gesendet, sobald Fhem neu gestartet wurde. Natürlich kann man auch beliebige andere Benachrichtigungen einführen.

Versand von Bildern

Es ist auch möglich Bilder auf dem Fhem-Server, die zum Beispiel von einer Kamera oder einem Wettermodul stammen über Telegram zu versenden. So wäre es z.B. möglich jeweils morgens die aktuelle Wetterkarte zu erhalten.

ACHTUNG: TelegramBot verwendet das HTTPUtils-Modul zur Kommunikation mit dem TelegramBot-API. Erst mit der Version, die seit 22.10.2015 ([r9576] HttpUtils.pm: Async write for POST Requests Fhem-Forum) verteilt wird, erlaubt auch den Transfer grösserer Bilder. Die Grenze liegt ansonsten bei ca. 14kb auf Raspberries (Plattformspezifische Grenze).

define notify_fhem_reload notify wetter:report set telebotdevice sendPhoto /opt/fhem/wetter.jpg

Bei Erreichen des entsprechenden Status am Wetter-Modul wird ein Image über Telegram versendet. Hier sind lokale Pfade (relativ zu fhem) oder absolute Pfade wie oben möglich.

Versand von Emojis (Smileys)

Es ist auch möglich Emojis mit den (Text-)Nachrichten zu versenden. Die entsprechenden (Unicode-)Zeichen werden einfach direkt mit in den Text der Nachricht aufgenommen. Um das zu vereinfachen kann man das einfach per Copy und Paste von dieser Seite

http://apps.timwhitlock.info/emoji/tables/unicode (Spalte "Native")

übernehmen und mit der Nachricht verschicken.

Die Emojis können auch empfangen werden und werden so auch in FHEM / FHEMWeb angezeigt. Plattformspezifische (z.B. von iOS oder Android) Emojis werden dabei nicht unterstützt (gerade mit iOS sind viele neue farbige Emojis hinzugekommen, die wohl leider nur auf Apple-devices funktionieren).

Kommandos auslösen

Ein wichtiges Szenario ist die Möglichkeit Kommandos in Fhem ausführen zu können, ohne einen Zugang durch die Firewall einrichten zu müssen. Dazu ist die Definition eines Schlüsselwortes (Attribut: "cmdKeyword")erforderlich, mit dem man die Nachrichten beginnen muss, damit der TelegramBot die Kommandos erkennt.

attr telebotdevice cmdKeyword doit

Somit kann man dann durch Nachrichten die mit "doit" beginnen Kommandos an Fhem senden, die ähnlich wie im Kommandoeingabefeld von Fhemweb dann von Fhem ausgeführt werden. Das Ergebnis der Ausführung wird zurück an den Sender (und an den definierten defaultPeer) geschickt.

Somit können nicht nur Aktionen angestossen werden, sondern auch Infos abgefragt werden.

Beispiele

dofhem set schalter on

dofhem list telegrambot

Achtung: Bei den Kommandos sollten man unbedingt das Attribut "cmdRestrictedPeer" setzen, damit nicht jeder Kommandos auf dem Fhem-Server ausführen kann. Dazu sollten die BenutzerIDs der erlaubten Benutzer (durch Leerzeichen getrennt angeben). Da Benutzernamen selber vergeben werden und nicht unbedingt eindeutig sind, sollten hier auch NUR BenutzerIDs verwendet werden.

Favoriten für Kommandos anlegen

Grundidee bei den Favoriten ist, dass man lange Befehle, die man häufig braucht auf "Kurzwahl" legt.

Beispiel-Kommandos wie z.B. set TYPE=ROLLADEN pos 100 und set TYPE=ROLLADEN pos 0, die man immer wieder braucht. Um nicht jedes mal dieses Kommando eintippen zu müssen auf dem Smartphone, kann man auch dafür Favoriten anlegen.

Dazu gibt man erst mal die beiden Kommandos getrennt durch Semikolon im Attribut favorites an:

attr telegrambotdevice favorites set TYPE=ROLLADEN pos 100;set TYPE=ROLLADEN pos 0

Um die Favorites jetzt ausführen zu können braucht man noch ein Schlüsselwort dafür. Nehmen wir mal an man möchte die Favoriten mit /short ausführen können. Dazu muss dann das Attribut "cmdFavorites" setzen

attr telegrambotdevice cmdFavorites /short

Wenn man nun im Telegram Client /short 1 an den Bot schickt führt der Bot den ersten Favoriten aus und das Ergebnis der Ausführung wird zurückgeschickt.

Ausserdem kann man im Telegram Client /short an den Bot schicken, dann antwortet der Bot mit

Favorites

1
set TYPE=ROLLADEN pos 100
2
set TYPE=ROLLADEN pos 0

Links

Github Repository für die Telegram-Fhem Entwicklung: https://github.com/viegener/Telegram-fhem
Infos zum Telegram BotFather: https://core.telegram.org/bots#botfather

Source code für das 50_TelegramBot.pm-Modul: https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm
Source code für das modifizierte HTTPUtils-Modul zur Übertragung grosser Bilder: https://github.com/viegener/Telegram-fhem/blob/master/HttpUtils.pm

Forum-Thread in dem das Modul vorgestellt wurde Fhem-Forum
Telegram messaging system https://telegram.org/
TelegramBot API https://core.telegram.org/bots/api

--Viegener (Diskussion) 22:49, 11. Okt. 2015 (CEST)

@@ Zeile 29: / Zeile 29: @@
 * Versand von Bildern
 * Empfang von Textnachrichten von beliebigen Kontakten
-* Kommandos in Fhem über telegram-Nachrichten von aussen auslösen
+* Kommandos in Fhem über Telegram-Nachrichten von aussen auslösen
 Eine detaillierte Beschreibung des Moduls ist im Fhem Forum und in der (englischen) Dokumentation zum Modul in der Commandref diesem  {{Link2Forum|Topic=38328|LinkText=Diskussionsthread}} zu finden. Seit Oktober 2015 wird das Modul offiziell über Fhem-Update verteilt.
@@ Zeile 39: / Zeile 39: @@
 }}
-Für die Anlage eines TelegramBot Devices in Fhem ist ein Authtoken erforderlich. Dieses Token wird über Anlegen eines neuen Bots im [https://core.telegram.org/bots#botfather Botfather] erzeugt. Dort mit dem Telegram-Befehl <code>/newbot</code> einen neuen Bot anlegen und mit einem Namen versehen. Hinweis: Die Namen für Bots müssen auf "Bot" enden.
+Für die Anlage eines TelegramBot Devices in Fhem ist ein Authtoken erforderlich. Dieses Token wird über Anlegen eines neuen Bots im [https://core.telegram.org/bots#botfather BotFather] erzeugt. Dort mit dem Telegram-Befehl <code>/newbot</code> einen neuen Bot anlegen und mit einem Namen versehen. Hinweis: Die Namen für Bots müssen auf "Bot" enden.
 Das Anlegen eines TelegramBot devices erfolgt durch die Angabe dieses Tokens:
@@ Zeile 56: / Zeile 56: @@
 === Privacyeinstellungen ===
-Damit der TelegramBot auch Meldungen in Gruppen sieht, müssen über den botfather die prviacy-Einstellungen geändert werden.
+Damit der TelegramBot auch Meldungen in Gruppen sieht, müssen über den BotFather die Privacy-Einstellungen geändert werden.
 === Kontakte ===
-Der Bot merkt sich die bereits bekannten Kontakte im Reading <code>Contacts</code>. Dabei werden die einzelnen Kontakte jeweils als 3-teilige Einträge bestehend aus userid, Vor- und Nachname des Benutzers (mit _ verbunden) und dem usernamen (mit vorangestelltem @).
+Der Bot merkt sich die bereits bekannten Kontakte im Reading <code>Contacts</code>. Dabei werden die einzelnen Kontakte jeweils als 3-teilige Einträge bestehend aus UserID, Vor- und Nachname des Benutzers (mit _ verbunden) und dem Username (mit vorangestelltem @).
 Beispiel: <code>123456:Ralf_Mustermann:@ralf</code>
@@ Zeile 68: / Zeile 68: @@
 Man kann die Kontakte auch manuell überschreiben (z.B. wenn das Reading fehlerhaft oder verloren sein sollte). Dazu gibt es den Set-Befehl <code>replaceContacts</code>. Dieser nimmt die Kontakte ebenfalls in der gleichen Form wie oben beschrieben entgegen.
-Die Kontaktliste wird ansonsten nur durch den Empfang von Nachrichten erweitert, da es im TelegramBot-API keine Möglichkeit gibt Kontaktdaten von telegram abzufragen (sieje auch pollingTimeout)
+Die Kontaktliste wird ansonsten nur durch den Empfang von Nachrichten erweitert, da es im TelegramBot-API keine Möglichkeit gibt Kontaktdaten von Telegram abzufragen (siehe auch pollingTimeout)
 === Reset ===
-Es ist möglich den Bot im laufenden Betrieb zurückzusetzen (Set-Befehl <code>reset</code>). Dabei werden noch nicht abgeschlossene Übetragungen entfernt und die internen Zustände des devices zurückgesetzt.
+Es ist möglich den Bot im laufenden Betrieb zurückzusetzen (Set-Befehl <code>reset</code>). Dabei werden noch nicht abgeschlossene Übetragungen entfernt und die internen Zustände des Devices zurückgesetzt.
@@ Zeile 95: / Zeile 95: @@
 <code>define notify_fhem_reload notify wetter:report set telebotdevice sendPhoto /opt/fhem/wetter.jpg</code>
-Bei Erreichen des entsprechenden Status am wetter-Modul wird ein Image über telegram versendet. Hier sind lokale Pfade (relativ zu fhem) oder absolute Pfade wie oben möglich.
+Bei Erreichen des entsprechenden Status am Wetter-Modul wird ein Image über Telegram versendet. Hier sind lokale Pfade (relativ zu fhem) oder absolute Pfade wie oben möglich.
-=== Versand von Emojis (smileys) ===
+=== Versand von Emojis (Smileys) ===
-Es ist auch möglich emojis mit den (Text-)Nachrichten zu versenden. Die entsprechenden (Unicode-)Zeichen werden einfach direkt mit in den text der Nachricht aufgenommen. Um das zu vereinfachen kann man das einfach per Copy und paste von dieser Seite
+Es ist auch möglich Emojis mit den (Text-)Nachrichten zu versenden. Die entsprechenden (Unicode-)Zeichen werden einfach direkt mit in den Text der Nachricht aufgenommen. Um das zu vereinfachen kann man das einfach per Copy und Paste von dieser Seite
-http://apps.timwhitlock.info/emoji/tables/unicode (Spalte native)
+http://apps.timwhitlock.info/emoji/tables/unicode (Spalte "Native")
 übernehmen und mit der Nachricht verschicken.
@@ Zeile 124: / Zeile 124: @@
 <code>dofhem list telegrambot</code>
-{{Randnotiz|RNTyp=Warn|RNText=Achtung: Bei den Kommandos sollten man unbedingt das Attribut "cmdRestrictedPeer" setzen, damit nicht jeder Kommandos auf dem Fhem-Server ausführen kann. Dazu sollten die Benutzerids der erlaubten Benutzer (durch Leerzeichen getrennt angeben). Da Benutzernamen selber vergeben werden und nicht unbedingt eindeutig sind, sollten hier auch NUR Benutzerids verwendet werden.
+{{Randnotiz|RNTyp=Warn|RNText=Achtung: Bei den Kommandos sollten man unbedingt das Attribut "cmdRestrictedPeer" setzen, damit nicht jeder Kommandos auf dem Fhem-Server ausführen kann. Dazu sollten die BenutzerIDs der erlaubten Benutzer (durch Leerzeichen getrennt angeben). Da Benutzernamen selber vergeben werden und nicht unbedingt eindeutig sind, sollten hier auch NUR BenutzerIDs verwendet werden.
 }}
 === Favoriten für Kommandos anlegen ===
-Grundidee bei den Favoriten ist, dass man lange Befehle, die man haeufig braucht auf "Kurzwahl" legt.
+Grundidee bei den Favoriten ist, dass man lange Befehle, die man häufig braucht auf "Kurzwahl" legt.
-Beispiel-Kommandos wie z.B. <code>set TYPE=ROLLADEN pos 100</code> und <code>set TYPE=ROLLADEN pos 0</code>, die man immer wieder braucht. Um nicht jedesmal dieses Kommando eintippen zu müssen auf dem Smartphone, kann man auch dafür Favoriten anlegen.
+Beispiel-Kommandos wie z.B. <code>set TYPE=ROLLADEN pos 100</code> und <code>set TYPE=ROLLADEN pos 0</code>, die man immer wieder braucht. Um nicht jedes mal dieses Kommando eintippen zu müssen auf dem Smartphone, kann man auch dafür Favoriten anlegen.
-Dazu gibt man erstmal die beiden Kommandos getrennt durch Semikolon im Attribut favorites an:
+Dazu gibt man erst mal die beiden Kommandos getrennt durch Semikolon im Attribut favorites an:
 <code>attr telegrambotdevice favorites set TYPE=ROLLADEN pos 100;set TYPE=ROLLADEN pos 0</code>
@@ Zeile 161: / Zeile 161: @@
 == Links ==
 * Github Repository für die Telegram-Fhem Entwicklung: https://github.com/viegener/Telegram-fhem
-* Infos zum Telegram Botfather: https://core.telegram.org/bots#botfather
+* Infos zum Telegram BotFather: https://core.telegram.org/bots#botfather
 * Source code für das 50_TelegramBot.pm-Modul: https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm