Projekt:Schaffenbot

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%
Datenschutz	Da jeder der Telegram hat auch den Schaffenburg_bot anschreiben kann sollten bestimmte Commands auf die Mitglieder der Schaffen-CIX Gruppe beschränkt werden	Antrag Robert Strehl
/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...