Schaffenburg

Projekt:Schaffenbot

Version vom 23. Oktober 2017, 22:47 Uhr von VinRisen360 (Diskussion | Beiträge)
Telegram-Bot.png

Telegram Bot Allgemein

Author: Paul Freudenberger / Marcel
GitHub Telegram Bot API: https://github.com/php-telegram-bot/core
GitHub Example Bot Template: https://github.com/php-telegram-bot/example-bot.git
GitHub Schaffenburg Template: https://github.com/Schaffenburg/telegram_bot_php.git

Bot erstellen

Bot anlegen via Telegram App

  • Starten Sie eine neue Konversation mit dem User 'BotFather'
  • Senden Sie die Nachricht '/newbot'
  • BotFather fragt Sie nun nach einem 'Anzeigenamen' für den Bot. Wählen Sie etwas, das Ihnen gefällt!
  • BotFather fragt Sie nach einem eindeutigen Bot-Username.
Der Name muss mit den Buchstaben 'bot' enden
Probieren Sie es solange weiter, bis Sie einen freien, guten Namen gefunden haben
  • MACHEN SIE EINEN SCREENSHOT VON DER NACHRICHT, DIE IHNEN BOTFATHER SENDET (DATEN NOTIEREN!)
  • Senden Sie die Nachricht '/setuserpic'
  • Senden Sie das gewünschte Profilbild an BotFather über den 'Büroklammer-Button'
  • Senden Sie die Nachricht '/setprivacy' (Wird benötigt, damit der Bot auch Nachrichten in Gruppen sendet, wenn bereits ein anderer Bot in die Gruppe sendet)
Daten von Schaffentest_bot:
Name: Lucy
Username: Schaffentest_bot
http://t.me/Schaffentest_bot
Token: 123456789: ABCdefGHIJklMnOP1QRStu_2VW3xYzAbCDe
https://core.telegram.org/bots/api

Webserver vorbereiten

Ab hier benötigen Sie einen funktionierenden Webserver.
Ich empfehle den LAMP-Server von Ubuntu Server 14.04 und höher

