A little Telegram’s bots cookbook

INTRODUZIONE

 

Il nostro prossimo evento, “Hello Bot! The Hackathon”, si terrá l’11 e 12 novembre 2017. Come suggerito dal titolo si tratterá di un hackathon, ovvero una competizione fra vari team di sviluppatori, i quali, a colpi di bit, si sfideranno nel costruire il miglior personal assistant virtuale!
Verranno offerti vari modi e strumenti per permettere ai partecipanti di affrontare la sfida nel miglior modo possibile, fra questi la possibilitá di usare le API di Alexa per costruire tramite un Raspberry Pi il proprio Amazon Echo, la possibilitá di creare una app mobile o una web app e infine la possibilitá di sviluppare un bot per Telegram o per Facebook Messenger.
É proprio su quest’ultima possibilitá che ci andremo a concentrare in questa piccola guida. In particolare il nostro focus sará sullo sviluppo di un semplice bot per Telegram, il quale non fará altro che rispondere ai vostri messaggi testuali con un messaggio completamente identico (un cosí detto echobot).

 

 

SVOLGIMENTO

 

Premessa necessaria

Per sviluppare un bot per Telegram si possono usare una moltitudine di linguaggi diversi e altrettante differenti librerie, in questa guida abbiamo deciso di focalizzarci, peró, solo su tre linguaggi di programmazione: Java, Python e Node.js. La nostra scelta è ricaduta su questi linguaggi per alcuni semplici motivi, come il fatto che siano fra i linguaggi piú diffusi e comunemente usati. Useremo diverse librerie open source per sfruttare le Bot API di Telegram, che sono basate su un’interfaccia HTTP creata appositamente per lo sviluppo di bot.
I bot che andremo a creare non saranno particolarmente “intelligenti”: starà a te renderli tali, sfruttando le tua abilità da ninja coder! Sfruttando le API messe a disposizione da Telegram e imparando a conoscere le librerie che ti andremo a presentare potrai donare al tuo bot i superpoteri: fargli utilizzare una tastiera modificata, collegarlo ad un database, usare comandi inline, ecc..

Tutte le librerie utilizzate saranno già disponibili il giorno dell’hackathon sul Raspberry Pi che ti verrà fornito, il quale potrà essere usato come host server per il tuo bot (in alternativa potrai sempre usare il tuo PC per questo scopo); di seguito verranno evidenziate le operazioni da eseguire per installare tali librerie in caso tu voglia hostare il tuo bot sul tuo PC.

 

 

Signor Telegram?

 

Prima di metterti a programmare, qualsiasi linguaggio andrai a scegliere, dovrai comunicare a Telegram la tua volontà di creare un bot. Come? Attraverso un altro bot, of course. BotFather ti aiuterà nella creazione del tuo bot e nella modifica dei settaggi dello stesso, non dovrai far altro che contattarlo (ti basta seguire il link presente in questa guida per aprire una chat, oppure puoi cercare il suo nickname direttamente su Telegram) e usare il comando /newbot, ti verrà richiesto un nome ed un username per il tuo bot, in cambio ti verrà fornito un token.

A cosa ti serve tale token? Lo scoprirai immediatamente, sarà grazie ad esso che riuscirai a metterti in comunicazione con le API di Telegram. Ti viene richiesta una sola accortezza: non condividere questo token con nessuno, altrimenti potrai perdere il controllo del tuo stesso bot.

 

 

Java

 

Procedi al download delle librerie esterne tramite il seguente link (si tratta di un jar contenente tutte le dipendenze necessarie).

Ora si dovranno creare le due classi principali del progetto: quella contenente il main della nostra applicazione e quella che estende la classe TelegramLongPollingBot.

Per quanto riguarda il main avremo:

import org.telegram.telegrambots.ApiContextInitializer;
import org.telegram.telegrambots.TelegramBotsApi;
import org.telegram.telegrambots.exceptions.TelegramApiException;

public class Main {

    public static void main(String[] args) {
	    ApiContextInitializer.init();
	    TelegramBotsApi botsApi = new TelegramBotsApi();

	    try {
	        botsApi.registerBot(new MyBot());
        } catch (TelegramApiException e) {
	        e.printStackTrace();
        }
    }
}

