Quelltext der Seite SSChatBot - Integration des Synology Chat Servers

{{Infobox Modul
|ModPurpose=Integration des Synology Chat Servers
|ModType=d
|ModCmdRef=SSChatBot
|ModForumArea=Sonstiges
|ModTechName=50_SSChatBot.pm
|ModOwner=DS_Starter}}

Das Modul 50_SSChatBot wird als offizielles Modul über den FHEM Standard Updateprozess ausgeliefert.

Aktuelle Entwicklungsversionen können einfach per Download mit diesem Befehl in der FHEM Kommandozeile bezogen werden. Bitte so komplett mit den Ausführungszeichen am Anfang und Ende eingeben:

<pre>
 "wget -qO ./FHEM/50_SSChatBot.pm https://svn.fhem.de/fhem/trunk/fhem/contrib/DS_Starter/50_SSChatBot.pm"
</pre>

Danach FHEM restarten.


= Zweckbeschreibung =

Mit diesem Modul erfolgt die Integration des Synology Chat Servers in FHEM. Dadurch ist es möglich, Nachrichten zwischen FHEM und Synology Chat Server auszutauschen. Der Synology Chat Server ist für den Synology Server Besitzer ein Teil einer private Cloud Lösung.



<br>

= Definition eines ChatBot-Devices =


Die Definition ist einfach:

 define <Name> SSChatBot <Adresse Synology Server> [Port] [Protokoll]

Die Angaben Port und Protokoll sind optional, per default werden Port=5000 und Protokoll=http verwendet.

* Port: Port der Synology Diskstation (default 5000)
* Protokoll: Protokoll für Messages Richting Chat-Server, http oder https (default http)

Beispiel mit HTTPS:

 define SynChatBot SSChatBot 192.168.2.10 5001 https

Bei der Definition wird sowohl ein SSChaBot Device als auch ein extra FHEMWEB Device zum Nachrichtenempfang automatisiert im Raum "Chat" angelegt. Der Port des FHEMWEB Devices wird automatisch ermittelt mit Startport 8082. Ist dieser Port belegt, werden die Ports in aufsteigender Reihenfolge auf eine eventuelle Belegung durch ein FHEMWEB Device geprüft und der nächste freie Port wird dem neuen Device zugewiesen.

Die Chatintegration unterscheidet zwischen "Eingehende Nachrichten" (FHEM -> Chat) und "Ausgehende Nachrichten" (Chat -> FHEM). Das SSChatBot Device konfiguriert beide Übermittlungstypen wie nachfolgend beschrieben.


== Aktivierung eingehende Nachrichten (FHEM -> Chat) ==

Für den Betrieb des ChatBots wird ein Bot-Token benötigt. Dieser Token wird über die benutzerdefinierte Einbindungsfunktionen erstellt bzw. kann darüber auch verändert werden. Klicken Sie dazu auf das Symbol '''Profilfoto''' oben rechts in der aufgerufenen Synology Chat-Applikation und wählen Sie '''Einbindung'''. Wählen sie dann '''Bots''' und erstellen einen neuen Bot oder verändern einen vorhandenen Bot.

<gallery>
File:chatint1.PNG 
File:chatint2.PNG
File:chatint3.PNG
</gallery>

In Einbindungseinstellungen:

* "Aus Botliste ausblenden" deaktivieren
* einen Namen und optionale Beschreibung vergeben
* den Token aus dem Feld '''"Token"''' herauskopieren

'''Wichtig:''' vor den nächsten Schritten ist der neue Bot zu speichern um ihn zu aktivieren. Andernfalls kommt die Meldung "'''bot is not legal'''" im erstellten SSChatBot Device.

Der Token wird nun in das neu definierten SSChatBot-Device eingefügt. In diesem Beispiel wäre es:

 set SynChatBot botToken U6FOMH9IgT22ECJceaIW0fNwEi7VfqWQFPMgJQUJ6vpaGoWZ1SJkOGP7zlVIscCp

War die Speicherung erfolgreich, kann mit:

 get SynChatBot storedToken

der gespeicherte Token jederzeit angezeigt werden.


<gallery>
File:chatdef1.PNG 
File:chatdef2.PNG
File:chatdef3.PNG
</gallery>



War die Definition erfolgreich, werden die im Synology Chat Server verfügbaren User abgefragt und zur weiteren Verwendung gespeichert. Konnte diese Abfrage fehlerfrei ausgeführt werden, springt der state des Device auf "active".

Sollten keine User in diesem Attribut erscheinen, bitte auf der Synology kontrollieren ob die gewünschten User die Berechtigung für die Chat-Anwendung besitzen.


<br>

== Aktivierung ausgehende Nachrichten (Chat -> FHEM) ==

Für Nachrichten des Chat in Richtung FHEM muß in der Chat-Applikation das Feld '''Ausgehende URL''' gefüllt werden.

Klicken Sie dazu auf das Symbol Profilfoto oben rechts in der aufgerufenen Synology Chat-Applikation und wählen Sie Einbindung.
Wählen sie dann im Menü '''Bots''' den bereits den für eingehende Nachrichten verwendeten Bot aus.

