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

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

EXTRA

(Zusätzliche Notizen hier)

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%
Alias/Änderung	/heikomaas statt /mute	Antrag Lukas
Alias/Änderung	/status statt /spacestatus	Antrag Oli
Timestamp	Mitanzeigen wenn Temperatur etc. abgefragt werden	100%
Mehr Parameter	Temperatur für Konferenzraum und Werkstatt, Klingelbetätigung, nichtöffentlicher Spacestatus	Antrag Benutzer:Dg3hda
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
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	vorschlag
Ban, Silence und Unban Befehl	Der Bot soll eine Art Moderatoren Rolle in der Schaffen-CIX Telegram Gruppe übernehmen	70%
/Slang Kommando	Zukünftige Ansprache in Slang von Nyu anfordern. "otaku kawaiii desuuuu" oder klingonisch oder hessisch oder oder oder...	Antrag Benutzer:Dg3hda
/meld Kommando	Angeben ob man abends kommt, mit Parameter Uhrzeit. In privatem Chat mit Bot, um Gruppe nicht zu füllen	Antrag Benutzer:Dg3hda
/wer Kommando	Anzeige der bisher gemeldeten (Anzahl/früheste Uhrzeit) sowie der als anwesend gemeldeten	Antrag Benutzer:Dg3hda
/da Kommando	Als "im Space anwesend" melden	Antrag Benutzer:Dg3hda
/weg Kommando	Als "Space verlassen" melden	Antrag Benutzer:Dg3hda
/da Kommando	Als "im Space anwesend" melden	Antrag Benutzer:Dg3hda
/topic Kommando	Aktuellen Topic festlegen	Antrag Benutzer:Dg3hda
/status Kommando	Änderung: Nicht mehr nur offen/verriegelt, Resultate von /da, Temperaturen	Antrag Benutzer:Dg3hda
/howhotisit Kommando	Änderung: Kommando zu lang, als Teil vom Status integrieren	Antrag Benutzer:Dg3hda
Tastaturfeld für Kommandos	Im privaten chat Auswahl interessanter Kommandos standardmäßig als Optionen (/keyboard-like).	Antrag Benutzer:Dg3hda

Loading comments...