Projekt:Schaffenbot
 Telegram Bot
Status: stable | |
|---|---|
| |
| Beschreibung | Telegram-Bot für Schaffen-CIX Gruppe |
| Ansprechpartner | VinRisen360 |
Telegram Bot Allgemein
Author: Paul Freudenberger (Aktuelle Version des Bots) / Marcel (Version 0.1 des Bots)
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://bot.schaffenburg.org/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.
Es ist auch möglich mehrere Werte zu übergeben. Dafür muss man die Werte einfach mit einem der folgenden Zeichen voneinander trennen:
Semikolon(;), Leerzeichen( ), Plus(+), Pipe(|).
Wenn mehrere Werte für "value" übergeben werden, können auch mehrere Werte für "tag" mitgegeben werden.
Die Zuordnung der "tag"s zu den "value"s erfolgt über die Position in der Mehrfach-Value-Kette
RÜCKGABEWERT BEI ERFOLGREICHEM LOGGEN:
Value successfully logged
Daten auslesen
Über die folgende URL können die Daten wieder ausgelesen werden:
http://bot.schaffenburg.org/getlog.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 (Wird getriggert, wenn jemand auf einen Button drückt, der im Chat Fenster steht (Umfrage))
- /Commands/WeatherCommand.php (Mit diesem Command kann das Wetter abgefragt werden. Benötigt allerdings Anmeldung an openweather API)
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]
Multi-Sprachen Support
Am 28.11.2017 wurde dem Bot Multi-Language Support hinzugefügt.
Dadurch kann der Schaffenbot in mehreren Sprache mit den Leuten kommunizieren.
Diese Features bietet der Multi-Language Support
- Die Sprache wird abhängig vom User gesetzt (Beispiel: Bot spricht Deutsch mit @UserNummer1 und Englisch mit @UserNummer2)
- Gibt es keine Sprachenzuordnung für einen User, spricht der Schaffenbot in der Standardsprache
- Die Standardsprache vom Schaffenbot ist Deutsch
- Nicht nur der Text, der von Commands ausgegeben wird ist an die Sprache angepasst, sondern auch die Schlüsselworte welche Commands triggern ( /weristda und /whoisthere geht)
- Die /hilfe bzw. /help wird abhängig von der gewählten Sprache ausgegeben
- Es gibt ein Wörterbuch pro Sprache, das gepflegt werden muss
Wörterbucher
Die Wörterbücher Englisch und Deutsch waren mit der Einführung des Multi-Language Support bereits verfügbar.
Jeder der mithelfen möchte weitere Sprachen zu implementieren soll ein neues Wörterbuch anlegen.
Das Format des Wörterbuchs muss wie in den vorhandenen Wörterbüchern sein:
Wörterbuch-Format:
[Text-ID][Leerzeichen][Text in der Sprache des Wörterbuchs]
Beispiel für Englisch Wörterbuch: 1 Be right back (in the space) 2 clock 3 Error: The time you have provided is not a valid clock time usw...
Die folgende Tabelle dient der Verwaltung der Wörterbücher:
| Sprache | Datei | Vollständig | Author/Mitwirkende |
|---|---|---|---|
| Englisch | Datei:Telegram-bot-en.zip | Ja | Paul |
| Deutsch | Datei:Telegram-bot-de.zip | Ja | Paul |
| Japanisch | Datei:Telegram-bot-jp.zip | Nein | Andy |
| Saarländisch | Datei:Telegram-bot-sal.zip | Nein | Hendrik |
| Hessisch | Datei:Telegram-bot-he.zip | 45% | Hendrik stev96 |
| Klingonisch | Datei:Telegram-bot-klingonisch.zip | Nein | Freiwillige vor! |
Angefragte Features
| Feature | Notizen | Umgesetzt zu X% |
|---|---|---|
| Einbindung Space-Status-Schalter | Wir haben den Schalter, die Info muss zu Nyu. | Antrag Benutzer:Dg3hda |
| Warnung wenn letzter User /geht aber Space noch offen | Es kam ja schon häufiger vor, dass Nyu den Space um 4 am schließt, von dem her is die "Fehlerquote" der Gehenden wohl hoch :D..evtl paar min Zeit vor Warnung | Antrag Karsten |
| Nachrichten für Aufenthalt hinterlegen | Wär praktisch wenn man für sich selbst und andere Nachrichten hinterlegen könnte, die Nyu bei Einchecken in den Space ausrichtet. Richtung "Kannst du dir das und das bitte mal anschauen", oder "Ich hab dir dein Wasauchimmer ins Fach gelegt", "Ich wollte eigentlich noch das und das machen" | Antrag Karsten |
| MoWaS-Integration | Warnungen aus dem Warnsystem MoWaS übernehmen, Nyu statt NINA! | Antrag Hendi |
| Hilfe-Update | Fertige Features wie Pizzatimer auch in Hilfe übernehmen und freigeben | Antrag Hendi |
| Oliver-Special | Textänderung für ihn: Oliver Kömm hat angegeben später zu kömmen um 20:00 Uhr usw. | Antrag Hendi |
| Geschlossene Gesellschaft | Statusse hinzufügen, um Website "Space open" für geschlossene Gesellschaft zu unterdrücken | Antrag Hendi |
| Sipgate.io | Nyu eine Stimme geben | Antrag Stev96 |
| Anmeldung zum Plenum | Analog zu Funktion für Schaffentag | Antrag Torsten |
| Uff Counter | "Uff" pro Tag zählen und in Milli bzw Mega Uff ausgeben sobald jemand "Uff" schreibt | Antrag byteturtle |
| Verkürzung von Ausgaben | So was wie Putzzeitpunkte muss nicht minutengenau angezeigt werden | Antrag Hendrik |
| Telegramm-Melder | Auslösung einer akustischen Meldung im Space (z.B. Piepser der Konferenzraum-Uhr) mittels Botkommando, unterschiedliche Kommandos für unterschiedliche Signale (Aufmerksamkeit auf Telegram richten, Hinweis auf verschlossene Tür) | Antrag Hendrik |
| Anmeldung und Erinnerung Stammtisch | Analog zu Funktion für Schaffentag | Antrag Karsten |
| Rückkehr der Aliase | Alias "werkommtnoch" ist weggefallen, vielleicht noch andere? Sind wohl noch bei Lucy?:-) Bitte wieder zurückbringen! | Antrag Hendi |
| Anwesenheitskomprimierung | Automatische Meldung des frühesten Öffnungszeitpunkt von "Ichkommheute" im CIX, detailierte Listen nur noch privat oder komprimiert. | Antrag Hendi |
| Strichlistenfernbedienung | Da ja der Bot weiß, wer postet, könnte doch etwa ein /trank cola oder /trank bier direkt über das Strichlisten API abbuchen. | Antrag Jochen |
| Anmeldung für SchaffenTag | Um den SchaffenTag besser Planen zu könne, vor allem das Essen. Wäre es gut eine Funktion zu haben die die Zusagen für den nächsten SchaffenTag zählt und auf Anfrage ausgibt. Um Spam zu vermeiden sollte das vielleicht nur in Privatchat mit Nyu ablaufen. | Antrag Torsten |
| Öffnungsankündigung URL | Angekündigte Öffnung des Space per URL-Abfrage (Daten-Auslese-Feature?) auslesbar machen, z.B. als Countdown. Zeit db-Abhängig. (Ankündigung via getlog abfragen) | Antrag Hendi |
| Abstimmung | Funktion zum Abstimmen im Bot einbauen. Wird wahrscheinlich Voraussetzung für Ban / Mute | Antrag Paul |
| Müllüberwachung Notiz von Paul: (Warte auf Rückmeldung von Karsten/Steven) |
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 |
| Dönermelder | Wir würden bei Nyu gerne melden, wer zum Döner geht und wann (ggf. zu welchem) - Dönerholstatus soll abbonierbar sein. Nyu soll bei Dönerbestellungen dann annehmen und demjenigen mitteilen, der Döner holen geht | Antrag @Kaen_guru |
| 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% |
| CIX-Message API | URL zum Auslösen von Nachrichten vom Bot an die Schaffen-CIX Gruppe | 100% |
| Pizzatimer | Pizzatimer á 15 minuten für Pizza bei 220 Grad Umluft | 100% |
| Spam durch Bot reduzieren | Bestimmte Befehle sollen auf PrivatChatOnly gesetzt werden um den Spam in der Schaffen-CIX Gruppe durch den Bot zu reduzieren | 100% |
| Putzalarm | Einmal die Woche sollte auf das Putzen der Toilette und des Spaces hingewiesen werden. Nyu sollte dabei so lange "Nerven" bis jemand /habewcgeputzt bzw /habegeputzt schreibt. Nyu bedankt sich bei dem Nutzer und zählt wie oft wer Putzt. Dann sollten wir uns überlegen wie wir die Fleißigen belohnen. | 100% |
| Heizungs-Trigger | Es soll immer 30 Minuten bevor jemand in den Space kommt ein Heizungsevent im log getriggert werden, sodass Hendrik's Arduino ihn zum Anschalten der Heizung verwenden kann. Beispiele für Logging-URL: [URL]/soap.php?tag=heater&value=on [URL]/soap.php?tag=heater&value=off |
100% |
| Logging erweitern | Mehrere Values (gleichzeitig) in der Logging-URL übergeben | 100% |
| SQL Maintenance | Maintenance task erstellen, der den logging table verkleinert (Temperatur älter als 1 Tag reicht stündlich) | 100% |
| Interface | URL-Kommando &format=(GP,JSON) (GP=Gnuplotfreundliches Textformat, to be specified) | 100% |
| /sendsticker | Funktion, um den Bot einen Sticker in die Schaffen-CIX Gruppe posten zu lassen | 100% |
| 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 =)) |
100% |
| Nyus-Letter | Nyus-Letter auch in Private chat (changelog), mit Sticker von Nyu drunter für cooleres Aussehen | 100% |
| /Slang Kommando | Zukünftige Ansprache in Slang von Nyu anfordern. "otaku kawaiii desuuuu" oder klingonisch oder hessisch oder oder oder... (Englisch und Deutsch sind verfügbar. Wer weitere Sprachen beitragen kann bitte bei Paul melden) | 100% |
| Alias/Änderung | /heikomaas statt /mute | 100% |
| /brb | Status hinzufügen (Bin gleich wieder da) | 100% |
| 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 | 100% |
| Anwesenheitsticker | Es soll eine Nachricht in der Schaffen-CIX Gruppe getriggert werden, sobald jemand meldet, dass er im Space ist | 100% |
| Survey | Das nutzlose Survey Feature deaktivieren das immer mal wieder jemand ausversehen triggert und dadurch genervt wird. | 100% |
| /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% |