In das Feld '''Ausgehende URL''' wird nun der Wert des Internals '''OUTDEF''' des erstellten SSChatBot Devices hineinkopiert.
Zum Beispiel könnte der String so aussehen:

<pre>
 http://fhemtest.myds.me:8086/sschat/outchat?botname=SynChatBot&fwcsrf=5de17731
</pre>


<br>

= Set =

<br>
; asyncSendItem: sendet eine [[#verschiedene_Arten_Nachrichten_an_Chatempf.C3.A4nger_senden | Nachricht]] an einen oder mehrere Chatempfänger

; botToken: speichert den Token für den Zugriff auf den Chat als Bot 

; listSendqueue: zeigt die noch an den Chat zu übertragenden Nachrichten (sofern vorhanden)

; purgeSendqueue < -all- | -permError- | index >: 
* -all- : löscht alle Einträge der Sendqueue 
* -permError- : löscht alle Einträge der Sendqueue mit "permanent Error" Status (forbidSend => 1)
* index : löscht ausgewählten Eintrag mit "index". Die Einträge in der Sendqueue kann man sich vorher mit "set listSendqueue" ansehen um den gewünschten Index zu finden.

; restartSendqueue [force]: startet die Abarbeitung der Sendequeue manuell neu. Der Sendeprozess wird bei jedem neuen Eintrag in die Sendequeue ebenfalls automatisch neu gestartet. Eventuell in der Sendequeue vorhandene Einträge mit der Kennzeichnung '''forbidSend''' werden nicht erneut versendet. <br>Erfolgt der Aufruf mit der Option '''force''', werden auch Einträge mit der Kennzeichnung '''forbidSend''' berücksichtigt. 



<br>

== verschiedene Arten Nachrichten an Chatempfänger senden ==

<br>
Nachrichten, die FHEM an den Chat Server sendet (eingehende Nachrichten), werden in FHEM zunächst in eine Queue gestellt. Der Sendeprozess wird sofort gestartet. War die Übermittlung erfolgreich, wird die Nachricht aus der Queue gelöscht. Anderenfalls verbleibt sie in der Queue und der Sendeprozess wird, in einem von der Anzahl der Fehlversuche abhängigen Zeitintervall, erneut gestartet. 
Mit dem Set-Befehl restartSendqueue kann die Abarbeitung der Queue auch manuell angestartet werden (zum Beispiel nach einer Synology Wartung).

Mit dem Kommando:

 set <Name> asyncSendItem <Item>

werden Nachrichten an den oder die Chatempfänger gesendet. Je nach dem zu versendenden Inhalt variiert der Inhalt von '''<Item>'''.
Nachfolgend sind die verschiedenen Varianten, wie '''<Item>''' gefüllt werden kann, dargestellt.



* die einfachste Möglichkeit eine '''Textnachricht''' [an user1] zu senden
: <pre>First line of message to post.\nAlso you can have a second line of message. [users="user1"]</pre>


* eine '''Textnachricht''' [an user1] mit dem text-Tag senden
: <pre>text="First line of message to post.\nAlso you can have a second line of message." [users="user1"]</pre>


* einen '''Link''' [an user1] senden
: <pre>text="https://www.synology.com" [users="user1"]</pre>


* eine andere Variante einen '''Link''' [an user1 und user2] senden 
: <pre>text="Check this!! <https://www.synology.com|Click here> for details!" [users="user1,user2"]</pre>


* eine '''Datei''' [an user1 und user2] senden. Die Datei muss über die angegebene URL (fileUrl) für den Synology Chat Server zugreifbar sein. Die maximale Größe zum Hochladen von Dateien beträgt '''32 MB'''.
: <pre>text="a fun image" fileUrl="http://imgur.com/xxxxx" [users="user1,user2"]</pre>


: Die Empfänger [users=] sind optional falls der/die Empfänger im Attribut "defaultPeer" bereits angegeben wurden.
: Ein im "asyncSendItem" angegebener Empfänger hat immer Vorrang vor einem eventuell gesetzem Attribut "defaultPeer".

: Die zu sendenden Nachrichten werden zunächst in eine interne Sendqueue gestellt und sofort versendet, sofern der Bot die Nachricht : übermitteln konnte. Bei auftretenden Fehlern wird der Sendvorgang in Abständen wiederholt, wobei der Abstand zwischen den
: Sendeversuchen mit der Anzahl der erfolglosen Versuche ansteigt. 


* eine '''SVG Plot-Datei''' [an user1 und user2] senden. Nach dem Keywort '''svg''' ist der Name des SVG Devices anzugeben dessen Plot als Image versendet werden soll (Perl Modul '''Image::LibRSVG''' muß installiert sein).
: <pre>text="aktuelles Plotfile" svg="<SVG-Device>[,<Zoom>][,<Offset>]" [users="user1,user2"]</pre>


: Die Empfänger [users=] sind optional falls der/die Empfänger im Attribut "defaultPeer" bereits angegeben wurden.
: Ein im "asyncSendItem" angegebener Empfänger hat immer Vorrang vor einem eventuell gesetzem Attribut "defaultPeer".
: Ist kein text="..." angegeben, wird per default der Name des SVG Devices eingesetzt und als Text versendet.
: Mit '''Zoom''' und '''Offset''' können der Zoom-Level, z.B.  hour, day, week, month oder year eingestellt, sowie ein anderes Zeitintervall, z.B. -1, -2, eingestellt werden. Zu weiteren Infos siehe [https://fhem.de/commandref_DE.html#SVG SVG] Attribut fixedrange.
: Das zu versendende File wird im Verzeichnis '''/opt/fhem/www/images''' erstellt.


* ein '''interaktives Objekt (Schaltfläche)''' an Chatempfänger senden <br><br>

: Der Bot kann interaktive Objekte (Aktionen) anhängen. Zurzeit werden Schaltflächen für interaktive Objekte bereitgestellt.
: Im Feld '''attachments''' werden die zu sendenden Daten als Array im JSON Format eingefügt.  Das Feld '''actions''' enthält ein Array von Aktionsobjekten (Schaltflächen). Es können mehrere Schaltflächen separiert durch Komma angegeben werden.

  <pre>
  text="<Mitteilungstext>" 
  attachments="[{
                "callback_id": "<Text für Reading recCallbackId>", "text": "<Überschrift des Buttons>", 
                "actions":[
                           {"type": "button", "name": "<Name>", "value": "<Wert>", "text": "<Text>", "style": "<Farbe>"}
                          ]
               }]"
  </pre>

: Der set-Befehl '''asyncSendItem''' kann mehrzeilige Eingaben verarbeiten. Dadurch kann eine solche Anweisung übersichtlich strukturiert dem Modul übergeben werden. <br>

: Die angegeben '''callback_id''' ist ein beliebiger Text, der den Vorgang beschreibt. Betätigt der Chatuser den gesendeten Button, wird dieser Text im Reading '''recCallbackId''' des Chatbot-Devices eingefügt.

: Konkrete Beispiele zur Anwendung sind im Abschnitt [[#Interaktionen mit Schaltflächen|Interaktionen mit Schaltflächen]] beschrieben. Weitere Informationen Intergrationsmöglichkeiten von Aktionen sind in der [https://www.synology.com/de-de/knowledgebase/DSM/help/Chat/chat_integration Synology Online-Hilfe] verfügbar.




Zu Hinweisen bezüglich des Textversands siehe auch [[#Beschränkungen und Known Bugs|Beschränkungen und Known Bugs]].



'''Beispiel für den Dateiversand:'''

Es soll eine Kameraaufnahme an die im Attribut "defaultPeer" angegebenen Empfänger gesendet werden. Dadurch kann auf die Angabe der Empfänger im Tag "users=" verzichtet werden.

<pre>
 set <Name> asyncSendItem text="letzte Aufnahme von Kamera" fileUrl="http://sdcam.myds.me:8081/surveillance/Hauseingang/20191124AM/Hauseingang-20191124-103741-1574588261.mp4"
</pre>


<br>

= Get =

<br>
; chatUserlist: erstellt eine Liste der für den Bot sichtbaren Usern. Sollten keine User gelistet werden, muss den Usern auf der Synology die Berechtigung für die Chat-Anwendung zugewiesen werden.

; chatChannellist: erstellt eine Liste der für den Bot sichtbaren Channels

; storedToken: zeigt den gespeicherten Token an

; versionNotes: listet wesentliche Versionsänderungen auf



== Synology Chat User auflisten ==

Eine Liste der verfügbaren Chat User wird mit 

 get <Name> chatUserlist

abgerufen. Die erscheinenden Usernamen können als Default-Empfänger im Attribut "defaultPeer" gespeichert werden. Eine Mehrfachauswahl ist möglich.



<br>

= Attribute =

<br>
; defaultPeer: ein oder mehrere (default) Empfänger für Nachrichten. Kann mit dem "users=" Tag im Befehl "asyncSendItem" übersteuert werden.

; showTokenInLog: wenn gesetzt wird im Log mit verbose 4/5 der übermittelte Bot-Token angezeigt. (default: 0)

; httptimeout: stellt den Verbindungstimeout zum Chatserver ein (default 20 Sekunden)

; allowedUserForSet: benennt die Chat-User, die Set-Kommandos in FHEM auslösen dürfen wenn der Slash-Befehl '''/set''' empfangen wurde (default: alle User erlaubt)

; allowedUserForGet: benennt die Chat-User, die Get-Kommandos in FHEM auslösen dürfen wenn der Slash-Befehl '''/get''' empfangen wurde (default: alle User erlaubt)

; allowedUserForCode: benennt die Chat-User, die Perl-Code in FHEM auslösen dürfen wenn der Slash-Befehl '''/code''' empfangen wurde (default: alle User erlaubt)

; allowedUserForOwn: benennt die Chat-User, die die im Attribut "ownCommand" definierte Kommandos in FHEM auslösen dürfen (default: alle User erlaubt)

; ownCommandx: definiert ein '''<Slash-Befehl> <Kommando>''' Paar. Der Slash-Befehl und das Kommando sind durch ein Leerzeichen zu trennen. Beim Empfang des Slash-Befehls wird das zugehörige Kommando ausgeführt.
::: '''Beispiel:'''
::: attr <SSChatBot> ownCommand1 /Wetter get MyWetter MAXTempDay 
::: attr <SSChatBot> ownCommand2 /Wetter get MyWetter wind_speed

: Liefert beim Empfang von "/Wetter" den Rückgabewert von "get MyWetter MAXTempDay" und von "get MyWetter wind_speed" an den Chat zurück.


<br>

= Nachrichten und Befehle aus dem Chat an FHEM senden =

<br>
[[Datei:recdata.PNG|right|thumb|300px|empfangene Chat Daten]]
Aus dem Synology Chat können Nachrichten oder Befehle an FHEM gesendet werden.
Dazu ist zunächst der Bot, mit kommuniziert werden soll, dem persönlichen Chat hinzuzufügen. Im linken Menü bei '''Bots''' auf das '''+''' klicken, den relevanten Bot auswählen und mit Klick auf '''Eingabe''' fügt den Bot hinzu.

<gallery>
File:tofhem1.PNG 
File:tofhem2.PNG
</gallery>

Hat man den Bot-Kanal betreten, können Textnachrichten oder Befehle an den Bot gesendet werden. 
Die empfangenen Daten werden im SSChatBot Device in verschiedenen, mit dem Präfix '''rec''' beginnenden Readings dargestellt. 
Die Inhalte der Readings sind von der empfangenen Nachricht abhängig.


Weiterhin können Set- und Get-Befehle an FHEM gesendet, sowie Perl-Code in FHEM ausgeführt werden.
Die Rückgabe-Daten der ausgeführten Befehle werden an den Synology Chat übermittelt.

Diese Möglichkeiten sind zuvor im Synology Chat als sogenannte '''Slash-Befehle''' zu konfigurien.


<br>
== Slash-Befehle im Synology Chat konfigurieren ==

<br>
[[Datei:slash1.PNG|right|thumb|300px|Slash-Befehl für "set" konfigurieren]]
Klicken Sie dazu auf das Symbol '''Profilfoto''' oben rechts in der aufgerufenen Synology Chat-Applikation und wählen Sie '''Einbindung'''. Wählen sie dann '''Slash-Befehl''' und erstellen einen neuen Schrägstrich-Befehl oder verändern einen vorhandenen Befehl.

In dem Beispiel werden die Felder für set-Befehle konfiguriert:

* '''Namen anpassen''' : ein Name für den neuen Slash-Befehl
* '''Befehl''' : der Befehl, in diesem Beispiel "set".
* '''Anfrage-URL''' : hier wird wieder der Inhalt des Internals '''OUTDEF''' hineinkopiert
* '''Befehls-Anweisungen''' : hier gibt man einen ergänzenden Text ein, der als Ausfüllhilfe bei der Eingabe eines "/" angezeigt werden soll. <br>Zum Beispiel wird "<Device> <Befehl>" später bei Eingabe von "/" als "/set <Device> <Befehl> [Beschreibung]" angezeigt.
* '''Beschreibung''' : ergänzende Beschreibung zum Befehl, z.B. "um einen Set-Befehl an FHEM zu senden". <br>Dadurch wird später bei Eingabe eines "/" der Eintrag als "/set <Device> <Befehl> um einen Set-Befehl an FHEM zu senden" in der Befehlsliste angezeigt.

[[Datei:slash2.PNG|left|thumb|300px|Befehls-Anweisungen und Beschreibung]]
[[Datei:slash3.PNG|right|thumb|300px|empfangener Befehl und Rückgabewert]]












Ist die Konfiguration abgespeichert, kann nun durch Eingabe von:

 /set <Device> <Befehl>

eine Set-Anweisung an FHEM ausgeführt werden. Zum Beispiel wird mit:

 /set CamHE1 snap

[[Datei:slash4.PNG|right|thumb|300px|Rückgabewert im Chat]]
ein Schnappschuss mit der Kamera CamHE1 ausgeführt. Die Kommunikation mit dem Chat zeigen die Readings im SSChatBot Device. Der von FHEM gemeldete Ausführungsstatus des Befehls wird an den Chat zurück gesendet.

Entsprechendes gilt ebenfalls für die Konfiguration der get- und code-Befehle.


<br>

== FHEM-Befehle aus dem Chat an FHEM senden ==

<br>
Um Befehle an FHEM zu senden, werden Slash-Befehle (/) verwendet. Sie sind vor der Verwendung wie oben beschrieben im Synology Chat und ggf. zusätzlich im SSChatBot Device (User spezifische Befehle) zu konfigurieren.
  
Folgende Befehlsformen werden unterstützt:

* '''/set'''
* '''/get'''
* '''/code''' 
* '''/<User spezifischer Befehl>'''



Zur Unterscheidung verschiedener Ziele ist z.B. auch '''set_test''', '''set_prod''', '''get_prod''', usw. möglich. Der Befehl '''muß''' mit set, get oder code beginnen, damit er dementsprechend erkannt wird.

Nachfolgend dargestellte Syntax ausgehender Befehle wird vom SSChatBot Device akzeptiert. Die unterschiedlichen Varianten dienen dazu, Slash-Befehle für verschiedene Ziele (Testsysteme, Produktivsystem) definieren zu können.


=== Set-Befehle ===

Bei der Definition des Slash-Befehls ist diese Syntax einzuhalten:

* '''Befehl :''' set[.*]  (es dürfen keine Leerzeichen innerhalb des set-Tags enthalten sein)

Zum Beispiel werden alle diese Varianten in FHEM als "set" ausgeführt.  

* /set <Device> <Befehl>
* /set_test <Device> <Befehl>
* /setProd <Device> <Befehl>

Wird zum Beispiel nach entsprechender Konfiguration im Chat der Befehl '''/set Lampe on''' abgesendet, wird im FHEM der set-Befehl "Lampe on" ausgeführt. Dabei wird die Berechtigung für den Chat-User mit dem Attribut "allowedUserForSet" geprüft.


<br>

=== Get-Befehle ===

Bei der Definition des Slash-Befehls ist diese Syntax einzuhalten:

* '''Befehl :''' get[.*]  (es dürfen keine Leerzeichen innerhalb des get-Tags enthalten sein)

Zum Beispiel werden alle diese Varianten in FHEM als "get" ausgeführt. 

* /get <Device> <Befehl>
* /get_test <Device> <Befehl>
* /getProd <Device> <Befehl>

Wird zum Beispiel nach entsprechender Konfiguration im Chat der Befehl '''/getProd eg.wz.wandthermostat regList''' abgesendet, wird im FHEM der get-Befehl "eg.wz.wandthermostat regList" ausgeführt. Dabei wird die Berechtigung für den Chat-User mit dem Attribut "allowedUserForGet" geprüft.


<br>

=== Code-Befehle ===

Bei der Definition des Slash-Befehls ist diese Syntax einzuhalten:

* '''Befehl :''' code[.*]  (es dürfen keine Leerzeichen innerhalb des code-Tags enthalten sein)

In FHEM auszuführender Perl-Code muß in {} eingeschlossen werden.  

* /code {return "das ist ein Return Test";}
* /code_test {my $ret = "das ist ein Return Test"; return $ret;}
* /codeProd {function()}

Wird zum Beispiel nach entsprechender Konfiguration im Chat der Befehl '''/codeProd {modrgallcalview}''' abgesendet, wird im FHEM die Funktion "modrgallcalview" aufgerufen und das Ergebnis zurück geliefert. Dabei wird die Berechtigung für den Chat-User mit dem Attribut "allowedUserForCode" geprüft.


<br>

=== User spezifische Befehle ===

Neben den oben benannten Möglichkeiten können auch eigene Slash-Befehle konfiguriert werden. Im folgenden Beispiel soll bei Eingabe von "'''/Wozi_Temp'''" die gemessene Temperatur des Wohnzimmers geliefert werden.

Im Chat wird der Slash-Befehl "Wozi_Temp" definiert:

* '''Namen anpassen''' : Wozi_Temp
* '''Befehl''' : Wozi_Temp
* '''Anfrage-URL''' : hier wird wieder der Inhalt des Internals '''OUTDEF''' des anzufragenden SSChatBot hineinkopiert
* '''Befehls-Anweisungen''' : 
* '''Beschreibung''' : gibt die Wohnzimmertemperatur zurück

Im SSChatBot Device wird mit dem Attribut '''ownCommandx''' das auszuführende Kommando festgelegt. Dabei ist "x" eine laufende Ziffer, beginnend mit "1".

Beispiel:

* attr <SSChatBot> ownCommand1 /Wozi_Temp {ReadingsVal("eg.wz.wandthermostat","measured-temp",0)}
* attr <SSChatBot> ownCommand2 /Wetter get MyWetter wind_speed
* ...

Wird nun im Chat der Befehl '''/Wozi_Temp''' ausgelöst, erfolgt in FHEM die Abfrage des Readingswertes von "measured-temp" des Devices "eg.wz.wandthermostat" bzw. mit dem Befehl '''/Wetter''' die Ausführung von "get MyWetter wind_speed". Dabei wird jeweils die Berechtigung für den Chat-User mit dem Attribut "allowedUserForOwn" geprüft.
Die Ergebnisse werden an den Chat zurück gesendet.


<br>

= Beispiele =

<br>
== Auslösen eines Set-Befehls in FHEM durch eine Synology Surveillance Station Aktionsregel ==

<br>
In der Synology Kamera-Applikation (Synology Surveillance Station) kann über die Definition von Regeln im Aktionsregeleditor beim Empfang verschiedener Ereignisse bzw. auch regelmäßig unter anderem ein Webhook aufgerufen werden.

Nachfolgende Beispiele zeigen, wie eine "Aktion" im Aktionsregeleditor ausgefüllt werden kann, um eine Lampe zu schalten wenn eine Kamera eine Bewegung registriert. Im Beispiel wird vorausgesetzt, dass ein SSChatBot (Name "SynChatBot") mit dem dazu gehörigen FHEMWEB-Device "WEBSSChatBot" erfolgreich definiert wurde.

Zunächst wird auf der Seite "Ereignis" des Regeleditors die Ereignisquelle "Kamera", bei Gerät der SVS-Name der Kamera und Ereignis "Bewegung entdeckt" ausgewählt.

Auf der nächsten Seite "Aktion" können nun verschiedene Optionen verwendet werden.
[[Datei:arule1.PNG|right|thumb|300px|Definition POST-Methode]]
<br>
* '''Verwenden der POST-Methode'''

<br>
1. Wähle Aktionsgerät '''Webhook''' aus. <br>
2. Feld '''URL''': Hier wird wieder der Inhalt des Internals '''OUTDEF''' des angelegten SSChatBot-Devices (SynChatBot) hineinkopiert.<br>
:Ergänzt wird die Angabe noch durch: 
:::* &user_id=<UserId eines validen Chatusers> (kann mit "get SynChatBot chatUserlist" ermittelt werden)
:::* &username=<Name des zur UserId gehörenden Users>
:::* &token=<Token des SSChatBots> (kann mit "get SynChatBot storedToken" ermittelt werden)
:z.Bsp: <pre>http://fhem.fqdn:8086/sschat/outchat?botname=SynChatBot&fwcsrf=5de11123&user_id=4&username=Martha&token=mNJa1brQOPeQ4xwXw1i7sTVNmK2mVG1H3myFTb3NwSlDVJn1jgYdSwEM0zmD6NRl </pre>
 
3. Methode POST definieren. <br>
4. Inhaltstyp '''text/plain''' festlegen. <br>
5. Im Feld Text das Keyword '''&text''' mit dem gewünschten FHEM-Befehl hinterlegen. Zum Beispiel: <br>
:::* &text=/set eg_kz_ostseite on

[[Datei:arule2.PNG|right|thumb|300px|Definition GET-Methode]]
<br>
* '''Verwenden der GET-Methode'''

<br>
1. Wähle Aktionsgerät '''Webhook''' aus. <br>
2. Feld '''URL''': Hier wird wieder der Inhalt des Internals '''OUTDEF''' des angelegten SSChatBot-Devices (SynChatBot) hineinkopiert.<br>
:Ergänzt wird die Angabe noch durch: 
:::* &user_id=<UserId eines validen Chatusers> (kann mit "get SynChatBot chatUserlist" ermittelt werden)
:::* &username=<Name des zur UserId gehörenden Users>
:::* &token=<Token des SSChatBots> (kann mit "get SynChatBot storedToken" ermittelt werden)
:::* &text=<URL encoded FHEM-Befehl>
:z.Bsp: <pre>http://fhem.fqdn:8086/sschat/outchat?botname=SynChatBot&fwcsrf=5de11123&user_id=4&username=Martha&token=mNJa1brQOPeQ4xwXw1i7sTVNmK2mVG1H3myFTb3NwSlDVJn1jgYdSwEM0zmD6NRl&text=%2Fset%20eg_kz_ostseite%20on </pre>
 
3. Methode GET definieren. <br>

<br>
Bei beiden Varianten wird die Gültigkeit des ChatBot-Tokens, des CSRF-Tokens sowie die Berechtigung des Chat-Users zur Ausführung von Set-Befehlen über das SSChatBot-Device geprüft. Mit dem Attribut '''allowedUserForSet''' kann der/die berechtigte(n) User für Set-Befehle definiert werden um die Sicherheit weiter zu erhöhen.

Wird ein angeforderter Befehl durch der ChatBot ausgeführt, erfolgt über den Kanal des Bots eine Rückmeldung des ausgeführten Befehls (oder einer eventuellen Fehlermeldung) im Synology Chat.


<br>
== Interaktionen mit Schaltflächen ==

<br>
Mit dem Chatbot-Device können Schaltflächen an die Chatuser gesendet und deren Reaktion darauf ausgewertet werden. Damit sind Interaktionen mit Nutzern und aufbauend darauf entscheidungsabhängige Steuerungen realisierbar.


=== eine einfache Schaltfläche versenden und die Bestätigung empfangen ===


[[Datei:sschat0.PNG|right|thumb|300px|Schaltfläche gesendet]]
Um eine einzelne Schaltfläche mit einem beschreibenden Text an den Chat zu senden, wird der set-Befehl '''asyncSendItem''' verwendet:

<pre>
set <Name> asyncSendItem text="Bitte bestätigen !" 
attachments="[
              {
              "callback_id": "Bestaetigung", "text": "einfache Schaltfläche", 
              "actions":[
                         {"type": "button", "name": "response", "value": "ok", "text": "OK", "style": "green"}
                        ]
              }
             ]"
</pre>
[[Datei:sschat1.PNG|right|thumb|300px|Anwort nach Betätigung einer Schaltfläche empfangenen]]

Das Chatbot-Device kann mehrzeilig strukturierte Befehle im set '''asyncSendItem''' verarbieten. 
Die angegeben '''callback_id''' ist ein beliebiger Text, der den Vorgang beschreibt. Betätigt der Chatuser den gesendeten Button, wird der Text '''Bestätigung''' im Reading '''recCallbackId''' des Chatbot-Devices eingefügt.



Im Feld '''actions''' werden die Eigenschaften der übertragenen Schaltfläche festgelegt: <br>


* '''type:''' "button" (fix)
* '''name:''' Freitext für einen Namen der Schaltfläche 
* '''value:''' der Wert der Schaltfläche der bei Betätigung an das Device zurück gesendet wird. 
* '''text:''' in der Schaltfäche angezeigter Beschreibungstext 
* '''style:''' Farbe der Schaltfläche. Es können zur Zeit verwendet werden: green, grey, red, orange, blue, teal




Der gesamte String des Feldes '''actions''' wird nach Betätigung des Buttons durch den User im Chat im Reading '''recActions''' eingefügt. 
Somit kann auf das Event :

 2020-03-14 09:28:27 SSChatBot SynChatBot recActions: type: button, name: response, value: ok, text: OK, style: green

reagiert werden und nach Auswertung des Textes '''value: ok''' in einem Notify zum Beispiel ein Schaltvorgang durchgeführt werden. 
Das Reading '''recActionsValue''' extrahiert den Wert von value aus dem Feld actions und kann somit direkt durch ein Notify ausgewertet werden. 


<br>

=== mehrere Schaltflächen versenden und eine Auswahl empfangen ===

[[Datei:sschat2.PNG|right|thumb|300px|mehrere Schaltflächen gesendet]]
Der Chatbot kann auch mehrere Schaltflächen versenden um dem Nutzer eine Auswahl von Alternativen zu ermöglichen. Das Feld '''value''' der ausgewählten '''action''' wird nach Betätigung des entsprechenden Buttons im Reading '''recActions''' enthalten sein:

<pre>
set <Name> asyncSendItem text="Bitte annehmen mit 'JA' oder ablehnen mit "NEIN" 
attachments="[
              {
              "callback_id": "Abstimmung", "text": "", 
              "actions":[
                         {"type": "button", "name": "resp", "value": "yes", "text": "JA", "style": "green"},
                         {"type": "button", "name": "resp", "value": "no", "text": "NEIN", "style": "red"}
                        ]
              }
             ]"
</pre>
[[Datei:sschat3.PNG|right|thumb|300px|Auswahl einer Schaltfläche empfangen]]



Drückt der Chat-User zum Beispiel die Taste "NEIN", wird das Reading '''recActions''' den Wert '''value: no''' enthalten. Der daraus resutlierende Event kann wiederum verwendet werden abhängig vom value-Inhalt alternative Schaltvorgänge auszuführen.
Einfacher: Das Reading '''recActionsValue''' extrahiert den Wert von value aus dem Feld actions und kann somit direkt durch ein Notify ausgewertet werden.  



Die Anzahl der Elemente in actions ist nicht begrenzt. Es können weitere Array-Elemente durch Komma getrennt eingefügt werden. Damit ist zum Beispiel die Übertragung von mehreren Auswahlflächen möglich, die jeweils alternative Uhrzeiten als Responsetext enthalten:


<pre>
set <Name> asyncSendItem text="Bitte eine Uhrzeit auswählen" 
attachments="[
              {
              "callback_id": "Auswahl", "text": "", 
              "actions":[
                         {"type": "button", "name": "resp", "value": "19:00", "text": "19:00", "style": "green"},
                         {"type": "button", "name": "resp", "value": "20:00", "text": "20:00", "style": "green"},
                         {"type": "button", "name": "resp", "value": "21:00", "text": "21:00", "style": "green"},
                         {"type": "button", "name": "resp", "value": "22:00", "text": "22:00", "style": "green"}
                        ]
              }
             ]"
</pre>

[[Datei:sschat4.PNG|right|thumb|300px|mehrere Schaltflächen gesendet]]
Schaltflächen können auch Slash-Kommandos enthalten, die je nach gedrückter Taste als Antwort in '''value''' von '''actions''' enthalten sind. Diese Slash-Kommandos in der Antwort werden durch das Modul unmittelbar erkannt und ausgeführt.

Dieser Aufruf sendet vier Schaltflächen an den Chatuser:

<pre>
set <Name> asyncSendItem 
text="Hallo ich bin Dein ChatBot! Was kann ich für Dich tun?" 
attachments="[{
        "callback_id": "menue", "text": "Wähle ein Menü aus!",
        "actions":[
                  {"type": "button", "name": "responseHM", "value": "hm", "text": "Hauptmenü", "style": "orange"},
                  {"type": "button", "name": "responseBCK", "value": "bck", "text": "Zurück", "style": "orange"},
                  {"type": "button", "name": "responseON", "value": "/set SW_TV on", "text": "TV An", "style": "green"},
                  {"type": "button", "name": "responseOFF", "value": "/set SW_TV off", "text": "TV Aus", "style": "green"}
                  ]
             }]"
