Telegram è un’applicazione di messaggistica istantanea e broadcasting molto popolare.
Una delle caratteristiche avanzate di Telegram sono i bot.
Un bot di Telegram è un piccolo programma progettato per simulare l’interazione e la conversazione umana. I bot interagiscono con gli utenti attraverso comandi e messaggi ai quali i bot risponde inviando all’utente il contenuto tramite chat, gruppo o canale.
La creazione di un bot su Telegram è una operazione semplice. Esiste un bot ufficiale di Telegram progettato allo scopo. Cerchiamo @BotFather sul campo di ricerca e digitiamo il comando /help
BotFather ci risponde elencando una serie di comandi.
Il comando principale è /newbot. Selezioniamolo.
Il bot risponde chiedendo il nome per il nuovo bot; digitiamo un nome (ad esempio “test_bot”).
Il bot ci chiede ora di assegnare una username univoca al nostro bot, ricordandoci di usare il suffisso _bot.
Qualora il nome fosse già in uso, BotFather ce lo segnala e ci chiede di scegliere un’altra username.
Fatto! Il bot è stato creato e ad esso è stata associato un token. Questo ci servirà per interagire con le API di Telegram e implementare la nostra funzionalità.
In questo articolo spiegheremo come implementare un bot per ricercare articoli sul nostro blog, utilizzando Apps Script. Ci appoggeremo su un Foglio di Google dove andremo a registrare l’id e il nome degli utenti che utilizzano il nostro bot.
In particolare implementeremo un bot che interpreta i messaggi ricevuti come chiave di ricerca per i nostri articoli. Inoltre forniremo due comandi /categorie e /tag per farci elencare dal bot l’elenco delle categorie e tag del blog.
Vediamo il codice
var token = "<TELEGRAM_TOKEN>"
var webAppUrl = "<WEBAPP_URL>";
var sheetName = "<SHEET_NAME>"
var telegramUrl = "https://api.telegram.org/bot" + token;
function setWebhook() {
var url = telegramUrl + "/setWebhook?url=" + webAppUrl;
UrlFetchApp.fetch(url);
}
function sendPostMessage(chatId, text) {
var data = {
method: "post",
payload: {
method: "sendMessage",
chat_id: String(chatId),
text: text
}
};
UrlFetchApp.fetch('https://api.telegram.org/bot' + token + '/', data);
}
function doPost(e) {
var contents = JSON.parse(e.postData.contents);
if (contents.message){
var chat_id = contents.message.from.id;
var text = contents.message.text;
var url = null;
var response = null;
var message = null;
if (text == "/start"){
var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName(sheetName);
var first_name = contents.message.chat.first_name;
sheet.appendRow([chat_id, first_name]);
message = "🤓 Benvenuto nel bot di https://www.codexamples.cloud!";
message = message + "\nScrivi il testo da ricercare negli articoli";
message = message + "\nUsa il comando /categorie per ottenere l'elenco delle categorie";
message = message + "\nUsa il comando /tag per ottenere l'elenco dei tag";
sendPostMessage(chat_id, message);
} else if (text == "/categorie"){
url = "<YOUR_BLOG_BASEURL>/wp-json/wp/v2/categories?per_page=100";
response = UrlFetchApp.fetch(url);
var categories = JSON.parse(response);
message = "";
for(var i = 0; i < categories.length; i++){
var category = categories[i].name;
var catLink = categories[i].link;
message = message + category + "\n" + catLink + "\n\n";
}
sendPostMessage(chat_id, message);
} else if (text == "/tag"){
url = "<YOUR_BLOG_BASEURL>/wp-json/wp/v2/tags?per_page=100";
response = UrlFetchApp.fetch(url);
var tags = JSON.parse(response);
message = "";
for(var i = 0; i < tags.length; i++){
var tag = tags[i].name;
var tagLink = tags[i].link;
message = message + tag + "\n" + tagLink + "\n\n";
}
sendPostMessage(chat_id, message);
} else if (text == "/cerca"){
message = "Scrivi il testo da ricercare"
sendPostMessage(chat_id, message);
} else {
url = "<YOUR_BLOG_BASEURL>/wp-json/wp/v2/search?search=" + text
response = UrlFetchApp.fetch(url);
var results = JSON.parse(response);
message = "";
if (results.length > 0){
for(var i = 0; i < results.length; i++){
var title = results[i].title;
var link = results[i].url;
message = message + title + "\n" + link + "\n\n";
}
} else {
message = "🤷♀️ Nessun risultato trovato per la chiave di ricerca '" + text + "'!"
}
sendPostMessage(chat_id, message);
}
}
}
All’inizio del nostro script, impostiamo alcune variabili che richiameremo nel codice:
var token = “<TELEGRAM_TOKEN>”;
var sheetName = “<SHEET_NAME>”;
var webAppUrl = “<WEBAPP_URL>”;
Sostituiamo i segnaposto delimitati da parentesi angolari, con il nostro token, col nome del foglio Google e con il link al quale pubblicheremo il nostro script.
Per ottenere il link è sufficiente, nell’editor di progetto, cliccare sul bottone in alto a destra “Esegui il deployment” > “Nuovo deployment”, selezionare il tipo “Applicazione web”, fornire una descrizione, selezionare il proprio utente nel campo “Esegui come” e autorizzare chiunque all’esecuzione.
Cliccando su “Esegui il deployment”, il nostro script è reso disponibile pubblicamente. Nella finestra di conferma, copiamo la URL presente sotto la voce Applicazione web e sostituiamola al segnaposto <WEBAPP_URL>.
IMPORTANTE
Dopo ogni modifica al codice è necessario procedere ad un nuovo deploy, assegnare la nuova URL alla variabile webAppUrl ed eseguire la funzione setWebhook.
La funzione setWebhook richiama una API di Telegram per impostare la webhook per il nostro bot, ossia la url pubblica che verrà invocata dal bot, ad ogni iterazione con gli utenti.
Per ricevere i messaggi dal bot, dobbiamo implementare la funzione doPost che rimane in ascolto degli richieste.
La richiesta che perviene dal bot è in formato JSON. Parsiamo la richiesta e otteniamo il testo della chat.
A seconda del contenuto del testo, inviamo nella chat un messaggio differente, utilizzando la funzione sendPostMessage che richiama una apposita API di Telegram:
- al comando /start, che viene invocato all’avvio del bot, forniamo all’utente una breve descrizione del bot e segniamo nel nostro Foglio, l’id della chat/utente e il suo nome proprio;
- al comando /categorie, forniamo all’utente l’elenco delle categorie del nostro blog;
- al comando /tag, forniamo all’utente l’elenco dei tag del nostro blog;
- se nessuna delle opzioni precedenti è soddisfatta, il messaggio dell’utente viene considerato come stringa di ricerca e restituiamo l’elenco degli articoli che contengono quella parola chiave
Per effettuare ricerche sul nostro blog, utilizziamo le api che mette a disposizione WordPress
- <YOUR_BLOG_BASEURL>/wp-json/wp/v2/categories?per_page=100
- <YOUR_BLOG_BASEURL>/wp-json/wp/v2/tags?per_page=100
- <YOUR_BLOG_BASEURL>/wp-json/wp/v2/search?search=<STRINGA_DI_RICERCA>
Leggi anche l’articolo su come installare Worpress sul tuo VPS
A questo punto è sufficiente digitare il nome del nostro bot nella casella di ricerca di Telegram e avviarlo (il che equivale a lanciare il comando /start).
Il bot presenta un messaggio dove riepiloga i comandi disponibili.
Clicchiamo sul link “/categorie” o digitiamolo nella chat. Il bot risponde con l’elenco delle categorie disponibili nel blog e per ciascuna di essa riporta il link all’elenco degli articoli del blog afferenti a quella categoria.
Clicchiamo sul link “/tag” o digitiamolo nella chat. Il bot risponde con l’elenco dei tag disponibili nel blog e per ciascuno di essa riporta il link all’elenco degli articoli del blog che contengono quel tag.
Infine, specificando semplicemente una stringa di testo, questa verrà interpretata come chiave di ricerca sul blog e restituirà l’elenco degli articoli che contengono quella stringa.
L’esempio appena descritto gestisce l’iterazione col bot senza memorizzare uno stato. Il bot non tiene cioè conto dello storico delle richieste dell’utente.
Per questo esempio non è necessario memorizzare lo stato della chat, ma in scenari di interazione più complessi, dove ad esempio si chiede all’utente di specificare uno o più parametri in seguito all’attivazione di un comando, è necessario utilizzare approcci diversi, come ad esempio gestire una macchina a stati finiti. Ma di questo parleremo in un prossimo articolo!