Mentre la seconda classe, che per comoditá abbiamo chiamato MyBot dovrá presentare obbligatoriamente tre metodi, ovvero:

• public void onUpdateReceived(Update update) in cui verranno gestite le risposte fornite dal nostro bot a seconda del messaggio ricevuto
• public String getBotUsername() in cui verrá ritornato lo username del nostro bot
• public String getBotToken() in cui verrá ritornato il token ricevuto da BotFather

 

import org.telegram.telegrambots.api.methods.send.SendMessage;
import org.telegram.telegrambots.api.objects.Update;
import org.telegram.telegrambots.bots.TelegramLongPollingBot;
import org.telegram.telegrambots.exceptions.TelegramApiException;


public class MyBot extends TelegramLongPollingBot{
    public void onUpdateReceived(Update update) {
        if(update.hasMessage()&&update.getMessage().hasText()) {
            Long sender_id=update.getMessage().getChatId();
            String received_text=update.getMessage().getText();
            String text_to_send="";
            SendMessage message=new SendMessage();

            text_to_send = received_text;

            message.setChatId(sender_id);
            message.setText(text_to_send);
            try {
                sendMessage(message);
            } catch (TelegramApiException e) {
                e.printStackTrace();
            }
        }
    }

    public String getBotUsername() {
        return "hellobot_example_bot";
    }

    public String getBotToken() {
        return "IL_TUO_TOKEN";
    }
}

 

Se sei arrivato a questo punto e stai usando un IDE di sviluppo come Eclipse o IntelliJ IDEA, ti basterá importare il file .jar precedentemente scaricato, compilare e lanciare il tuo programma! Il tuo bot sará subito attivo.

