Bouw je eigen Telegram-chatbot
Er is een hele hype rond chatbots, die op steeds meer plaatsen opduiken. In dit artikel laten we zien wat je er zelf mee kunt. We bouwen onze eigen Telegram-chatbot en vertellen wat je daar allemaal mee kunt doen.
Er zijn diverse websites met tools om een bot te bouwen. Leerzamer is het om er zelf eentje te maken. Om inspiratie op te doen kun je kijken op storebot.me van Telegram of het bredere botlist.co. Ook Microsoft zet vol in op bots, de website bots.framework.com geeft een goede indruk. In deze masterclass gebruiken we een bot als ‘communicatiekanaal’.
Vanaf een server kunnen we hier bijvoorbeeld teksten en foto’s naar versturen. De meldingen lees je via de Telegram-app, waar en wanneer je maar wilt. We laten ook zien hoe je die bot gebruikt voor het afvangen van meldingen van de home automation software Domoticz. Hierna maken we de chatbot zodat deze op commando’s kan reageren.
BotFather
Telegram maakt het bouwen en gebruiken van een bot relatief eenvoudig. Er is prima documentatie, een relatief eenvoudige api en de BotFather waarmee je in een paar stappen zelf een chatbot maakt. Alle berichten die de chatbot verstuurt en ontvangt lopen via Telegram. Daarom heb je een (gratis) Telegram-account nodig. Je kunt je eenvoudig registreren via web.telegram.org door het opgeven van je mobiele telefoonnummer. Je ontvangt dan een sms-bericht en kunt via de instructies op het scherm het account maken.
Heb je al een Telegram-account, dan kun je dat gebruiken voor de stappen in deze masterclass via het bovengenoemde webadres. Je kunt ook een van de vele Telegram-apps gebruiken. Telegram heeft een eigen bot genaamd BotFather die je gebruikt voor het registreren van je nieuwe chatbot. Een conversatie met BotFather kun je starten via telegram.me/botfather.
Een bot bij Telegram kan behalve berichten ook specifieke commando’s ontvangen die met een slash (/) beginnen. Het maken van een bot gaat ook met commando’s. Stuur
/newbot naar de BotFather om een bot te maken. Kies een naam gevolgd door een (unieke) gebruikersnaam. Wij kiezen PCM_DemoBot. Kies voor je eigen bot een andere gebruikersnaam. Je ontvangt hierna meteen een bevestiging met een token die je nodig hebt bij het gebruik van de api. De eenvoudigste manier om de api te gebruiken is via een browser. Blader naar de url https://api.telegram.org/bot<jouw-bot-token>/getme waarbij je op de plaats van
<jouw-bot-token></jouw-bot-token>je token invult. De letters bot voor de token zijn belangrijk, maar worden vaak vergeten. De token dient voor het vinden van je bot én voor autorisatie dus houd de token geheim. De respons is nu bijvoorbeeld
{"ok":true,"result":{"id":309266712,"first_name":"PCM Demo Bot","username":"PCM_DemoBot"}}Door in de aanroep de opdracht getme te vervangen door getUpdates krijg je (in het json-formaat) een respons met alle berichten die naar de bot zijn verstuurd. Omdat het een nieuwe bot is zie je nu nog geen berichten. Daarom gaan we eerst een conversatie opzetten met de bot.
Chatten
Om een conversatie met je bot te starten blader je naar https://telegram.me/<gebruikersnaam> of zoek je naar @<gebruikersnaam> in een van de Telegram-apps. Klik daarna op Begin. Stuur een willekeurige tekst naar je bot (bijvoorbeeld Hallo). Als je nu de url https://api.telegram.org/bot<jouw-bot-token>/getUpdates opent zie je wél berichten.
Om de respons beter leesbaar te maken selecteer je alle tekst in de browser met Control+A. Kopieer de tekst met Control+C en plak het in een venster van de online tool JSONLint (http://jsonlint.com). Druk dan op Validate JSON. We zijn op dit moment alleen geïnteresseerd in de id die onder chat wordt genoemd in de sectie result. Dat is de chat-id. In ons voorbeeld is dat 58332350. Je kunt nu een antwoord via de api versturen met die chat-id. Om een antwoord te sturen open je de url https://api.telegram.org/bot<jouw-bot-token>/sendMessage?chat_id=<chat-id>&text=<jouw-tekst> in de browser waarbij je <chat-id> vervangt door de correcte chat-id en <jouw-tekst> door de gewenste tekst. In de Telegram-app zie je vervolgens deze reactie van de bot in de chat. We zullen nu andere manieren verkennen om tekst en afbeeldingen via de bot te versturen.
©PXimport
Curl
Het openen van een url in de browser kun je zien als een http-get actie. Voor het versturen van bestanden, zoals een afbeelding, is een http-post actie nodig. Een handige en veelgebruikte tool voor http-get en http-post via de opdrachtprompt is curl. Zeker in Linux-omgevingen is dit meestal standaard geïnstalleerd en anders kun je de tool onder Debian/Ubuntu gemakkelijk met
apt-get install curl installeren. Om een tekst naar de chat te sturen met een http-get gebruik je onderstaande commando waarbij je uiteraard weer de correcte chat-id en gewenste tekst invoert.
curl -i -X GET "https://api.telegram.org/bot<jouw-bot-token>/sendMessage?chat_id=<chat-id>&text=<jouw-tekst></jouw-tekst></chat-id></jouw-bot-token>Wil je een foto versturen dan kun je een http-post doen inclusief afbeelding met onderstaande commando, waarbij je achter @ het volledige pad naar de foto opgeeft.
curl -s -X POST "https://api.telegram.org/bot<jouw-bot-token>/sendPhoto" -F chat_id=<chat-id> -F photo="@/pad/naar/foto"</chat-id></jouw-bot-token>Meldigen van Domoticz
In een paar stappen kun je de bekende home-automation-software Domoticz zo instellen dat het notificaties naar de bot stuurt. Open de gebruikersinterface van Domoticz in de browser en ga naar Setup / Settings. Op het tabblad Notifications vink je Enabled aan bij Custom HTTP/Action. Vul bij #TO de chat-id in. In het veld URL/Action voer je het volgende in: https://api.telegram.org/bot<jouw-bot-token>/sendMessage?chat_id=#TO&text=#MESSAGE. Vervang <jouw-bot-token> door je token. Bij een notificatie komt de melding in #MESSAGE en wordt #TO vervangen door de ingevulde chat-id. Met wat knutselen is Domoticz zelfs volledig via een bot te besturen.
Onze chat kan handig als ‘berichtenstroom’ voor een server dienen, bijvoorbeeld om meldingen van Domoticz te ontvangen. Dat is een stuk praktischer dan e-mail. Ten eerste kun je overal de meldingen lezen omdat de Telegram-app voor zeer veel platforms beschikbaar is. Bovendien heb je veel controle over de meldingen. Zo kun je bijvoorbeeld opmaak toepassen in je berichten (markdown of html) en naast foto’s ook mp3-bestanden, documenten en video’s versturen.
De limiet is ruimhartig (50 MB per bestand). Verder kun je desgewenst updates voor berichten plaatsen of, op het moment dat je een bericht verstuurt, met een parameter aangeven dat het ‘in stilte’ moet worden verzonden: een iPhone zal dan geen notificatie geven, een Android doet dat stilletjes. Je kunt de bot in de Telegram-app ook altijd even op stil zetten als je tijdelijk geen notificaties wilt ontvangen. In de prima documentatie van Telegram-api lees je meer over deze en talloze andere opties.
©PXimport
Interactieve chatbot
In deze stap maken we onze chatbot interactief. Daarvoor gebruiken we de programmeertaal Python. Er zitten aardig wat haken en ogen aan als je het helemaal zelf wilt schrijven. Voor een http-get en het decoderen van json-data zijn natuurlijk bibliotheken maar je moet ook bijvoorbeeld rekening houden met berichten die je al hebt afgehandeld. Ook moet de bot efficiënt werken door bijvoorbeeld de verbinding met Telegram langer open te houden tussen updates. Dat is beter dan het steeds opnieuw opzetten van een verbinding.
Denk verder ook aan het juist aanroepen van speciale karakters zoals een + of & in je tekst, anders geven ze problemen bij het versturen van de http-get. Ook hiervoor is overigens een bibliotheek. Een ‘echte’ bot heeft ook baat bij een geheugen: met een database (bijvoorbeeld SQLite) kun je informatie voor specifieke gebruikers onthouden. Veel sneller en handiger is het om pyTelegramBotAPI te gebruiken. Met deze bibliotheek kun je zonder in het diepe te springen alle mogelijkheden van de api gebruiken.
Python instellen
Je hebt voordat we beginnen natuurlijk Python nodig, dat in veel Linux-omgevingen standaard is geïnstalleerd en anders gemakkelijk is toe te voegen. De Telegram-bibliotheek werkt zowel met Python 2.x als 3.x. Bij de op Debian gebaseerde besturingssystemen, zoals Debian, Ubuntu of Raspbian op de Raspberry Pi, installeer je Python 3.x en de packagemanager pip met
sudo apt-get install python3 python3-pipMet de packagemanager kun je gemakkelijk bibliotheken toevoegen. Met
pip3 install pyTelegramBotAPIinstalleer je de bibliotheek voor Telegram. Maak nu met
touch bot.py py een nieuw Python-bestand en open dit met je favoriete teksteditor of gebruik nano vanaf de opdrachtprompt met
nano bot.pyZet hier onderstaande code in. Vul bij jouw-bot-token weer de eerder gemaakte token in. Bewaar de tekst met Control+O en verlaat nano met Control+X,
import telebot
bot = telebot.TeleBot("<jouw-bot-token>")
# Opdracht 'start' afhandelen
@bot.message_handler(commands=['start'])
def send_welcome(message):
bot.reply_to(message, u"We gaan van start...")
# Opdracht 'help' afhandelen
@bot.message_handler(commands=['help'])
def send_welcome(message):
bot.reply_to(message, u"Ik help je graag!")
bot.polling()
</jouw-bot-token>De bot starten
Start het programma vanaf de opdrachtprompt met
python3 bot.pyVanaf nu is je bot actief totdat je het programma beëindigt met Control+C. In Telegram kun je de opdrachten /start en /help geven en de bijbehorende reactie lezen. Je ziet dat met weinig code je bot operationeel is, al zijn er geavanceerdere toepassingen te bedenken. Belangrijk is
import telebot waarmee de bibliotheek wordt geladen. We definiëren daarna de bot met
bot = telebot.TeleBot("<jouw-bot-token>")</jouw-bot-token>Met een
message_handlerstel je filters in waar een bericht aan moet voldoen. De eerste reageert op het commando start (/start). Voldoet het bericht daaraan dan zal de bijbehorende functie genaamd
send_welcome worden uitgevoerd. Die naam mag je zelf kiezen, zolang er maar één parameter is, die met het bericht (message). De tweede message_handler reageert op het commando help met een passende tekst. De volgorde van filters is belangrijk: ze worden getest tot een passende message_handler is gevonden. Aan het einde van het script wordt de bot met bot.polling() daadwerkelijk aan het werk gezet.
Filters
In een message_handler kun je natuurlijk niet alleen op commando’s testen via commands. Je kunt ook met content_types testen op bepaalde content, zoals een foto of document, in plaats van gewoon tekst. Erg praktisch zijn reguliere expressies waarbij je op bepaalde karakters of reeksen kunt testen. De message_handler in het voorbeeld hieronder reageert als een reeks getallen is ingevoerd.
Er mogen geen andere karakters worden ingevoerd. In de reguliere expressie markeren de ^ en $ respectievelijk het begin en einde van de string. De [0-9]* gebruik je voor een reeks getallen. Een reguliere expressie is ook handig voor testen op bepaalde woorden in een tekst.
@bot.message_handler(regexp="^[0-9]*$")
def handle_message(message):
bot.reply_to(message, u"Dat zijn alleen nummers!")Ook erg praktisch is dat je een functie kunt aanroepen. Dat mag ook een anonieme lambdafunctie zijn, zoals in het voorbeeld hieronder. Een lambdafunctie is een feature van Python. Zo’n functie bevat geen return zoals gewoonlijk maar geeft een expressie terug, in dit geval true (altijd waar). Onderstaande message_handler reageert op ieder bericht met de oorspronkelijke tekst die beschikbaar is in message.text. We noemen dit ook wel ‘echoën’.
@bot.message_handler(func=lambda m: True)
def echo_all(message):
bot.reply_to(message, message.text)De documentatie biedt nog geavanceerdere voorbeelden voor het gebruik van de bibliotheek, waaronder keuzemenu’s. Feitelijk kun je haast alle methodes van de Telegram-api in je code gebruiken, maar soms met net iets andere namen. Belangrijk is dat je regelmatig de Python-bibliotheek update met
pip install pytelegrambotapi --upgradeVolgens de makers zijn er regelmatig updates om in lijn te blijven met de api van Telegram. De documentatie van Telegram is natuurlijk ook een belangrijke referentie. Je hebt nu een basis om serieus met bots aan de slag te gaan. Wil je verder de diepte in? Op de GitHub-pagina van de pyTelegramBotAPI vind je verwijzingen naar bots die met deze bibliotheek zijn gemaakt, inclusief broncode.
Tekst: Gertjan Groen
