Bots de conversa de Telegram amb Google Apps Script

Paràmetres enviats per Telegram

La informació que Telegram envia, en format JSON, a l'script que les ha de processar sol tenir informació que ens pot ser útil. Agafem, per exemple, un d'aquests paquets de dades, que correspon a l'enviament d'un text (format message).

{"update_id":348606921,"message":{"message_id":65,"from":{"id":^^9499826,"is_bot":false,
"first_name":"Oriol","username":"OriolBoix","language_code":"ca"},"chat":{"id":^^9499826,
"first_name":"Oriol","username":"OriolBoix","type":"private"},"date":1602241026,"text":"proves"}}

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:

{
  "update_id": 348606921,
  "message": {
    "message_id": 65,
    "from": {
      "id": ^^9499826,
      "is_bot": false,
      "first_name": "Oriol",
      "username": "OriolBoix",
      "language_code": "ca"
    },
    "chat": {
      "id": ^^9499826,
      "first_name": "Oriol",
      "username": "OriolBoix",
      "type": "private"
    },
    "date": 1602241026,
    "text": "proves"
  }
}

Els paràmetres que conté són els següents:

★ Si el missatge s'ha enviat des del xat que l'usuari té amb el bot aquests dos valors coincidiran. En cas que el bot formi part d'un grup, els missatges que s'escriguin al grup tindran identificadors diferents per a l'usuari (que serà qui ha enviat la comanda) i la finestra (la del grup) on ho ha fet.

Nota: És convenient tenir anotat el nostre identificador de Telegram, així podem enviar informació al nostre bot de conversa sense necessitat d'escriure una comanda. Això és útil en casos com el d'aquest exemple o quan estem depurant errors. Aquest exemple ens pot ser útil per saber-lo.

Important: Si intentem enviar dades a un usuari de Telegram que no tingui activat el nostre bot (que no hagi enviat la comanda /start) obtindrem un missatge d'error.

Les dades rebudes a Google Apps Script es poden llegir a e.postData.contents. Normalment descodificarem el JSON per obtenir per separat cada una de les dades:

  var dades = JSON.parse(e.postData.contents);  // Tracta les dades rebudes com a JSON i les guarda a dades

Un cop estan les dades tractades, podem obtenir separadament cada una d'elles. Per exemple:

  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

La data que obtenim té un format poc útil. Però podem incorporar-la al format de Google Apps Script per poder treballar amb ella. La funció Date admet com a paràmetre el nombre de mil·lisegons transcorreguts des de l'inici del dia 1-1-1970, per tant podem fer:

  var data = new Date(dades.message.date * 1000);

Dades rebudes en format callback_query

El format callback_query és el que fan servir els teclats en línia quan es prem una tecla. Agafem, per exemple, un d'aquests paquets de dades, que correspon a la pulsació d'una tecla en un teclat en línia.

{"update_id":348607044,"callback_query":{"id":"3045559061608223482","from":{"id":^^9499826,
"is_bot":false,"first_name":"Oriol","username":"OriolBoix","language_code":"ca"},
"message":{"message_id":296,"from":{"id":^^80216110,"is_bot":true,"first_name":"oba_bot_json",
"username":"oba_bot_json_bot"},"chat":{"id":^^9499826,"first_name":"Oriol","username":"OriolBoix",
"type":"private"},"date":602241026,"text":"Tria opcio",
"reply_markup":{"inline_keyboard":[[{"text":"Enc\u00e9n","callback_data":"/on"},
{"text":"Apaga","callback_data":"/off"}],[{"text":"Llegir valor","callback_data":"/llegir"},
{"text":"Llista comandes","callback_data":"/llistat"}]]}},"chat_instance":"3528994572595811640","data":"/on"}}

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:

{
  "update_id": 348607044,
  "callback_query": {
    "id": "3045559061608223482",
    "from": {
      "id": ^^9499826,
      "is_bot": false,
      "first_name": "Oriol",
      "username": "OriolBoix",
      "language_code": "ca"
    },
    "message": {
      "message_id": 296,
      "from": {
        "id": ^^80216110,
        "is_bot": true,
        "first_name": "oba_bot_json",
        "username": "oba_bot_json_bot"
      },
      "chat": {
        "id": ^^9499826,
        "first_name": "Oriol",
        "username": "OriolBoix",
        "type": "private"
      },
      "date": 1602523531,
      "text": "Tria opcio",
      "reply_markup": {
        "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"
            }
          ]
        ]
      }
    },
    "chat_instance": "3528994572595811640",
    "data": "/on"
  }
}

La llista de paràmetres és molt llarga. Els que habitualment necessitarem són els següents:

Dades rebudes en format inline_query

El format inline_query és el que fan servir els inline bots. Agafem, per exemple, un d'aquests paquets de dades.

{"update_id":275635970,"inline_query":{"id":"3045559061682506888","from":{"id":^^9499826,"is_bot":false,
"first_name":"Oriol","username":"OriolBoix","language_code":"ca"},"query":"5.2","offset":""}}

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:

{
  "update_id": 275635970,
  "inline_query": {
    "id": "3045559061682506888",
    "from": {
      "id": ^^9499826,
      "is_bot": false,
      "first_name": "Oriol",
      "username": "OriolBoix",
      "language_code": "ca"
    },
    "query": "5.2",
    "offset": ""
  }
}

Els paràmetres que habitualment necessitarem són els següents:

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