Per compilare e lanciare il tuo bot dovrai, da terminale, dapprima posizionarti nella cartella contenente il tuo bot (nel nostro caso si chiamerá “hello_bot”:

cd posizione/della/tua/cartella/hello_bot

Successivamente dovrai compilare e lanciare il bot stesso:

javac -cp posizione/del/tuo/jar/myfile.jar Main.java

java -cp .:posizione/del/tuo/jar/myfile.jar Main

 

 

Python

 

Innanzitutto verifica di aver installato sul tuo sistema Python, in caso contrario scarica l’ultima versione da qui.
Successivamente procedi all’installazione di pip, un tool usato per gestire i pacchetti di Python. Ulteriori informazioni sull’installazione di pip possono essere trovate qui.
A questo punto non ti resta che installare la libreria esterna che verrá utilizzata in questo esempio, ovvero python-telegram-bot. Per installarla non dovrai far altro che usare il comando:
pip install python-telegram-bot –upgrade

Iniziamo creando il file python, che nel nostro esempio sará denominato hello_bot.py. All’interno del main della nostra applicazione dovremo istanziare due particolari classi definite nella libreria esterna che abbiamo deciso di adoperare: la classe Updater e la classe Dispatcher. La prima si occuperá di ricevere gli aggiornamenti del nostro bot (ovvero tutti gli input inseriti dall’utente), mentre la seconda verrá usata per associare ad ogni comando o testo inserito dall’utente un particolare metodo di risposta. Nel nostro caso sará presente un solo metodo di questo tipo, che non fará altro che rispondere all’utente con il testo inviato da quest’ultimo.
Il codice del nostro esempio avrá un aspetto di questo tipo:

from telegram.ext import Updater, CommandHandler, MessageHandler, Filters

def echo(bot, update):
   """Metodo usato per rispondere ad un messagio con un testo identico a quello ricevuto"""
   update.message.reply_text(update.message.text)

def main():
   """Main del nostro programma"""
   updater = Updater("IL_TUO_TOKEN") # Creazione dell'updater, usato per ricevere aggiornamenti sugli input dell'utente 
   dp = updater.dispatcher # Creazione del dispatcher, a cui verranno assegnati i metodi di risposta


   dp.add_handler(MessageHandler(Filters.text, echo)) # Qualsiasi messaggio ricevuto verrá gestito attraverso il metodo echo

   updater.start_polling() # Inzio del polling

   updater.idle() # Il bot viene arrestato quando Ctrl-C è stato premuto o il bot riceve un SIGINT, SIGTERM o SIGABRT. 


if __name__ == '__main__':
   main()

Per lanciare il tuo bot non dovrai far altro che eseguire da terminale:
    python hello_bot.py

 

Node.js

Prima di tutto procedi all’installazione di node.js, per far ciò ti basterà scaricare l’ultima versione da qui.
Successivamente dovrai installare il package necessario alla realizzazione del tuo bot, semplicemente eseguendo dal tuo terminale il comando:
npm install –save node-telegram-bot-api

Per prima cosa dovrai creare la cartella dove andrai a posizionare il tuo bot, in questo esempio tale cartella sarà denominata “hello_bot”. Posizionati in tale cartella con:

cd posizione/della/tua/cartella/hello_bot

Lancia il comando:

npm init

il quale procederà alla creazione del package.json contenente le informazioni sulla tua applicazione. Questo comando ti chiederà di inserire una serie di informazioni (nome dell’applicazione, versione iniziale, nome del file principale, ecc..), potrai semplicemente ignorarle premendo INVIO e infine confermando la creazione del file json digitando yes.

A questo punto sei pronto a creare il tuo file index.js (a meno che tu non abbia specificato un differente nome per il file principale durante il comando npm init), il quale conterrà il codice del tuo bot:

var TelegramBot = require ('node-telegram-bot-api'); // Crea un oggetto che carica le api di telegram
var token = 'IL_TUO_TOKEN'; // Memorizza all'interno di una variabile il token ricevuto da BotFather
var bot = new TelegramBot (token, {polling:true}); // Istanzia l'oggetto TelegramBot al quale gli si passa il token e lo si mette in attesa di ricevere nuovi messaggi (polling)
// Qui stabiliamo il comportamento del nostro bot
    
bot.onText (/(.+)/, function (msg, match) {  // Il bot, ricevuto un testo       
var fromID = msg.from.id; // Preleva l'ID del mittente
var resp = match[1]; // Preleva il testo ricevuto 
bot.sendMessage(fromID, resp); // Restituisce al mittente, tramite la primitiva sendMessage, lo stesso testo da esso inviato
});

 

Per lanciare il tuo bot non dovrai far altro che salvare questo file e lanciare il comando:

node index.js

 

 

CONCLUSIONE

 

Come visto, sviluppare un bot per Telegram non presenta enormi difficoltá. Ovviamente nei casi mostrati si trattava di bot “semplici”, il cui unico compito era quello di inviare all’utente un testo uguale a quello ricevuto dallo stesso. Esistono miriadi di librerie open source per contattare le API di Telegram, per pressoché qualsiasi linguaggio di programmazione. Qui potete trovare quelle suggerite nelle linee guida dell’azienda stessa.
Non di soli echobot si puó peró vivere, come si puó perció donare intelligenza ai nostri bot? Ci sono decine e decine di modi, come il collegare il bot ad un semplice database o ad una serie di servizi esterni (sviluppati da terze parti o ad hoc per il bot stesso). Un’altra possibilitá é quella di usare librerie conversazionali, basate su meccanismi di machine learning, in modo tale da “allenare” il nostro bot a rispondere a quasi tutti i possibili input ricevuti. Esempi di librerie di questo tipo vengono forniti nei riferimenti alla fine di questa guida.
Per concludere, sviluppare un bot non é un’impresa impossibile, tutt’altro. Il giorno dell’hackathon, inoltre, ci saranno diversi mentor presenti e pronti ad aiutarti in caso dovessi avere problemi. Arrivato a questo punto, sei pronto ad accettare la sfida?

 

 

RIFERIMENTI

 

• Bots: An introduction for developers
• Telegram Bot Java Library
• Python-Telegram-Bot
• Node.js Telegram Bot API

 

 

 

A cura di:

Carmine D’Amico

Matteo D’Ospina

Flavia Muggianu

Francesco Vergona