Bots de conversa de Telegram amb Google Apps Script

Enviar botons a Telegram

Podem fer que Telegram ens mostri un conjunt de botons. Quan l'usuari premi un dels botons, s'enviarà al bot de conversa la comanda que correspon al botó. La següent funció permet enviar un text o un teclat. Si no es posa el tercer paràmetre s'enviarà un text.

function sendText(chatId,text_env,keyBoard){  // Funció que envia un text o un teclat a Telegram 
  keyBoard = keyBoard || 0;
  if(keyBoard.inline_keyboard || keyBoard.keyboard){
    var data = {
      method: "post",
      payload: {
        method: "sendMessage",
        chat_id: String(chatId),
        text: text_env,
        parse_mode: "HTML",
        reply_markup: JSON.stringify(keyBoard)
      }
    }
  } else {
    var data = {
      method: "post",
      payload: {
        method: "sendMessage",
        chat_id: String(chatId),
        text: text_env,
        parse_mode: "HTML"
      }
    }
  }
  UrlFetchApp.fetch( telegramUrl + '/', data);
}

Telegram té dos tipus de teclats. Els teclats clàssics es mostren a la part de baix de la finestra mentre que els teclats en línia es mostren dins de la conversa. Els teclats en línia permeten fer que cada tecla tingui un text diferent de la comanda que envia, o sigui que permeten posar un text més descriptiu. Els botons dels teclats en línia poden tenir també una adreça URL, de manera que quan es pica el botó s'obre la pàgina corresponent sense passar per l'script. Podem combiar en el mateix teclat en línia botons de diferents tipus.

Aquesta funció també serveix per enviar un text. El següent exemple mostra com enviar un text al compte de Telegram que correspon a l'identificador indicat:

  var resposta = "Prova d'enviar un text";
  sendText(id_usuari,resposta);

Si ho desitgem, podem aplicar alguns formats al text.

Teclat clàssic

El següent exemple mostra com enviar un teclat al compte de Telegram que correspon a l'identificador indicat:

  // El teclat s'envia en forma de matriu
  // Els claudàtors marquen una filera de tecles
  var botons = new Array(["/on","/off"],["/llegir","/llistat"]); 
  var tecles = { keyboard: botons, resize_keyboard: true, one_time_keyboard : true };  // Configura el teclat 
  var titol = "Tria opció";
  sendText(id_usuari,titol,tecles);  // Envia el teclat 

L'identificador de l'usuari es pot obtenir de les dades JSON enviades.

Teclat en línia

La sintaxi per enviar un teclat en línia la podem veure en el següent exemple:

  // El teclat s'envia en forma de matriu
  // Els claudàtors marquen una filera de tecles
  // L'etiqueta text correspon al que es mostra a la tecla
  // L'etiqueta callback_data correspon a la comanda que s'envia
  var tecles = {"inline_keyboard":[
    [{"text":"Encén","callback_data":"/on"},{"text":"Apaga","callback_data":"/off"}],
    [{"text":"Llegir valor","callback_data":"/llegir"},{"text":"Llista comandes","callback_data":"/llistat"}]
  ]};
  var titol = "Tria opció";
  sendText(id_usuari,titol,tecles);  // Envia el teclat

Per posar adreces URL als botons podem fer-ho com en el següent exemple:

  var tecles = {"inline_keyboard":[
    [{"text":"Google","url":"https://www.google.com/"},{"text":"Bing","url":"https://www.bing.com/"}],
  ]};
  var titol = "Tria opció";
  sendText(id_usuari,titol,tecles);  // Envia el teclat

En aquest exemple podem veure com creem un teclat així.

En els exemples que hem vist fins ara escrivíem directament l'estructura del teclat. A vegades, però, ens pot fer falta generar el teclat sobre la marxa sense saber, en principi, quantes tecles tindrà. Anem a veure com ho faríem amb un teclat d'una sola tecla per filera:

  var llista = new Array();  // La llista contindrà totes les tecles
  var text_tecla = "";
  var cmd_tecla = "";
  var tecla;  // Objecte corresponent a una tecla
  while(condicio){
    text_tecla = "text que va a la tecla";
    cmd_tecla = "comanda que correspon a la tecla";
    tecla = {"text":text_tecla,"callback_data":cmd_tecla};
    var filera = new Array(1);  // Contindrà una filera d'un sol botó
    filera[0] = tecla;  // Posem el botó a la filera
    llista.push(filera);  // Afegim la filera a la llista
  }
  var tecles = {"inline_keyboard":llista};  // Creem el teclat
  var titol = "Títol del teclat";
  sendText(id,titol,tecles);  

Si volem que un teclat generat així tingui diverses tecles per filera la cosa es complica una mica. En aquest exemple podem veure com creem un teclat així.

Cal tenir en compte que la resposta d'un teclat en línia no s'envia en el format JSON de tipus message sinó en el format tipus callback_query. Quan fem servir aquest tipus de teclat hem de mirar quines dades ha rebut la funció doPost i tractar-les convenientment. El següent tros de programa mostra com fer-ho.

function doPost(e){ 
  var data = JSON.parse(e.postData.contents);
  if (data.callback_query){  // Si és la resposta a un teclat
    var tecla = data.callback_query.data;  // Resposta del teclat
    var id_callback = data.callback_query.from.id;  // Identificador de la finestra on s'ha escrit el missatge
    ...
  }
  if (data.message){  // Si és una comanda normal
    var text = data.message.text;  // El text enviat
    var id = data.message.chat.id;  // Identificador de la finestra on s'ha escrit el missatge 
    ...
  }
}

En aquest exemple podem veure l'ús dels teclats en línia.

Aquesta obra d'Oriol Boix està llicenciada sota una llicència no importada Reconeixement-NoComercial-SenseObraDerivada 3.0.