Els xatbots apareixen a l'aplicació Telegram en forma semblant als xats dels usuaris o grups però permeten l'execució de programes que poden tenir funcions molt diverses. A cada xatbot li assignarem un programa. Quan enviem una comanda al xatbot, aquesta serà executada i tornarà una resposta. Els programes que corresponen als xatbots han de poder ser executats des d'una adreça d'internet, és a dir una URL, com passa, per exemple, amb els Scripts de Google.
La següent imatge resumeix el funcionament dels xatbots de Telegram fent servir Google Apps Script.
Si no som usuaris habituals de Telegram, haurem d'instal·lar l'aplicació i crear-nos el nostre compte d'usuari. Telegram també es pot fer servir des de l'ordinador però serà una rèplica del nostre compte i el primer cop que ho fem servir ens enviarà un codi per fer la sincronització. Per treballar amb els xatbots és pràctic tenir Telegram a l'ordinador per no haver d'estar pendents de dos dispositius.
Per crear un xatbot farem servir un altre xatbot anomenat BotFather. Podem picar al botó de la lupa i posar les primeres lletres del nom. Veurem que és el que ens interessa per la seva icona característica i pel fet que no té un compte d'usuari (començat amb @) associat. Quan obrim BotFather haurem de picar el botó START, situat a la part inferior, per poder començar a treballar amb ell.
Quan piquem el botó START ens informarà de la llista de comandes disponible. Per enviar una comanda
podem picar la barra / del teclat o fer servir el botó
Entrarem la comanda /newbot i picarem la tecla enter. Ens demanarà que entrem el nom que li volem donar al xatbot. Podem posar, per exemple, bot_IoT. Després ens demana que donem un nom d'usuari que, necessàriament, ha d'acabar en "bot". Una bona pràctica és afegir _bot al final del nom del xatbot. En el nostre cas, doncs, posem com a nom d'usuari bot_provaIoT_bot. Un cop definit el xatbot, ens donarà l'adreça i el token que ens permetran accedir al xatbot. L'adreça serà una cosa similar a:
t.me/bot_provaIoT_bot
I el token serà una successió de caràcters com, per exemple, aquesta:
^^34628844:AAFIpk-e7j3UZtYQYQaTduf4mPhnDqIcNXI
Un cop tenim el xatbot definit, passarem a configurar-lo. Amb la comanda /mybots ens sortirà la llista dels nostres xatbots (segurament només un) i picarem sobre el nom d'usuari del xatbot (@bot_provaIoT_bot). S'ens mostraran diverses opcions. En aquest moment ens interessa l'opció Edit Bot. Quan la piquem veurem diverses opcions entre les que ens poden interessar Edit Botpic, que ens permet posar una imatge (mínim 150 ⨯ 150 px) al xatbot, o Edit Commands, que ens servirà per definir una llista de comandes que ens sortiran quan piquem la barra /. Les comandes s'han d'entrar posant el nom de la comanda (sense accents o caràcters especials), un espai, un guió, un espai i una breu descripció de la comanda. Per saltar de línia i poder escriure la comanda següent picarem la tecla enter al mateix temps que la de majúscules. Aquestes dues configuracions no són obligatòries i les podem fer (o modificar les opcions) quan desitgem. En aquest cas definim tres comandes:
llistat - Llista de les comandes disponibles guardar - Guarda un valor al full de càlcul llegir - Llegeix el darrer valor guardat
Un cop ja tenim el xatbot definit, el podríem cercar (com hem fet per trobar BotFather), iniciar-lo (prement START) i enviar-li comandes, però no farà res perquè no li hem dit què s'ha d'executar quan s'enviï una comanda al xatbot.
Telegram envia i rep la informació en format JSON. Podem veure, des del navegador, la darrera comanda que s'ha enviat al nostre xatbot. Per fer-ho, emprarem la següent URL:
https://api.telegram.org/bot^^34628844:AAFIpk-e7j3UZtYQYQaTduf4mPhnDqIcNXI/getupdates
Si recentment hem enviat la comanda /llistat obtindrem una resposta com aquesta:
{"ok":true,"result":[{"update_id":825667527,"message":{"message_id":5,"from":{"id":^^9199456,"is_bot":false,
"first_name":"Oriol","username":"Oriol_Boix","language_code":"ca"},"chat":{"id":^^9199456,"first_name":"Oriol",
"username":"Oriol_Boix","type":"private"},"date":1601744308,"text":"/llistat","entities":[{"offset":0,"length":8,
"type":"bot_command"}]}}]}
El format JSON escrit així és pesat de llegir però es pot passar per un formatejador que ens el deixi amb una estructura més fàcil d'entendre. Per exemple, fent servir JSON formatter obtindríem:
{
"ok": true,
"result": [
{
"update_id": 825667527,
"message": {
"message_id": 5,
"from": {
"id": ^^9199456,
"is_bot": false,
"first_name": "Oriol",
"username": "Oriol_Boix",
"language_code": "ca"
},
"chat": {
"id": ^^9199456,
"first_name": "Oriol",
"username": "Oriol_Boix",
"type": "private"
},
"date": 1601744308,
"text": "/llistat",
"entities": [
{
"offset": 0,
"length": 8,
"type": "bot_command"
}
]
}
}
]
}
Observem que, entre les dades enviades, hi ha l'identificador d'usuari (id) que ens serà útil properament. En el nostre cas, l'identificador és:
^^9199456
Per fer proves, també podem enviar missatges des del navegador cap al compte de Telegram. Per exemple la següent:
https://api.telegram.org/bot^^34628844:AAFIpk-e7j3UZtYQYQaTduf4mPhnDqIcNXI/sendMessage?chat_id=^^9199456&text=Missatge enviat des del navegador
Teòricament, cal substituir alguns caràcters especials (espai, %, etc.) pels seus codis però, a la pràctica, la majoria de navegadors ja ho canvien automàticament. En el nostre exemple, la comanda que realment s'envia és la següent (%20 és el codi corresponent a l'espai):
https://api.telegram.org/bot^^34628844:AAFIpk-e7j3UZtYQYQaTduf4mPhnDqIcNXI/sendMessage?chat_id=^^9199456&text=Missatge%20enviat%20des%20del%20navegador
El xatbot que hem fet és capaç de rebre comandes però no fa res amb elles perquè Telegram no té cap programa assignat per a aquest xatbot. Ara anem a fer un programa que sigui capaç de rebre les comandes del xatbot i retornar una resposta. Quan entrem una comanda al xatbot, Telegram l'enviarà al programa i retornarà al xatbot el resultat que el programa enviï. Farem servir els scripts de Google (Google Apps Script) per fer el programa del nostre xatbot. Atès que en molts casos acabarem necessitant un full de càlcul, farem l'script des d'un full. SI sabem segur que no ens cal el full de càlcul també podem crear l'script directament des del drive.
Obrim la nostra pàgina de Google Drive i creem un full de càlcul nou. A la primera filera posem els títols de les columnes. A la primera, per exemple, hi podem posar Dades. Serà convenient escriure un valor a la segona filera del full per poder fer proves. Un cop introduït, es veuria d'aquesta manera:
Les pàgines i els serveis de Google canvien d'aspecte amb certa freqüència. Les imatges que trobarem en aquest apartat, per tant, poden no correspondre exactament amb les reals. Aquí l'important són els passos, no l'aspecte.
De moment, el nostre full de càlcul és només accessible per a ús personal. Si hi volem accedir des de fora ho haurem de canviar. Piquem sobre el botó Comparteix.... Se'ns obrirà una finestra en la que picarem el botó Opcions avançades. On s'indica Qui hi té accés hi deu dir Privat i ho hem de canviar per Activat: tothom que tingui l'enllaç i en el desplegable on diu Pot visualitzar haurem de triar Pot editar (en aquest cas ho podríem deixar a Pot visualitzar però llavors no podríem modificar el formulari des d'altres aplicacions). En aquesta finestra hi surt un enllaç que copiarem i ens guardarem en algun lloc, per exemple un document del bloc de notes. L'enllaç obtingut serà similar a aquest:
https://docs.google.com/spreadsheets/d/1TThsoSjkeMSfwEKy4mn_4QEYH96sxv3VURqE3WHCTswDA/edit?usp=sharing
D'aquesta adreça ens interessa el codi de la taula, que és una seqüència llarga de caràcters situada entre barres. Aquí l'hem marcada en verd perquè sigui fàcil d'identificar. Piquem al botó Fet. Ara anem a la pestanya Fitxer i piquem sobre l'opció Publica al web.... Se'ns obrirà una finestra en la que picarem el botó Publica, acceptarem la confirmació i tancarem la finestra.
En el nostre full de càlcul, anirem a la pestanya Extensions i triarem l'opció Apps Script. Se'ns obrirà una finestra similar a la següent:
Hem d'esborrar la funció buida myFunction i deixar l'espai en blanc. Aquest és l'script que farem servir:
// Funció per interaccionar amb el full de càlcul des de Telegram
// Oriol Boix, 2020 Basat en un exemple de Ferran Mas
// Sota llicència Creative Commons BY-NC-ND
// https://creativecommons.org/licenses/by-nc-nd/3.0/deed.es_ES
//
// Les variables següents ens permeten personalitzar l'script al nostre projecte
var token = "1334328844:AAFIpk-e7j3UZtYQYQaTduf4hEhnDqIcNXI"; // API Token de Telegram
var telegramUrl = "https://api.telegram.org/bot" + token; // Url que comunica el nostre xatbot amb Telegram
// Adreça de l'script (ens la donen en el moment de publicar-lo)
var webAppUrl = "https://script.google.com/macros/s/AKfycbzXSTtXkzqyM_sABbEZanVX2EuRAIUB5xct53AXp6-MbLscpLHO/exec";
// Id del full de càlcul (l'obtenim quan el compartim)
var IdFull = "1TThsoSjkeMSfwEKy4mn_4QEYH96sxv3VURqE3WHCTswDA";
// Funció que envia un text a Telegram
function sendText(chatId,text_env){
var cont = {
method: "post",
payload: {
method: "sendMessage",
chat_id: String(chatId),
text: text_env,
parse_mode: "HTML"
}
}
UrlFetchApp.fetch(telegramUrl + '/', cont);
}
// Funció que s'executa quan l'script rep una ordre post
function doPost(e){ // Funciíon que recibe los datos enviados por Telegram que seran por metodo Post
var fet = 0;
var resposta = '';
var dades = JSON.parse(e.postData.contents); // Tracta les dades rebudes com a JSON i les guarda a dades
// Extraiem les dades
var text = dades.message.text; // Recupera el text del missatge
var id = dades.message.chat.id; // Recupera l'identificador de la finestra des de la que s'ha enviat
var id_usuari = dades.message.from.id; // Recupera l'identificador de l'usuari que ha escrit el missatge
var id_missatge = dades.message.message_id; // Recupera l'identificador del missatge
var lang = dades.message.from.language_code ; // Llengua que l'usuari té configurada a Telegram
var nom_usuari = dades.message.from.first_name ; // Recupera el nom de l'usuari que ha enviat el missatge
var posicio = dades.message.location; // Recupera la localizació de l'usuari, si és possible
// La comanda pot tenir paràmetres, separats amb @
// Descomposem el text rebut a partir de les @
var comanda = text.split("@"); // Separa per les @
var cmd = comanda[0]; // Comanda
var par1 = comanda[1]; // Primer paràmetre
// Si esperem més paràmetres podem avegir més línies
var sh = SpreadsheetApp.openById(IdFull); // Obrim el full de càlcul
var sheet = sh.getSheets(); // Agafem els fulls
if (cmd == '/llistat'){
var llista = "/llistat - Llista de les comandes disponibles\n"; // Text que es retornarà a Telegram
llista = llista + "/guardar - Guarda un valor al full de càlcul\n";
llista = llista + "/llegir - Llegeix el darrer valor guardat";
sendText(id,llista);
fet = 1;
}
if (cmd == '/guardar'){
if (par1 == undefined){
resposta = "No s'ha rebut cap dada per guardar\n";
resposta = resposta + "La sintaxi és /guardar@dada\n";
resposta = resposta + "Per exemple: /guardar@22,4";
} else {
var camps = new Array(1); // Valors per guardar a la taula
camps[0] = par1;
sheet[0].appendRow(camps); // Afegeix una fila amb la llista de dades en format matriu al primer full
resposta = 'Valor guardat';
}
sendText(id,resposta);
fet = 1;
}
if (cmd == '/llegir'){
var full = sheet[0].getDataRange().getValues();
var rang = sheet[0].getLastRow(); // Índex de la darrera filera
if (rang > 1){ // Si és 1 només hi ha els títols
var filera = full[rang -1]; // Agafem la darrera filera
resposta = filera[0];
} else {
resposta = "No hi ha cap dada guardada";
}
sendText(id,resposta);
fet = 1;
}
// Si no hem entrat a cap if vol dir que la comanda no s'ha reconegut
if (fet == 0){
resposta = "Comanda incorrecta";
sendText(id,resposta);
}
}
Al començament de l'script hi ha algunes variables que hem de personalitzar amb les dades corresponents. Ara que ja tenim l'script, li hem de dir a Telegram l'adreça per tal que el pugui executar quan s'enviïn comandes al xatbot.
Un cop personalitzat el programa l'hem de guardar, picant el botó que es mostra a continuació.
Picarem el botó Implementar.
En el desplegable triarem Nueva implementación i s'obrirà una finestra similar a la següent:
El primer cop que ho fem, haurem de picar en el botó que es mostra a continuació.
I triar l'opció Aplicación web. La finestra ens preguntarà en nom de qui volem que s'executi l'aplicació (li direm Yo) i qui hi té accés (li direm que qualsevol usuari). Finalment, picarem el botó Implementar.
Se'ns mostrarà una pantalla en la que se'ns indicarà l'adreça URL de l'aplicació, que haurem de copiar.
| URL script | https://script.google.com/macros/s/^^fycbxqrJpVA-KT1sUd8HIta643R3bH4ixpDahttayGSGjkpHUBjPQ/exec |
Un cop estiguem, podem picar el botó Listo.
Atenció: Hem de recordar que cal guardar el programa (botó del disquet) abans d'implementar, si no ho fem ens implementarà la darrera versió guardada que no serà l'actual.
Per indicar a Telegram quina és l'aplicació a executar farem servir aquesta comanda:
https://api.telegram.org/bot^^34628844:AAFIpk-e7j3UZtYQYQaTduf4mPhnDqIcNXI/setWebhook?url=
https://script.google.com/macros/s/AKfycbzXSTtXkzqyM_sABbEZanVX2EuRAIUB5xct53AXp6-MbLscpLHO/exec
Hem partit la instrucció perquè és molt llarga però caldria posar-la al navegador sense salts de línia.
Atenció: Pot passar que quan modifiquem el nostre script la seva adreça URL canviï. Si això passa i no canviem el Webhook seguirem executant la versió anterior. Podem semiautomatitzar aquest canvi amb la següent funció:
var script = "https://script.google.com/macros/s/^^fycbyO825_c_O2Ar4eos7p3NFZ7b1mroghyZg20V40aJHDui4WKfrIrZJHSxrGCdC1auImQg/exec";
var token = "^^34328844:AAFIpk-e7j3UZtYQYQaTduf4hEhnDqIcNXI"; // API Token de Telegram
var telegramUrl = "https://api.telegram.org/bot" + token; // Url que comunica el nostre bot amb Telegram
function assigna(){
var peticio = telegramUrl + "/deleteWebhook";
var response = UrlFetchApp.fetch(peticio); // Carrega la resposta a la petició
var peticio = telegramUrl + "/setWebhook?url=" + script;
var response = UrlFetchApp.fetch(peticio); // Carrega la resposta a la petició
}
Cada cop que actualitzem el programa podem copiar l'enllaç que ens donen, posar-lo a la variable script i executar la funció des de l'editor. Quan tornem a fer servir el bot ja tindrem la versió actualitzada.
Hi ha altres comandes de Telegram accessibles des del navegador. Podem trobar la llista en aquesta pàgina.
Aquesta obra d'Oriol Boix està llicenciada sota una llicència no importada Reconeixement-NoComercial-SenseObraDerivada 3.0.