TelegramBot: Unterschied zwischen den Versionen

Aus FHEMWiki
(kat)
 
(24 dazwischenliegende Versionen von 8 Benutzern werden nicht angezeigt)
Zeile 7: Zeile 7:
|ModOwner=[[Benutzer:Viegener|Viegener]] ({{Link2FU|12772|Forum}} / [[Benutzer Diskussion:Viegener|Wiki]])}}
|ModOwner=[[Benutzer:Viegener|Viegener]] ({{Link2FU|12772|Forum}} / [[Benutzer Diskussion:Viegener|Wiki]])}}


Das [[TelegramBot]]-Modul ermöglicht das Senden und Empfangen von Nachrichten über den Telegram-instant messaging Dienst (https://telegram.org/).  
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.
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.
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 [https://core.telegram.org/bots/api TelegramBot-API] über https-Aufrufe. Es muss jedoch das [http://www.fhemwiki.de/wiki/Raspberry_Pi#N.C3.BCtzliche_Zusatzpakete perl JSON modul] installiert sein.  
Das TelegramBot-Modul benötigt keine Zusatzsoftware auf dem FHEM-Server<ref>anders als die Vorläufer-Variante über das [[Telegram - old API method|Telegram-API]]</ref>, sondern verwendet das [https://core.telegram.org/bots/api TelegramBot-API] über https-Aufrufe. Es muss jedoch das [http://www.fhemwiki.de/wiki/Raspberry_Pi#N.C3.BCtzliche_Zusatzpakete perl JSON modul] installiert sein.


== Über Telegram Instant Messaging ==
== Über Telegram Instant Messaging ==
Telegram-IDs und Versand/Empfang von Nachrichten sind kostenfrei.  
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  
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.  
können auch aus dem WebBrowser verwendet werden.
Es gibt auch einen Kommandozeilen-Client für Linux, der die Grundlage dieses Moduls darstellt.  
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.
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.
Gruppenchats und Chats mit End-2-End-Verschlüsselung werden ebenfalls unterstützt.
Zeile 23: Zeile 23:
Für die Unterstützung von ''WhatsApp'' siehe Modul [[yowsup]].
Für die Unterstützung von ''WhatsApp'' siehe Modul [[yowsup]].


== Features ==
Unterstützt werden:
Unterstützt werden:


* Versand von Textnachrichten  
* Versand von Textnachrichten
* Versand und Empfang von Bildern/Audio/etc  
* Versand und Empfang von Bildern/Audio/etc
* Empfang von Textnachrichten von beliebigen Kontakten
* 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
Zeile 36: Zeile 35:
Die jeweils aktuellste Entwicklungs-Version des Moduls ist in Github [https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm 50_TelegramBot.pm] verfügbar.
Die jeweils aktuellste Entwicklungs-Version des Moduls ist in Github [https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm 50_TelegramBot.pm] verfügbar.


== Hinweise zum Betrieb mit FHEM ==
== TelegramBot Devices in FHEM ==
=== Define ===
{{Randnotiz|RNTyp=Info|RNText=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.
{{Randnotiz|RNTyp=Info|RNText=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 [https://core.telegram.org/bots#6-botfather BotFather] erzeugt. Dafür muss der BotFather mit einem Telegram-Client kontaktiert werden. 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.<br>
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#6-botfather BotFather] erzeugt (siehe dazu unten). Dafür muss der BotFather mit einem Telegram-Client kontaktiert werden. 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.<br>


Das Anlegen eines TelegramBot devices erfolgt durch die Angabe dieses Tokens:
Das Anlegen eines TelegramBot devices erfolgt durch die Angabe dieses Tokens:
Zeile 46: Zeile 46:
<code>define &lt;name&gt; TelegramBot  &lt;token&gt; </code>
<code>define &lt;name&gt; TelegramBot  &lt;token&gt; </code>


Beispiel: <code>define teleBot TelegramBot 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw</code>
Beispiel: <code>define myTelegramBot TelegramBot 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw</code>


'''Das Empfangen von Nachrichten (polling) erfordert die Einstellung des Attributes'''  
'''Das Empfangen von Nachrichten (polling) erfordert die Einstellung des Attributes'''
<code>pollingTimeout</code> '''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.'''  
<code>pollingTimeout</code> '''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.'''


Beispiel: <code>attr teleBot pollingTimeout 120</code>
Beispiel: <code>attr myTelegramBot pollingTimeout 120</code>


'''Der TelegramBot kann erst dann Nachrichten an einen telegram user schicken, wenn dieser zuerst an den telegram bot eine Nachricht gesendet hat.'''
'''Der TelegramBot kann erst dann Nachrichten an einen telegram user schicken, wenn dieser zuerst an den telegram bot eine Nachricht gesendet hat.'''
Dafür muss man in seinem Telegram-Client den Kontakt @botName suchen und dann eine Nachricht daran versenden.
Dafür muss man in seinem Telegram-Client den Kontakt @botName suchen und dann eine Nachricht daran versenden.
'''Der TelegramBot kann keine Nachrichten an andere Bots senden. Ein anderer Bot erhält die Nachrichten auch nicht wenn er in einer Gruppe enthalten ist.''' Dies ist eine Beschränkung in der Bot-Funktion bei Telegram. Das Versenden an einen anderen Bot (wenn man den Kontakt manuell hinzugefügt hat) führt zur Fehlermeldung
<code>sentMsgResult - Callback returned error :Bad Request: chat not found:</code>


{{Randnotiz|RNTyp=Info|RNText=TelegramBot setzt eine aktuelle Version von FHEM voraus, insbesondere Versionen weit vor der Umstellung auf 5.7 (also vor Herbst 2015) können mit einem TelegramBot-Modul nicht funktionieren, da insbesondere das HTTPSRV-Modul dann veraltet ist. Am besten auch den TelegramBot über den offiziellen Update mit dem Rest von FHEM installieren/aktualisieren.
{{Randnotiz|RNTyp=Info|RNText=TelegramBot setzt eine aktuelle Version von FHEM voraus, insbesondere Versionen weit vor der Umstellung auf 5.7 (also vor Herbst 2015) können mit einem TelegramBot-Modul nicht funktionieren, da insbesondere das HTTPSRV-Modul dann veraltet ist. Am besten auch den TelegramBot über den offiziellen Update mit dem Rest von FHEM installieren/aktualisieren.
}}
}}


== Registrierung eines neuen Bot ==
=== Registrierung eines neuen Bot ===
Zur Registrierung wird ein funktionierender Telegram-Client (egal ob Web, App oder Programm)benötigt. Hier wird ein Chat zum BotFather gestartet und der Befehl /newbot gesendet. Nun fragt der BotFather die benötigten Angaben ab und liefert am Ende des Dialogs die Informationen für den neuen Bot.
Zur Registrierung wird ein funktionierender Telegram-Client (egal ob Web, App oder Programm)benötigt. Hier wird ein Chat zum BotFather gestartet und der Befehl /newbot gesendet. Nun fragt der BotFather die benötigten Angaben ab und liefert am Ende des Dialogs die Informationen für den neuen Bot.
Hier ein Beispiel, wie so ein Chat aussehen könnte:
Hier ein Beispiel, wie so ein Chat aussehen könnte:
<pre>Client:  
<pre>Client:
/newbot
/newbot
----------------
----------------
BotFather:
BotFather:
Alright, a new bot. How are we going to call it? Please choose a name for your bot.  
Alright, a new bot. How are we going to call it? Please choose a name for your bot.
----------------
----------------
Client:  
Client:
Mein Name  
Mein Name
----------------
----------------
BotFather:  
BotFather:
Good. Now let's choose a username for your bot. It must end in `bot`. Like this, for example: TetrisBot or tetris_bot.
Good. Now let's choose a username for your bot. It must end in `bot`. Like this, for example: TetrisBot or tetris_bot.
----------------
----------------
Client:  
Client:
fhem_bot
fhem_bot
----------------
----------------
BotFather:  
BotFather:
Sorry, this username is already taken. Think of something different.
Sorry, this username is already taken. Think of something different.
----------------
----------------
Client:  
Client:
fhem1234_bot
fhem1234_bot
----------------
----------------
BotFather:  
BotFather:
Done! Congratulations on your new bot.
Done! Congratulations on your new bot.
You will find it at telegram.me/fhem1234_bot.
You will find it at telegram.me/fhem1234_bot.
Zeile 89: Zeile 92:
----------------
----------------
Use this token to access the HTTP API:
Use this token to access the HTTP API:
1234567890:AbCdefgHIJklmnOPQRst-uvwxyz  
1234567890:AbCdefgHIJklmnOPQRst-uvwxyz


For a description of the Bot API, see this page: https://core.telegram.org/bots/api  
For a description of the Bot API, see this page: https://core.telegram.org/bots/api
</pre>
</pre>
{{Randnotiz|RNTyp=Info|RNText=Achtung: Da Bots generell für alle Benutzer sichtbar sind und es gelegentlich Problem mit spammern gibt, die fremde bots auch in Gruppen hinzufügen, ist es empfehlenswert die Einstellung /setjoingroups auf false zu setzen, wenn die Zugehörigkeit zu Gruppen (und der Empfang von Meldungen aus gruppen) nicht notwendig ist
}}
Um einen Chat an einen "Contact" versenden zu können, muss zuerst in Contacts (bei Readings) ein Kontakt auftauchen. Wenn man sich zum allerersten Mal bei Telegram angemeldet hat, gibt es noch keinen Chat mit irgendjemanden. Man muss sich zuerstmal selbst eine Nachricht im Smartphone zusenden, dann taucht unter Readings der Eintrag Contacts auf. Erst dann kann man eine Nachricht mit @msgPeerId (das ist Ziffernfolge des Contacts ) oder mit @msgPeer (das ist der Name nach dem Doppelpunkt) vom TelegramBot auf sein Smartphone senden.
Um einen Chat an einen "Contact" versenden zu können, muss zuerst in Contacts (bei Readings) ein Kontakt auftauchen. Wenn man sich zum allerersten Mal bei Telegram angemeldet hat, gibt es noch keinen Chat mit irgendjemanden. Man muss sich zuerstmal selbst eine Nachricht im Smartphone zusenden, dann taucht unter Readings der Eintrag Contacts auf. Erst dann kann man eine Nachricht mit @msgPeerId (das ist Ziffernfolge des Contacts ) oder mit @msgPeer (das ist der Name nach dem Doppelpunkt) vom TelegramBot auf sein Smartphone senden.


== Tipps ==
== Tipps ==
Zeile 118: Zeile 127:
BotFather:
BotFather:
Success! The new status is: DISABLED. /help</pre>
Success! The new status is: DISABLED. /help</pre>
Siehe auch Info zu /setjoingroups oben.


=== Kontakte ===
=== 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 gespeichert - bestehend aus UserID, Vor- und Nachname des Benutzers (mit _ verbunden) und dem Username (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 gespeichert - bestehend aus UserID, Vor- und Nachname des Benutzers (mit _ verbunden) und dem Username (mit vorangestelltem @).


Beispiel: <code>123456:Ralf_Mustermann:@ralf</code>
Beispiel: <code>123456:Ralf_Mustermann:@ralf</code>
Zeile 133: Zeile 144:
=== Reset ===
=== 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.


=== Gruppen ===
=== Gruppen ===
Zeile 142: Zeile 153:


Auch die neuen Supergruppen werden mit dem Bot unterstützt, es ist allerdings zu beachten, dass bei der Umwandlung einer Gruppe in eine Supergruppe eine neue ID in den Kontakten von Telegram vergeben wird. Wenn man also wie empfohlen IDs zur Identifikation von Benutzern einsetzt, muss entsprechend angepasst werden.
Auch die neuen Supergruppen werden mit dem Bot unterstützt, es ist allerdings zu beachten, dass bei der Umwandlung einer Gruppe in eine Supergruppe eine neue ID in den Kontakten von Telegram vergeben wird. Wenn man also wie empfohlen IDs zur Identifikation von Benutzern einsetzt, muss entsprechend angepasst werden.
==== Fehlermeldungen bei veralteter SSL-Version ====
Telegram nutzt seit Februar 2020 eine neue Verschlüsselung und dies ruft bei veralteter Installation eine Fehlermeldung hervor:
NonBlockingGet: returned <hidden>: Can't connect(2) to <nowiki>https://api.telegram.org:443</nowiki>
Dies deutet auf eine veraltete SSL-Version hin, siehe dazu die Forumsdiskussion ab {{Link2Forum|Topic=38328|Message=1021642|LinkText=diesem Beitrag}}. Hilfreich hat sich ein upgrade der SSL-Module erwiesen. Zuerst muss u.U. ein Modul installiert werden
:<code>sudo apt-get install libssl-dev</code>
und danach in zwei Schritten
sudo cpan <enter>
upgrade net::SSLeay<enter>
Es ist bei Jessie zwingend ein Upgrade von
IO::Socket::SSL 2.002 -> 2.066
notwendig. Es wird darauf hingewiesen, dass idealerweise nicht einzelne Module, sondern das gesamte OS sowie alle Perlmodule auf den neuesten Stand gebracht werden sollten.
=== Befehle von Telegram an FHEM senden ===
Es handelt sich hier um ein Tool, das {{Link2Forum|Topic=51425|Message=464928|LinkText=hier im Forum}} vorgestellt wurde. Dabei wird ein notify in FHEM angelegt, das den TelegramBot überwacht. Wird eine Befehlsfolge an den Bot gesendet, liest das Telegram-Device die gesendete Information aus und führt den Befehl aus. Weitere Details, wie hier vorzugehen ist, unter dem oben angegebenen Link im Forum.
Wenn man an FHEM Befehle senden will, muss der TelegramBot bereit sein, diese Nachrichten zu empfangen. Wenn man allerdings aus Sicherheitsgründen das Attribut
:<code>allowUnknownContacts = 0</code>
gesetzt hat, dann ist ein solcher Empfang nicht möglich. Daher muss (zumindest einmalig) erlaubt werden, von unbekannten Kontakten eine Nachricht zu bekommen. Nach dem ersten Empfang ist dann der Kontakt bekannt und man kann erneut den Empfang auf bekannte Kontakte beschränken.


== Beispielszenarien ==
== Beispielszenarien ==
=== Benachrichtigungen über Ereignisse ===
=== 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:
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:


<code>define notify_fhem_reload notify global:INITIALIZED set telebotdevice message fhem newly started - just now !</code>
<code>define notify_fhem_reload notify global:INITIALIZED set myTelegramBot message fhem newly started - just now !</code>


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.
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.
Nebenbemerkung: hier ist eine erweiterte Strukturierung evt. empfehlenswert: statt jede Notify-Syntax o.ä. direkt auf TelegramBot-Spezifika gehen zu lassen, kann man sich eine Helper-Funktion (zur Vermittlung all solcher "Alarmtexte") bauen ([[99_myUtils_anlegen]]), die entsprechende Alarm-Meldungen dann nur intern auf (u.a.) einen Messaging-Service wie (momentan!) Telegram schickt.


=== Versand von Bildern ===
=== Versand von Bildern ===
Zeile 157: Zeile 189:
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.
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  
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 {{Link2Forum|Topic=41583|LinkText=FHEM-Forum}}) verteilt wird, erlaubt auch den Transfer grösserer Bilder. Die Grenze liegt ansonsten bei ca. 14kb auf Raspberries (Plattformspezifische Grenze).
([r9576] HttpUtils.pm: Async write for POST Requests {{Link2Forum|Topic=41583|LinkText=FHEM-Forum}}) verteilt wird, erlaubt auch den Transfer grösserer Bilder. Die Grenze liegt ansonsten bei ca. 14kb auf Raspberries (Plattformspezifische Grenze).




<code>define notify_fhem_reload notify wetter:report set telebotdevice sendImage /opt/fhem/wetter.jpg</code>
<code>define notify_fhem_reload notify wetter:report set myTelegramBot sendImage /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.
Zeile 167: Zeile 199:
=== Versand von SVG-Plots ===
=== Versand von SVG-Plots ===


SVG-Plots können mit dem Befehl  
SVG-Plots können mit dem Befehl
<code>cmdSend [ @<peer1> ... @<peerN> ] <fhem command></code>
<code>cmdSend [ @<peer1> ... @<peerN> ] <fhem command></code>
verschickt werden.
verschickt werden.
Zeile 173: Zeile 205:
Das angegebene FHEM-Kommando wird ausgeführt und das Ergebnis an die angegebenen Peers bzw. den Standard-Peer verschickt.
Das angegebene FHEM-Kommando wird ausgeführt und das Ergebnis an die angegebenen Peers bzw. den Standard-Peer verschickt.


Mit dem folgenden Befehl wird der SVG-Plot SVG_FileLog_Aussen an den Standard-Peer geschickt:  
Mit dem folgenden Befehl wird der SVG-Plot SVG_FileLog_Aussen an den Standard-Peer geschickt:
<code>set mein_telegramBot cmdSend { plotAsPng('SVG_FileLog_Aussen') }</code>
<code>set myTelegramBot cmdSend { plotAsPng('SVG_FileLog_Aussen') }</code>


Nach <code>define cmd_sendTelegramSVG cmdalias TGSVG .* AS set mein_telegramBot cmdSend { plotAsPng("$EVENT") }</code>
Nach <code>define cmd_sendTelegramSVG cmdalias TGSVG .* AS set myTelegramBot cmdSend { plotAsPng("$EVENT") }</code>
kann man mit einem kurzen  
kann man mit einem kurzen
<code>TGSVG SVG_Garten</code>
<code>TGSVG SVG_Garten</code>
ein beliebiges SVG über die Kommandozeile per Telegram versenden.
ein beliebiges SVG über die Kommandozeile per Telegram versenden.
Zeile 183: Zeile 215:
Um das SVG nun noch mit einem Text zu versehen, muss eine Textnachricht dazu gesendet werden, was sich am einfachsten durch das Ausführen eines FHEM-Befehls auf Perl-Ebene realisieren lässt:
Um das SVG nun noch mit einem Text zu versehen, muss eine Textnachricht dazu gesendet werden, was sich am einfachsten durch das Ausführen eines FHEM-Befehls auf Perl-Ebene realisieren lässt:


<code>{fhem "set mein_telegramBot message Bildbeschreibung;; set mein_telegramBot cmdSend { plotAsPng('mein_SVG') }" }</code>
<code>{fhem "set myTelegramBot message Bildbeschreibung;; set myTelegramBot cmdSend { plotAsPng('mein_SVG') }" }</code>


'''Hinweis:''' früher wurde zum Verschicken von Plots auch die interne Funktion TelegramBot_ExecuteCommand verwendet; mit dem Update Ende Februar 2017 hat diese Funktion einen zusätzlichen Parameter erhalten und lautet nun  
'''Hinweis:''' früher wurde zum Verschicken von Plots auch die interne Funktion TelegramBot_ExecuteCommand verwendet; mit dem Update Ende Februar 2017 hat diese Funktion einen zusätzlichen Parameter erhalten und lautet nun
<code>TelegramBot_ExecuteCommand($defs{"mein_telegramBot"}, meine_ZielID, undef, '{plotAsPng("mein_SVG")}');</code>
<code>TelegramBot_ExecuteCommand($defs{"myTelegramBot"}, meine_ZielID, undef, '{plotAsPng("mein_SVG")}');</code>




Zeile 205: Zeile 237:
<code>received photo # Size: 107701</code>
<code>received photo # Size: 107701</code>
Über das Get-Kommando <code>urlForFile</code> mit der ID aus dem msgFileId Reading lässt sich dann daraus ein URL ableiten, der dann zur eigentlichen Datei führt:  
Über das Get-Kommando <code>urlForFile</code> mit der ID aus dem msgFileId Reading lässt sich dann daraus ein URL ableiten, der dann zur eigentlichen Datei führt:


<code>https://api.telegram.org/file/bot123456:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/photo/file_25.jpg</code>
<code>https://api.telegram.org/file/bot123456:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/photo/file_25.jpg</code>
Zeile 212: Zeile 244:
=== 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.  
ü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).
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).
Zeile 222: Zeile 254:
=== Kommandos auslösen ===
=== 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.
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.


<code>attr telebotdevice cmdKeyword doit</code>
<code>attr myTelegramBot cmdKeyword doit</code>


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 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.
Zeile 236: Zeile 268:
<code>doit list telegrambot</code>
<code>doit 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.
==== TelegramBot-Aktionen auslösen ====
Der Bot sendet Nachrichten standardmäßig an den defaultPeer (falls definiert). So kann mit folgendem Befehl etwa der Versand eines Videos ausgelöst werden:
 
<code>doit set telegrambot sendMedia cam.mp4</code>
 
Soll eine Nachricht an einen anderen (bekannten) User geschickt werden, so ist die Angabe der ID des Users erforderlich. Dies kann dynamisch mit set-Logik und Abfrage der Readings erfolgen. Der folgende Befehl sendet das Video an den User, der das Kommando an den Bot geschickt hat:
 
<code>doit set telegrambot sendMedia @[TB:msgChatId] cam.mp4</code>
 
Bei der Definition von Favoriten (siehe unten) kann genau so vorgegangen 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 ====
==== Favoriten für Kommandos anlegen ====
Grundidee bei den Favoriten ist, dass man lange Befehle, die man häufig 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 jedes mal dieses Kommando eintippen zu müssen auf dem Smartphone, kann man auch dafür Favoriten anlegen.
Beispiel-Kommandos wie z.B. <code>set TYPE=ROLLLADEN pos 100</code> und <code>set TYPE=ROLLLADEN 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 erst mal 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>
<code>attr myTelegramBot favorites set TYPE=ROLLLADEN pos 100;set TYPE=ROLLLADEN pos 0</code>


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


<code>attr telegrambotdevice cmdFavorites /short</code>
<code>attr myTelegramBot cmdFavorites /short</code>


Wenn man nun im Telegram Client  
Wenn man nun im Telegram Client
<code>/short 1</code> an den Bot schickt führt der Bot den ersten Favoriten aus und das Ergebnis der Ausführung wird zurückgeschickt.
<code>/short 1</code> 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  
Ausserdem kann man im Telegram Client
<code>/short</code> an den Bot schicken, dann antwortet der Bot mit
<code>/short</code> an den Bot schicken, dann antwortet der Bot mit


Zeile 263: Zeile 303:
Favorites
Favorites


/short1 = set TYPE=ROLLADEN pos 100
/short1 = set TYPE=ROLLLADEN pos 100


/short2 = set TYPE=ROLLADEN pos 0
/short2 = set TYPE=ROLLLADEN pos 0


</pre>
</pre>
Zeile 272: Zeile 312:
Um die Beschriftung der Schaltflächen zu optimieren, können die Befehle im Attribut favorites mit Beschreibungen versehen werden:
Um die Beschriftung der Schaltflächen zu optimieren, können die Befehle im Attribut favorites mit Beschreibungen versehen werden:


<code>/[Rollaeden zu ]=set TYPE=ROLLADEN pos 100;/[Rollaeden auf]=set TYPE=ROLLADEN pos 0</code>
<code>/[Rolllaeden zu ]=set TYPE=ROLLLADEN pos 100;/[Rolllaeden auf]=set TYPE=ROLLLADEN pos 0</code>


Nun antwortet der Bot auf das Schlüsselwort für die Favoriten mit:
Nun antwortet der Bot auf das Schlüsselwort für die Favoriten mit:
Zeile 279: Zeile 319:
Favorites
Favorites


/short1 = Rollaeden zu
/short1 = Rolllaeden zu


/short2 = Rollaeden auf
/short2 = Rolllaeden auf


</pre>
</pre>
=== Nützliche Kombinationen mit weiteren Modulen ===
==== msgConfig ====
{{Link2CmdRef|Anker=msgConfig|Lang=de|Label=msgConfig}}
{{Link2CmdRef|Anker=msgDialog|Lang=de|Label=msgDialog}}
==== msgDialog ====
[[MsgDialog]]
==== MSG ====
[[Msg]]
{{Link2CmdRef|Anker=MSG|Lang=en|Label=MSG}}
{{Link2Forum|Topic=39983|LinkText=Forum-Beitrag}}
==== PostMe ====
[[Modul PostMe#Steuerung per Telegram|PostMe]]
{{Link2CmdRef|Anker=PostMe|Lang=de|Label=PostMe}}
{{Link2CmdRef|Anker=TBot_List|Lang=en|Label=TBot_List}}
==== ROOMATE ====
{{Link2CmdRef|Anker=ROOMMATE|Lang=de|Label=ROOMMATE}}
==== MAX ====
[[MAX#Telegram-Benachrichtigung bei dauergeöffnetem Fenster|Dauer-offenes Fenster melden]]
==== SSCAM - Steuerung von Kameras in Synology Surveillance Station - Schnappschüsse mit TelegramBot versenden ====
[[SSCAM - Steuerung von Kameras in Synology Surveillance Station#Schnappschüsse mit TelegramBot versenden|Schnappschüsse mit TelegramBot versenden]]
==== PRESENCE ====
[[PRESENCE#Hinweis zur Benutzung / Fehlerhandling|Hinweis zur Benutzung / Fehlerhandling]]
==== AMAD ====
[[AMAD]]
==== TALKTOME & TALKTOUSER ====
[[TALKTOME & TALKTOUSER - Sprachverarbeitung für Nutzerinteraktionen#Beleuchtungssteuerung mit Telegram|Beleuchtungssteuerung mit Telegram]]
==== Staumelder ====
[[Staumelder#telegram|Staumelder]]
==== Grafana ====
[[Grafana#Speichern und Senden von Grafiken (zB_mit_Telegram)|Grafana-Plots versenden]]
==== Talk2Fhem ====
[[Talk2Fhem#Messenger Telegram|Talk2Fhem]]
==== Hausüberwachung ====
[[Hausüberwachung#Nachrichten aus dem Haus|Nachrichten aus dem Haus]]
==== Gäste-WLAN der Fritzbox auswerten und Login per Telegram senden ====
{{Link2Forum|Topic=100119|Message=936495|LinkText=Forum-Beitrag}}
==== Batterieüberwachung nur einmal täglich ====
{{Link2Forum|Topic=99219|Message=926652|LinkText=Forum-Beitrag}}
==== BOTVAC ====
[[BOTVAC#MAPS|Saugroboter-Karten]]
==== Unifi Voucher bereistellen über msgDialog ====
[[Unifi#über Telegram|Unifi Voucher]]
[[Unifi#Erkennung neuer clients|Erkennung unbekannter Clients]]


== Links ==
== Links ==
Zeile 295: Zeile 405:
* TelegramBot API https://core.telegram.org/bots/api
* TelegramBot API https://core.telegram.org/bots/api


<references />
[[Kategorie:Telegram]]
[[Kategorie:Telegram]]

Aktuelle Version vom 28. Dezember 2020, 21:24 Uhr

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!


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[1], sondern verwendet das TelegramBot-API über https-Aufrufe. Es muss jedoch das perl JSON modul installiert sein.

Ü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.

Unterstützt werden:

  • Versand von Textnachrichten
  • Versand und Empfang von Bildern/Audio/etc
  • Empfang von Textnachrichten von beliebigen Kontakten
  • Kommandos in FHEM über Telegram-Nachrichten von aussen auslösen
  • Ergebnisse der Kommandos zusenden lassen

Eine detaillierte Beschreibung des Moduls ist im FHEM Forum und in der (englischen) Dokumentation zum Modul in der commandref/TelegramBot und in 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.

TelegramBot Devices in FHEM

Define

Info green.pngAchtung: 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 (siehe dazu unten). Dafür muss der BotFather mit einem Telegram-Client kontaktiert werden. 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 myTelegramBot 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.

Beispiel: attr myTelegramBot pollingTimeout 120

Der TelegramBot kann erst dann Nachrichten an einen telegram user schicken, wenn dieser zuerst an den telegram bot eine Nachricht gesendet hat. Dafür muss man in seinem Telegram-Client den Kontakt @botName suchen und dann eine Nachricht daran versenden.

Der TelegramBot kann keine Nachrichten an andere Bots senden. Ein anderer Bot erhält die Nachrichten auch nicht wenn er in einer Gruppe enthalten ist. Dies ist eine Beschränkung in der Bot-Funktion bei Telegram. Das Versenden an einen anderen Bot (wenn man den Kontakt manuell hinzugefügt hat) führt zur Fehlermeldung sentMsgResult - Callback returned error :Bad Request: chat not found:

Info green.pngTelegramBot setzt eine aktuelle Version von FHEM voraus, insbesondere Versionen weit vor der Umstellung auf 5.7 (also vor Herbst 2015) können mit einem TelegramBot-Modul nicht funktionieren, da insbesondere das HTTPSRV-Modul dann veraltet ist. Am besten auch den TelegramBot über den offiziellen Update mit dem Rest von FHEM installieren/aktualisieren.


Registrierung eines neuen Bot

Zur Registrierung wird ein funktionierender Telegram-Client (egal ob Web, App oder Programm)benötigt. Hier wird ein Chat zum BotFather gestartet und der Befehl /newbot gesendet. Nun fragt der BotFather die benötigten Angaben ab und liefert am Ende des Dialogs die Informationen für den neuen Bot. Hier ein Beispiel, wie so ein Chat aussehen könnte:

Client:
/newbot
----------------
BotFather:
Alright, a new bot. How are we going to call it? Please choose a name for your bot.
----------------
Client:
Mein Name
----------------
BotFather:
Good. Now let's choose a username for your bot. It must end in `bot`. Like this, for example: TetrisBot or tetris_bot.
----------------
Client:
fhem_bot
----------------
BotFather:
Sorry, this username is already taken. Think of something different.
----------------
Client:
fhem1234_bot
----------------
BotFather:
Done! Congratulations on your new bot.
You will find it at telegram.me/fhem1234_bot.
You can now add a description, about section and profile picture for your bot, see /help for a list of commands.
----------------
Use this token to access the HTTP API:
1234567890:AbCdefgHIJklmnOPQRst-uvwxyz

For a description of the Bot API, see this page: https://core.telegram.org/bots/api
Info green.pngAchtung: Da Bots generell für alle Benutzer sichtbar sind und es gelegentlich Problem mit spammern gibt, die fremde bots auch in Gruppen hinzufügen, ist es empfehlenswert die Einstellung /setjoingroups auf false zu setzen, wenn die Zugehörigkeit zu Gruppen (und der Empfang von Meldungen aus gruppen) nicht notwendig ist


Um einen Chat an einen "Contact" versenden zu können, muss zuerst in Contacts (bei Readings) ein Kontakt auftauchen. Wenn man sich zum allerersten Mal bei Telegram angemeldet hat, gibt es noch keinen Chat mit irgendjemanden. Man muss sich zuerstmal selbst eine Nachricht im Smartphone zusenden, dann taucht unter Readings der Eintrag Contacts auf. Erst dann kann man eine Nachricht mit @msgPeerId (das ist Ziffernfolge des Contacts ) oder mit @msgPeer (das ist der Name nach dem Doppelpunkt) vom TelegramBot auf sein Smartphone senden.


Tipps

Privacyeinstellungen

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

Client:
/setprivacy
----------------
BotFather:
Choose a bot to change group messages settings.
----------------
Client:
@fhem1234_bot
----------------
BotFather:
'Enable' - your bot will only receive messages that either start with the '/' symbol or mention the bot by username.
'Disable' - your bot will receive all messages that people send to groups.
Current status is: ENABLED
----------------
Client:
Disable
----------------
BotFather:
Success! The new status is: DISABLED. /help

Siehe auch Info zu /setjoingroups oben.

Kontakte

Der Bot merkt sich die bereits bekannten Kontakte im Reading Contacts. Dabei werden die einzelnen Kontakte jeweils als 3-teilige Einträge gespeichert - 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.

Gruppen

Um eine Nachricht von FHEM an eine Gruppe zu senden, muss der BOT in die Gruppe aufgenommen werden. Nach dem Senden einer Nachricht an die Gruppe kann im Modul die Gruppen-ID ermittelt werden und zum Senden von Nachrichten verwendet werden. Die Gruppen-ID ist eine negative Zahl. Wenn die Privacy-Einstellungen nicht auf 'Disabled' gesetzt wurden, muss die Nachricht mit einem Slash (/) beginnen.

Supergroups / Supergruppen

Auch die neuen Supergruppen werden mit dem Bot unterstützt, es ist allerdings zu beachten, dass bei der Umwandlung einer Gruppe in eine Supergruppe eine neue ID in den Kontakten von Telegram vergeben wird. Wenn man also wie empfohlen IDs zur Identifikation von Benutzern einsetzt, muss entsprechend angepasst werden.

Fehlermeldungen bei veralteter SSL-Version

Telegram nutzt seit Februar 2020 eine neue Verschlüsselung und dies ruft bei veralteter Installation eine Fehlermeldung hervor:

NonBlockingGet: returned <hidden>: Can't connect(2) to https://api.telegram.org:443

Dies deutet auf eine veraltete SSL-Version hin, siehe dazu die Forumsdiskussion ab diesem Beitrag. Hilfreich hat sich ein upgrade der SSL-Module erwiesen. Zuerst muss u.U. ein Modul installiert werden

sudo apt-get install libssl-dev

und danach in zwei Schritten

sudo cpan <enter>
upgrade net::SSLeay<enter>

Es ist bei Jessie zwingend ein Upgrade von

IO::Socket::SSL 2.002 -> 2.066 

notwendig. Es wird darauf hingewiesen, dass idealerweise nicht einzelne Module, sondern das gesamte OS sowie alle Perlmodule auf den neuesten Stand gebracht werden sollten.

Befehle von Telegram an FHEM senden

Es handelt sich hier um ein Tool, das hier im Forum vorgestellt wurde. Dabei wird ein notify in FHEM angelegt, das den TelegramBot überwacht. Wird eine Befehlsfolge an den Bot gesendet, liest das Telegram-Device die gesendete Information aus und führt den Befehl aus. Weitere Details, wie hier vorzugehen ist, unter dem oben angegebenen Link im Forum.

Wenn man an FHEM Befehle senden will, muss der TelegramBot bereit sein, diese Nachrichten zu empfangen. Wenn man allerdings aus Sicherheitsgründen das Attribut

allowUnknownContacts = 0

gesetzt hat, dann ist ein solcher Empfang nicht möglich. Daher muss (zumindest einmalig) erlaubt werden, von unbekannten Kontakten eine Nachricht zu bekommen. Nach dem ersten Empfang ist dann der Kontakt bekannt und man kann erneut den Empfang auf bekannte Kontakte beschränken.

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 myTelegramBot 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.

Nebenbemerkung: hier ist eine erweiterte Strukturierung evt. empfehlenswert: statt jede Notify-Syntax o.ä. direkt auf TelegramBot-Spezifika gehen zu lassen, kann man sich eine Helper-Funktion (zur Vermittlung all solcher "Alarmtexte") bauen (99_myUtils_anlegen), die entsprechende Alarm-Meldungen dann nur intern auf (u.a.) einen Messaging-Service wie (momentan!) Telegram schickt.

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 myTelegramBot sendImage /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 SVG-Plots

SVG-Plots können mit dem Befehl cmdSend [ @<peer1> ... @<peerN> ] <fhem command> verschickt werden.

Das angegebene FHEM-Kommando wird ausgeführt und das Ergebnis an die angegebenen Peers bzw. den Standard-Peer verschickt.

Mit dem folgenden Befehl wird der SVG-Plot SVG_FileLog_Aussen an den Standard-Peer geschickt: set myTelegramBot cmdSend { plotAsPng('SVG_FileLog_Aussen') }

Nach define cmd_sendTelegramSVG cmdalias TGSVG .* AS set myTelegramBot cmdSend { plotAsPng("$EVENT") } kann man mit einem kurzen TGSVG SVG_Garten ein beliebiges SVG über die Kommandozeile per Telegram versenden.

Um das SVG nun noch mit einem Text zu versehen, muss eine Textnachricht dazu gesendet werden, was sich am einfachsten durch das Ausführen eines FHEM-Befehls auf Perl-Ebene realisieren lässt:

{fhem "set myTelegramBot message Bildbeschreibung;; set myTelegramBot cmdSend { plotAsPng('mein_SVG') }" }

Hinweis: früher wurde zum Verschicken von Plots auch die interne Funktion TelegramBot_ExecuteCommand verwendet; mit dem Update Ende Februar 2017 hat diese Funktion einen zusätzlichen Parameter erhalten und lautet nun TelegramBot_ExecuteCommand($defs{"myTelegramBot"}, meine_ZielID, undef, '{plotAsPng("mein_SVG")}');


Voraussetzungen für den Versand von SVG-Plots

Es muss das Modul libimage-librsvg-perl installiert sein:

sudo apt-get install libimage-librsvg-perl

Evtl. sind weitere Module erforderlich:

sudo apt-get install libgd-graph-perl

sudo apt-get install libgd-text-perl

Empfang von Bildern oder ähnlichem

Beim Empfang von Bildern wird zuerst nur eine ID vom Telegram-Server empfangen, diese befindet sich im Reading msgFileId angelegt (123456:xxxxxxxxxxxxxxxxxxxxxxx-xxxxxxxx) und im Reading msgText steht dann so etwas wie received photo # Size: 107701

Über das Get-Kommando urlForFile mit der ID aus dem msgFileId Reading lässt sich dann daraus ein URL ableiten, der dann zur eigentlichen Datei führt:

https://api.telegram.org/file/bot123456:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/photo/file_25.jpg


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 myTelegramBot 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

doit set schalter on

doit list telegrambot

TelegramBot-Aktionen auslösen

Der Bot sendet Nachrichten standardmäßig an den defaultPeer (falls definiert). So kann mit folgendem Befehl etwa der Versand eines Videos ausgelöst werden:

doit set telegrambot sendMedia cam.mp4

Soll eine Nachricht an einen anderen (bekannten) User geschickt werden, so ist die Angabe der ID des Users erforderlich. Dies kann dynamisch mit set-Logik und Abfrage der Readings erfolgen. Der folgende Befehl sendet das Video an den User, der das Kommando an den Bot geschickt hat:

doit set telegrambot sendMedia @[TB:msgChatId] cam.mp4

Bei der Definition von Favoriten (siehe unten) kann genau so vorgegangen werden.

Emblem-question-yellow.svgAchtung: 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=ROLLLADEN pos 100 und set TYPE=ROLLLADEN 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 myTelegramBot favorites set TYPE=ROLLLADEN pos 100;set TYPE=ROLLLADEN 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 myTelegramBot 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

/short1 = set TYPE=ROLLLADEN pos 100

/short2 = set TYPE=ROLLLADEN pos 0

Die Antworten werden als Schaltflächen dargestellt (Telegram inline Keyboard) und können am Mobile-Client direkt angeklickt werden um sie auszuführen. Um die Beschriftung der Schaltflächen zu optimieren, können die Befehle im Attribut favorites mit Beschreibungen versehen werden:

/[Rolllaeden zu ]=set TYPE=ROLLLADEN pos 100;/[Rolllaeden auf]=set TYPE=ROLLLADEN pos 0

Nun antwortet der Bot auf das Schlüsselwort für die Favoriten mit:

Favorites

/short1 = Rolllaeden zu

/short2 = Rolllaeden auf

Nützliche Kombinationen mit weiteren Modulen

msgConfig

msgConfig

msgDialog

msgDialog

MsgDialog

MSG

Msg

MSG

Forum-Beitrag

PostMe

PostMe

PostMe

TBot_List

ROOMATE

ROOMMATE

MAX

Dauer-offenes Fenster melden

SSCAM - Steuerung von Kameras in Synology Surveillance Station - Schnappschüsse mit TelegramBot versenden

Schnappschüsse mit TelegramBot versenden

PRESENCE

Hinweis zur Benutzung / Fehlerhandling

AMAD

AMAD

TALKTOME & TALKTOUSER

Beleuchtungssteuerung mit Telegram

Staumelder

Staumelder

Grafana

Grafana-Plots versenden

Talk2Fhem

Talk2Fhem

Hausüberwachung

Nachrichten aus dem Haus

Gäste-WLAN der Fritzbox auswerten und Login per Telegram senden

Forum-Beitrag

Batterieüberwachung nur einmal täglich

Forum-Beitrag

BOTVAC

Saugroboter-Karten

Unifi Voucher bereistellen über msgDialog

Unifi Voucher

Erkennung unbekannter Clients


Links

  1. anders als die Vorläufer-Variante über das Telegram-API