</pre>

Wird die Taste '''"TV An"''' gedrückt, führt das SSChatBot-Device nach Prüfung der User-Berechtigung direkt den Befehl '''"/set SW_TV on"''' aus. Das Feld '''value''' kann natürlich auch ein vorher definiertes [[#User_spezifische_Befehle | ownCommand]] enthalten (z.B. /Wetter).


<br>

== Versenden von SVG-Plots ==

<br>
=== integrierter Versand ===

Seit der Version 1.7.0 ist der Versand von SVG-Plots integriert über das Kommando:
<pre>
set <name> asyncSendItem text="<Text>" svg="<SVG-Device>[,<Zoom>][,<Offset>]"
</pre>
möglich. 
Der nachfolgend beschriebene Weg ist dadurch nicht mehr notwendig, aber natürlich weiterhin möglich.


<br>

=== diskreter Versand ===
Das SVG-Modul bietet mit der Funktion '''plotAsPng''' (Hinweis: das Perl Modul Image::LibRSVG muß installiert sein) die Möglichkeit, Plot-Ausgaben in ein PNG-File umzuwandeln.
Um eine Datei zu versenden, muss diese Datei über einen Link durch den Synology Chat-Server zugreifbar sein.

Dazu wird zunächst eine kleine Routine in 99_myUtils eingestellt, die das zu versendende PNG-File in einem durch FHEMWEB zugreifbaren Verzeichnis erstellt.

<pre> 
####################################################################################
#       Ausgabe der SVG-Funktion "plotAsPng" in eine Datei schreiben
#       Die Datei wird im Verzeichnis "/opt/fhem/www/images" erstellt
#
#       Aufruf mit: PlotToFile('<Filename>.png','<Name-SVG-Device>')
#
####################################################################################
sub PlotToFile {
	my $file = shift;
	my $plot = shift;
	my $dir  = "/opt/fhem/www/images";
	
	open FILE, "> $dir/$file" or do {
	                                  Log (1, ">PlotToFile< can't open $dir/$file for write access !");
                                          return;
	                                };
    binmode FILE;
    print FILE plotAsPng($plot);
    close FILE;

return;
}
</pre>

Der Aufruf erfolgt mit '''PlotToFile('<Filename>.png','<Name-SVG-Device>')''', z.B.:

<pre>
PlotToFile('PlotToChat.png','SM_LogDB_RAM')
</pre>

Damit wird das File ''PlotToChat.png'' aus dem Plot des SVG-Devices ''SM_LogDB_RAM'' im Verzeichnis ''/opt/fhem/www/images'' erstellt.

Der Web-Zugriff kann über das WEBSSChatBot-Device erfolgen, welches bei der Definition des SSChatBots mit angelegt wurde. Den Namen dieses FHEMWEB-Devices ist im Internal '''FW''' des SSChatBot-Devices enthalten. Dieses Device ist automatisch durch ein CSRF-Token geschützt welcher bei der Angabe der Webseite mit angegeben werden muß.

Das nachfolgende Beispielnotify reagiert auf den Event '''".... user sendPng <SVG-Device>"''', der zum Beispiel von einem Dummy ausgelöst wurde, und versendet den Plot des darin enthaltenen '''<SVG-Device>''' mit dem SSChatBot-Device '''SynChatBot''':

<pre>
user:sendPng.*
{
  my $server = "xxx.xxx.xxx.xxx:xxxx/sschat";     # <IP>:<Port> des WEBSSChatBot-Devices (Internal FW des SSChatBot)
  my $file   = "PlotToChat.png";                  # Filename
  my $path   = "www/images";                      # Pfad
  my $csrf   = "xxxxxxxx";                        # CSRF-Token des WEBSSChatBot-Devices (Internal CSRFTOKEN)
  my $prot   = "http";                            # ggf. anpassen
  PlotToFile($file, $EVTPART1);
  CommandSet (undef, "SynChatBot asyncSendItem text=\"aktueller Plot $EVTPART1\" fileUrl=\"$prot://$server/$path/$file?%26fwcsrf=$csrf\" ");
}
</pre>


<br>

= Beschränkungen und Known Bugs =

<br>
Die Textnachrichten an den Chat dürfen bestimmte Zeichen nicht enthalten und werden entweder vor dem Versand ersetzt oder eliminiert.

* = -> sollen Gleichheitszeichen im Text übermittelt werden, muss die Form mit text-Tag gewählt werden, z.B. text="3+1=4" .

<br>

= Links =

Forumthread zu diesem Modul: https://forum.fhem.de/index.php/topic,105714.0.html    <br>
Synology KnowldgeBase: https://www.synology.com/de-de/knowledgebase/DSM/help/Chat/chat_desc