Envíar mensajes a Telegram mediante API Rest con Flow Engine
Con el lanzamiento de la versión 7.0.0-Zelda de Onesait Platform, hemos incluido una serie de guías y tutoriales de uso de la Plataforma.
Esta guía va a mostrar los pasos necesarios para poder crear un servicio REST desde el cual se puedan mandar mensajes de texto, los cuales llegará a grupos de Telegram mediante el uso de un bot de Telegram.
Para ello, se hará uso del paquete «node-red-contrib-telegrambot» para conectarse con Telegram de forma rápida y sencilla.
Para realizar este tutorial es necesario contar con una cuenta personal de Telegram.
Pasos
Acceder a Flow Engine
El primer paso consistirá en acceder al módulo de Flow Engine, el cual se encuentra en el menú de Procesamiento > Flujo Engine.
Se mostrará entonces el listado de instancias de Flow Engine disponibles. Si no hay ninguna para el usuario con el que se accede, se podrá crear una nueva pulsando en el botón de «+» situado en la parte superior derecha de la pantalla:
Como con otros recursos de Onesait Platform, un usuario con un rol que no sea de tipo «administrador» sólo podrá tener una única instancia de Flow Engine.
Aparecerá el asistente de creación de Flow Engine, en donde se tendrá que indicar tanto el identificador único como los límites de los estados de los shockets.
Para este tutorial sólo habrá que indicar el nombre de la instancia.
Una vez creada, la pantalla regresará al listado de instancias de Flow Engine. Ésta habrá que iniciarla pulsando en el botón de «▶» situado en las propiedades de la instancia.
Tras unos segundos, la instancia se iniciará. Para acceder a ella, se tendrá que pulsar en el botón de «👁»:
Configurar el espacio e instalar los paquetes necesarios
Una vez dentro de la instancia de Flow Engine, se recomienda crear una nueva pestaña de trabajo. Para ello, se pulsará en el botón de «+» situado en la parte superior derecha.
Esto generará una nueva pestaña. Haciendo doble clic sobre el nombre de esta se accederá a sus propiedades, donde se podrá cambiar el nombre. En este caso, se ha decidido renombrar la pestaña a «Telegram API»:
Cambiado el nombre, lo siguiente que se tendrá que hacer instalar la dependencia de Telegram para Node-RED. Para ello, se navegará al menú de ≡ > Manage palette.
Se mostrará entonces la ventana con el gestor de nodos y dependencias que se pueden instalar. Se pulsará en la pestaña de «Install» y en el buscador se buscará «telegrambot»:
Una vez localizado, se pulsará en el botón de «Install» para instalar las dependencias. Una vez que termine, se mostrará una ventana con los nodos añadidos.
Crear el API REST para enviar los mensajes
Para este paso se hará uso de los siguientes nodos:
- Input:
- onesaitplatform api rest operation
- onesaitplatform api rest
- Output:
- onesaitplatform api rest operation response
En primer lugar, se buscará y añadirá el nodo de «onesaitplatform api rest», el cual se puede buscar en el listado de nodos situado en la parte izquierda de pantalla:
Ya en el lienzo, haciendo doble clic sobre el nodo se accederá a sus propiedades, en donde se tendrán que rellenar algunos campos.
- Name: el nombre del API; en este caso, «APITelegram».
- Description: un pequeño texto descriptivo de la funcionalidad del API.
- Categories: se seleccionará la disponibilidad; en este caso «ALL».
A continuación se añadirá el nodo de «onesaitplatform api rest operation»:
Como en el caso anterior, una vez en el lienzo se clicará dos veces para acceder a sus propiedades, donde se configurará de la siguiente forma:
- Method: el tipo de operación del API. En este caso, se escogerá de tipo «POST».
- URL: se indicará «/sender».
- Description: texto opcional que describa la operación.
- Query params: este campo sirve para realizar consultas y filtros, en caso de necesitarse. En este caso no se pondrá nada.
Abajo del todo aparece una anotación indicando que la URL hace referencia al nombre de la instancia de Flow Engine que se haya indicado. Este valor será diferente para cada usuario la gran mayoría de las veces.
Una vez configurado el nodo, se unirá con el creado previamente.
Cuando se despliegue el flujo, estos dos nodos crearán de manera automática el servicio API REST correspondiente, con la operación POST generada.
Por último, se añadirá el bloque de «onesaitplatform api rest operation response», que servirá para indicar cuál es la respuesta de la llamada (esperando un 200, que indique todo ha ido bien).
Una vez añadido al lienzo, se accederá a sus propiedades de igual modo que en los casos anteriores.
En este caso, sólo será necesario añadir el valor «200» al campo de «Status code», para indicar que la operación ha tenido éxito.
Como buena práctica, al flujo se le añadirá un nodo de captura de errores para que indique cuando algo falla. Para ello, se creará otro nodo de «onesaitplatform api rest operation response», configurándolo con un código de estado 500, y añadiéndole previamente un nodo de «catch», el cual se unirá con el nodo.
Deberá quedar algo tal que así:
El nodo de «catch» se configurará más adelante, conforme se avance en la creación del flujo.
Preparar el mensaje del bot
El siguiente paso será el de añadir un nodo de función.
Este nodo se editará para añadir el siguiente código, cuya finalidad es la de transformar la llamada y pasar las opciones necesarias para el nodo del bot.
La propiedad de chatId hace referencia al identificador del grupo de Telegram; el valor aquí mostrado hace referencia a un ejemplo interno. Esto se discutirá más adelante.
Este nodo se conectará con el nodo de «onesaitplatform api rest operation response», quedando de la siguiente forma:
Configuración del bot de Telegram
A continuación se va a generar un bot en Telegram. Para ello, se hará uso de BotFather. Tras entrar en la URL indicada, se tendrá que pulsar en el botón que pone «Start Bot»:
En caso de que al darle al botón no pase nada, o se produzca algún error, será necesario lanzar BotFather desde la aplicación web de Telegram mediante un usuario personal.
Una vez iniciado el chat con BotFather, se mostrará un listado de acciones disponibles:
Lo primero que habrá que hacer será crear un nuevo bot con el comando /newbot (o pinchar en el enlace del mismo). El BotFather preguntará entonces el nombre que se quiere que tenga el bot:
A continuación se pedirá el nombre de usuario del bot, que tendrá que ser único y terminar en «bot»:
Los nombres de los bots son universales, por lo que tienen que ser únicos. Si ya existe un bot con ese nombre, aunque no lo haya creado el usuario, no se podrá crear.
Si todo ha ido bien, se recibirá un mensaje de respuesta indicando que se ha creado el bot, con la URL de acceso al bot, así como con el token del servicio HTTP API.
Configurar el nodo de Telegram
Volviendo al lienzo de Flow Engine, se buscará y arrastrará el nodo de «sender» dentro del grupo de Telegram.
Tras añadirlo, se tendrá que abrir sus propiedades para seleccionar el bot a utilizar y el nombre del nodo.
Como seguramente no existan bots previos, lo primero que se tendrá que hacer es crear uno nuevo pulsando en el botón de «🖉»:
Se abrirá entonces una ventana en donde se tendrá que configurar el bot que se ha creado en el paso anterior.
Existen diversas opciones a configurar, pero sólo se tendrá que introducir:
- Bot-Name: el nombre de usuario del bot que se ha creado (no cómo se le va a llamar). En el caso del ejemplo, «onesaitplatform002bot».
- Token: el token asociado al bot y que se tiene que guardar siempre a buen recaudo y que no hay que compartir nunca con nadie ni en ninguna parte. Será del estilo de 1234567890:EsTeToKeNeSuNiNvEnTdEcUiDaDo.
Este nodo habrá que conectarlo con el de la función anterior, quedando tal que así:
Crear un grupo en Telegram y añadir al bot
Desde Telegram, se creará un nuevo grupo de usuarios. Para ello, se pulsará en el botón de «🖉» de la parte inferior, y de las distintas opciones se seleccionará la de «New Group».
A continuación se mostrará un listado con todos los contactos disponibles, para añadirlos al grupo. Sin embargo, en vez de eso se usará el buscador para encontrar al bot, el cual aparecerá con su nombre único:
Por último, se pedirá caracterizar el grupo con una imagen de perfil, así como el nombre del mismo.
Una vez creado, el grupo aparecerá disponible en el listado de chats del usuario:
Antes de terminar con esta parte, es importante guardar, junto al nombre de usuario del bot y el token, el identificador del grupo creado. Esto se puede extraer de la URL del grupo:
Probar el envío de mensajes
Con el grupo configurado, el siguiente paso será el probar que todo funciona correctamente. Para ello, en primer lugar se desplegará el flujo que se ha creado hasta ahora, para que se genere el API REST y su operación de POST.
Para ello, únicamente habrá que pulsar sobre el botón de «Deploy».
Si todo funciona como corresponde, se mostrará una notificación indicando que el despliegue ha sido correcto, y saldrá un estado en el bot de Telegram indicando que se encuentra conectado.
Seguidamente, se navegará en otra pestaña hasta el menú de Procesamiento > APIs.
Se mostrará el listado de APIs disponibles para el usuario, y se podrá comprobar que el API definido en el Flow Engine se encuentra creada:
En las opciones del API, se seleccionará la de «Swagger»:
Se accederá entonces al listado de operaciones disponibles del API del bot:
Habrá que autorizar previamente el uso de las operaciones añadiendo el token de usuario en la sección de «Authorize».
Para mandar el mensaje, lo primero es conformar el objeto JSON del mensaje a enviar. Se compone de dos propiedades:
- text: con el cuerpo de texto a enviar.
- chatId: el identificador único del grupo, que se obtenía de la URL como se vio previamente.
Así, como texto de ejemplo se podría mandar:
{
"text": "¡Buenos días, estrellas brillantes! La Tierra les da la bienvenida.",
"chatId": -4781592641
}Este objeto se introducirá en el cuerpo de la operación POST:
Pulsando en el botón de «Execute», se lanzará el mensaje y, si todo ha ido correctamente, se recibirá en el grupo de Telegram.
Algo interesante es que, mediante markdown, es posible mandar texto con formato.
Configurar el Catch
El bot ya se encuentra funcionando, pero antes de terminar queda un último paso por completar, y es el de configurar el nodo de Catch que se creó varios pasos antes, y que ahora se está en disposición de configurarlo bien.
Lo que hay que hacer es abrir sus propiedades y seleccionar la opción de «selected nodes» dentro del selector de errores:
Esto habilitará una lista de nodos, en donde se tendrán que escoger los siguientes:
Hecho esto se guardará el nodo. Esto va a servir para que, si se produce algún error tanto en la función que envía el mensaje como en el nodo de envío a Telegram, salte un aviso de error.
Para terminar, de volverá a desplegar el flujo creado y actualizar los últimos cambios, quedando todo de la siguiente forma:
Imagen de cabecera: Telegram
✍🏻 Author(s)