Folgendes sollte bereits konfiguriert sein:

  • Der Webserver muss über das Internet erreichbar sein
  • Es muss eine Domain auf dem Webserver registriert sein (entsprechenden virtual host konfigurieren)
  • Der Server muss über die Domain angesprechbar sein
  • Der Webserver muss https unterstützen (Am besten Let's Encrypt Certificate einbinden)
  • Es sollte bequem möglich sein Änderungen in das Webroot-Verzeichnis einzuspielen (sFTP-Zugang oder Git)

Bot Template Installation

Holen Sie sich das Template example-bot von GitHub mit der folgenden URL:
https://github.com/php-telegram-bot/example-bot

Bot Template auf eigene Bedürfnisse anpassen

Gehen Sie durch die folgenden .php files und pflegen Sie Werte 

$bot_api_key  = '123456789:ABCdefGHIJklMnOP1QRStu_2VW3xYzAbCDe';
$bot_username = 'Uniquename_bot';
$hook_url     = 'https://yourdomain.me/hook.php';

ein (s. NOTIZEN VON SCHRITT 1.1):

  • cron.php
  • hook.php
  • set.php
  • unset.php

Abschließend kopieren Sie das angepasste Bot-Template auf das Webroot Verzeichnis ihres Webservers. (Bsp.: /var/www/telegrambot-webroot/)

Composer einrichten

(Composer ist ein PHP-Tool, dass automatisch alle Libraries nachlädt, die der telegram bot benötigt)
Quelle: https://getcomposer.org/download/

Abhängigkeiten von composer installieren: (Prüfen mit frischer Installation)

sudo apt-get install curl php5-cli git php5-curl

Composer installieren

cd ~
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php -r "if (hash_file('SHA384', 'composer-setup.php') === 
'669656bab3166a7aff8a7506b8cb2d1c292f042046c5a994c43155c0be6190fa0355160742ab2e1c88d40d5be660b410') { echo 'Installer verified'; } else { echo 
'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"
php composer-setup.php
php -r "unlink('composer-setup.php');"

ACHTUNG: Die Befehle könnten sich in zukünftigen Versionen von Composer ändern Immer die Seite https://getcomposer.org/download/ als Referenz nehmen

Composer als globalen shell Befehl einpflegen

sudo mv composer.phar /usr/local/bin/composer

Composer ausführen, um telegram dependancies zu installieren

Für die folgenden Befehle benötigt Ihr Shell-User Schreibrechte auf das telegrambot-webroot Verzeichnis
(sudo chown -R youruser:youruser /var/www/telegrambot-webroot/)
(sudo chmod -R 664 /var/www/telegrambot-webroot/) 

cd /var/www/telegrambot-webroot/
composer update

Bot Funktionen aktivieren

Rufen Sie die folgende URL in einem Browser auf:
https://yourdomain.me/set.php

Es lädt ca. 3 Sekunden, danach sollte 'Webhook was set' auf der Website angezeigt werden.

Entfernen Sie den Kommentar aus cron.php und hook.php bei: 

$commands_paths = [
//    __DIR__ . '/Commands/',
];

Bot Erweiterung für Spacestatus

Zunächst muss eine SQL-Datenbank angelegt werden. (Wird für das Tracking des Spacestatus benötigt) Zunächst legt man eine neue SQL-Datenbank incl. User und Passwort mit folgendem Befehl an: mysql -u sqlrootuser -p'p@ssw0rd' -e "CREATE USER 'dbuser'@'localhost' IDENTIFIED BY 'dbpass';CREATE DATABASE dbname;GRANT ALL PRIVILEGES ON dbname . * TO 'dbuser'@'localhost';" mysql -u sqlrootuser -p'p@ssw0rd' dbname < structure-schaffenburg.sql
Download the file here: Datei:Structure-schaffenburg.zip

Nehmen Sie jetzt folgende Änderungen an den Dateien cron.php und hook.php vor: Entfernen Sie die Kommentare bei 

//$mysql_credentials = [
//    'host'     => 'localhost',
//    'user'     => ,
//    'password' => ,
//    'database' => ,
//];

und geben Sie die entsprechenden credentials ein.

Entfernen Sie außerdem alle Kommentare bei: 

//$telegram->enableMySql($mysql_credentials);

Cron-Job für Bot Commands anlegen

Bots können auch Zeitgesteuert einen Command ausführen. Diese geschieht über sogenannte crontabs. Zum Anlegen eines crontabs, geben Sie folgende Befehl direkt in die Shell ein: 

crontab -e
* * * * * php /var/www/telegrambot-webroot/cron.php

Schaffenburg Data Tracking

Es gibt eine Möglichkeit Daten aller Art zu loggen.
Der Schaffenburg-Telegram-Bot kann auf diese Daten zugreifen und sie der Allgemeinheit zur Verfügung stellen.
Aktuell sind folgende Daten in das Data-Tracking eingebunden:

  • Status der Räumlichkeiten von Schaffenburg e.V. (Offen, Geschlossen)
  • Temperatur in den Räumlichkeiten von Schaffenburg e.V.
  • Mülleimerstatus (Regelmäßiges leeren der Mülleimer)
  • Anwesenheits-Summary (Personen können freiwillig angeben, ob sie in den Räumlichkeiten sind/sein werden)

Daten loggen

Über die folgende URL können Daten ins Logging aufgenommen werden:
http://codeblatz.ddns.net/soap.php?token=<secret token>&tag=<string>&value=<string>
Erklärung:

  • token: Damit nicht jeder einfach Daten loggen kann, muss ein valider Token in der URL mitgegeben werden.
    Ein neuer Token kein beim Benutzer Paul Freudenberger angefordert werden.
  • tag: Ein Search-Tag, der mit den Infos hinterlegt wird.
    Es sollte ein einzelnes Wort sein, dass beschreibend für den Wert ist. (Beispiel: temperature)
  • value: Der eigentliche Wert, den man loggen möchte.
    Hier kann eigentlich alles mitgegeben werden.

RÜCKGABEWERT BEI ERFOLGREICHEM LOGGEN:
Value successfully logged

Daten auslesen

Über die folgende URL können die Daten wieder ausgelesen werden:
http://codeblatz.ddns.net/soap.php?token=<secret token>[&tag=<string>][&limit=100]
Erklärung:

  • token: Damit nicht jeder einfach Daten auslesen kann, muss ein valider Token in der URL mitgegeben werden.
    Ein neuer Token kein beim Benutzer Paul Freudenberger angefordert werden.
  • tag: OPTIONAL: Filtert die LOG-Ausgabe auf Werte mit dem angegebenen Search-Tag.
    Wenn kein tag angegeben wird, werden alle Datensätze aus dem Log ausgegeben.
  • limit: OPTIONAL: Die Anzahl der Datensätze bei der Ausgabe festlegen.
    Wenn kein limit angegeben wird, wird nur der neuste Datensatz ausgegeben

AUSGABEFORMAT:
Die Daten werden in Form eines JSON-Files ausgegeben.
Beispiel:
{"time":"22.10.2017 00:00:01","spacetemperature":20.5,"metric":"C (degree Celsius)"}

Nett-to-know

Folgende Infos über den Bot könnten für Developer interessant sein:

  • Es gibt einen Unterordner /Commands im Root-Verzeichnis des Telegram Bots (Hier liegen alle Befehle, die der Bot kann). Schauen Sie dort, wenn Sie neue Commands einführen wollen
  • /Commands/GenericCommand.php (Dieser Command wird getriggert, wenn ein Command getriggert wird, den es nicht gibt)
  • /Commands/GenericmessageCommand.php (Wird getriggert, wenn ein Text an den Bot oder in eine Gruppe mit dem Bot geschrieben wird)
  • /Commands/CallbackqueryCommand.php (Erklärung: ???)
  • /Commands/WeatherCommand.php (Mit diesem Command kann das Wetter abgefragt werden.)
Damit das funktioniert, muss man sich auf der folgenden Webseite registrieren:
https://home.openweathermap.org/users/sign_up 

Danach muss man sich ein wenig gedulden. (Ca. 10 Minuten - 1 Stunde)
Nach dieser Zeit kann man sich den erforderlichen API Key unter der folgenden URL abholen:
https://home.openweathermap.org/api_keys 

Beispiel für einen API_Key: z825bl24x5xx1p44w9i6c3g1g22ve299
Um den API_Key im telegram php bot zu verwenden, fügen Sie folgende Zeile in der hook.php ein:
$telegram->setCommandConfig('weather', ['owm_api_key' => 'z825bl24x5xx1p44w9i6c3g1g22ve299']);

Man kann auch über den Browser testen, ob der API_Key funktioniert. Hierfür ruft man folgende URL auf:
http://api.openweathermap.org/data/2.5/weather?q=Berlin&units=metric&APPID=z825bl24x5xx1p44w9i6c3g1g22ve299

  • Die meisten Commands haben in ihren Klassen "extends UserCommand" stehen. Dies bedeutet jeder Nutzer kann diesen Command triggern
  • Manche Commands haben in ihren Klassen "extends AdminCommand" stehen.Dies bedeutet, nur Nutzer deren ID unter /[webroot]/hook.php im Array $admin_users = []; gelistet sind können diesen Command triggern
  • Manche Commands haben in ihren Klassen "extends SystemCommand" stehen. Dies bedeutet der Command wird nicht unter /help aufgelistet, es gibt ihn aber

EXTRA

Potentielles Tool zur Auswertung der Langzeit Logging-Daten: Highstocks

MySQL Store messages/users/chats

(Optional, WIRD NICHT VON SCHAFFENBURG e.V. VERWENDET)
Dieser Abschnitt beschäftigt sich mit der getUpdatesCLI.php
Diese Datei ist dafür gedacht alle Vorgänge, die der Bot mitbekommt in einer SQL-Datenbank zu dokumentieren
Damit diese Funktion genutzt werden, muss zunächst eine SQL-Datenbank angelegt werden.
Einen SQL-File hierfür gibt es auf der URL: https://github.com/php-telegram-bot/core#getupdate-installation
Die Datei structure.sql muss in SQL importiert werden.
Außerdem muss die folgende Variable mit den entsprechenden Logindaten befüllt werden: 

$mysql_credentials = [
    'host'     => 'localhost',
    'user'     => ,
    'password' => ,
    'database' => ,
];

[Mehr Dokumentation folgt, wenn dieser Punkt ausreichend Relevanz bekommt]

Angefragte Features

Feature Notizen Umgesetzt zu X%
/brb Status hinzufügen (Bin gleich wieder da) Antrag Fabs
Abstimmung Funktion zum Abstimmen im Bot einbauen. Wird wahrscheinlich Voraussetzung für Ban / Mute Antrag Paul
Müllüberwachung Abfrage des Status vom ESP Karsten (Müll muss gelehrt werden?), automatisch rot nach 3 Tagen, Grün per Knopfdruck am Müll; Wenn kritisch ("rot") automatischer Hinweis vom Bot wenn sich der Spacestatus auf "offen" ändert (jmd zum leeren da ist); Hinweis vom Bot beim Wechsel von grün zu rot und zunehmend energischere Hinweise, wenn nach gewissen Abständen niemand etwas unternommen hat Antrag Karsten/Steven
Alias/Änderung /heikomaas statt /mute Antrag Lukas
Nyus-Letter Nyus-Lettter auch in Private chat Antrag Hendi
Interface URL-Kommando &format=(GP,JSON) (GP=Gnuplotfreundliches Textformat, to be specified) Antrag Hendi
Totzeit für "not working" Meldung in Telegram erst wenn mehrere Poll-Versuche fehl schlugen, Rückkehr zu Normalbetrieb erst nach mehreren erfolgreichen Statusabfragen um "not working" Wellen zu vermeiden. Siehe Vorgänger =) Antrag Benutzer:Dg3hda
/Slang Kommando Zukünftige Ansprache in Slang von Nyu anfordern. "otaku kawaiii desuuuu" oder klingonisch oder hessisch oder oder oder... Antrag Benutzer:Dg3hda
Tastaturfeld für Kommandos Im privaten Chat Auswahl interessanter Kommandos standardmäßig als Optionen (/keyboard-like). 30%
Ban, Silence und Unban Befehl Der Bot soll eine Art Moderatoren Rolle in der
Schaffen-CIX Telegram Gruppe übernehmen		 90%
/status Kommando Änderung: Nicht mehr nur offen/verriegelt, Resultate von /da, Temperaturen 100%
Interface URL-Kommando &last=(number) Anzahl der Einträge aus DB um optional mehr als nur den letzten zu kriegen 100%
/meld Kommando Angeben ob man abends kommt, mit Parameter Uhrzeit. In privatem Chat mit Bot, um Gruppe nicht zu füllen 100%
/wer Kommando Anzeige der bisher gemeldeten (Anzahl/früheste Uhrzeit) sowie der als anwesend gemeldeten 100%
/da Kommando Als "im Space anwesend" melden 100%
/weg Kommando Als "Space verlassen" melden 100%
Mehr Parameter Temperatur für Konferenzraum und Werkstatt, Klingelbetätigung, nichtöffentlicher Spacestatus 100%
Alias/Änderung /status statt /spacestatus 100%
Timestamp Mitanzeigen wenn Temperatur etc. abgefragt werden 100%
Abfrage der Temparatur im Space Temparatur wird zur Verfügung gestellt vom ESP von Hendrik 100%
Private Push Nachrichten für den Spacestatus Damit man via Vibration des Handy's mitbekommt,
wenn der Space offen ist		 100%
Push Nachrichten erweiterung keine benachrichtigung, wenn man im space ist, Benachrichtigung auch beim schließen als option buchbar 100%
/howhotisit Kommando Änderung: Kommando zu lang, als Teil vom Status integrieren 100%
Loading comments...
Abgerufen von „https://wiki.schaffenburg.org/index.php?title=Projekt:Schaffenbot&oldid=4958“