Creación de acciones de Github con la API Messages API de Vonage

Para los equipos y los individuos, la comunicación es muy importante para el crecimiento de un proyecto. No sólo la comunicación entre los miembros, sino también la comunicación directa con el proyecto. Comprobar manualmente el estado de su aplicación puede ser agotador, y esa es la ventaja que puede proporcionar la automatización mediante API de comunicación. Puedes recibir fácilmente notificaciones por texto, llamada de voz, redes sociales o cualquier otro medio (dependiendo de las características de la API) cuando se produzcan eventos en tu aplicación.

GitHub Actions es una hermosa integración en GitHub que te permite desencadenar acciones basadas en eventos específicos que ocurren. Esto puede ser útil para muchos propósitos dependiendo de lo creativo que pueda ser un desarrollador. Uno de los casos de uso es el envío de mensajes a través de las API de comunicación.

En este artículo, aprenderemos a combinar GitHub Actions con Vonage Messages API utilizando el canal de WhatsApp. Enviaremos mensajes a un número de WhatsApp cuando se produzca un evento específico. También puedes practicar con los demás canales compatibles de la API.

Conocimientos necesarios: Para sacar el máximo provecho de este artículo, se requeriría un buen conocimiento de cómo se crean las aplicaciones Node.js y cómo funcionan las Acciones de GitHub. Aquí tienes una Introducción a las Acciones de GitHub que quizás quieras leer primero.

¿Qué son las acciones de Github?

Las acciones de GitHub te permiten ejecutar comandos específicos cuando se produce un evento; por ejemplo, cuando alguien realiza una solicitud de pull, empuja a una rama, y muchos más eventos.

Las Acciones de GitHub pueden utilizarse de varias maneras, algunas de las cuales son:

• ejecución de pruebas en pull requests

• despliegue automático tras actualizar una rama

• comunicar a los desarrolladores el estado de la aplicación, los problemas o los pull requests

• muchos más

Messages API de Vonage - Canal WhatsApp

Messages API te permite enviar mensajes a un número de WhatsApp a través del canal de WhatsApp. Para acceder a la API, debes crear una Account en el panel de Vonage Developer. Después, recibirás créditos gratuitos para comenzar a probar la API. Para usar el canal de WhatsApp, debes configurar un sandbox.

Vonage API Account

To complete this tutorial, you will need a Vonage API account. If you don’t have one already, you can sign up today and start building with free credit. Once you have an account, you can find your API Key and API Secret at the top of the Vonage API Dashboard.

Ready to start building?

Experience seamless connectivity, real-time messaging, and crystal-clear voice and video calls—all at your fingertips.

Vonage Developer dashboard for setting up a sandbox

Luego, agrega el canal de WhatsApp al sandbox. Recibirás un enlace que te llevará a la aplicación WhatsApp, con un mensaje predeterminado en el campo de entrada listo para enviar a Vonage. El mensaje predeterminado varía. Para este tutorial, el mensaje generado fue "Únete a yam slice". Para la aplicación web de WhatsApp, aquí tienes una captura de pantalla:

WhatsApp app after clicking generated link gotten after adding WhatsApp channel to sandbox

Al enviar ese mensaje, recibirás un mensaje notificándote que tu número ha sido incluido en la lista blanca del Sandbox. Esto significa que ya puedes enviar mensajes a ese número.

Si desea añadir más números, sólo tiene que enviar el mismo texto al mismo destinatario utilizando el número de WhatsApp que desee añadir.

En la misma página, encontrará algo parecido a esto:

Example code for using the WhatsApp API

Aquí se muestra cómo llamar a la API para enviar un mensaje a un número de la lista blanca. Esta solicitud POST muestra:

• La URL: https://messages-sandbox.nexmo.com/v0.1/messages

• El nombre de usuario y la contraseña en la -u (ocultos intencionalmente en la captura de pantalla). El primer conjunto antes de los dos puntos es tu clave API y el segundo conjunto es la contraseña generada por Vonage.

• Algunas cabeceras

• Los datos, que contienen el from (el número de WhatsApp que te ha proporcionado Vonage para enviar mensajes), to (el destinatario, que es un número de la lista blanca), y la propiedad message la propiedad.

Esto es lo que usaremos en nuestras Acciones GitHub para enviar mensajes.

A continuación, vamos a configurar una aplicación de ejemplo para ver el uso de GitHub Actions y Vonage Messages API.

Combinar acciones de Github con la API de WhatsApp

Para este ejemplo, vamos a crear una biblioteca npm que devuelve "Soy una biblioteca" cuando se ejecuta. Es una aplicación muy sencilla, así que podemos centrarnos en cómo funcionan las acciones de GitHub con la API de WhatsApp.

Configuración del entorno

Utilizando el terminal, navegue hasta el directorio deseado donde desea que viva el proyecto y haga lo siguiente:

• mkdir simple-libpara crear un directorio llamado "simple-lib"

• cd simple-libpara navegar en ese directorio

• npm init -ypara instalar package.json

• touch index.jspara crear un archivo index.js donde pondríamos el código de ejecución de nuestra librería

Añada el siguiente código a index.js:

function returnPhrase() {
  return "I am a library";
}

module.exports = returnPhrase;

Digamos que queremos configurar un conjunto de pruebas para nuestra biblioteca. Ejecute los siguientes comandos en su terminal:

Mocha es un marco de pruebas para aplicaciones JavaScript. Tendremos el conjunto de pruebas en test.js con el siguiente código:

const assert = require("assert");
const returnPhrase = require(".");

describe("returnPhrase", function () {
  it("should print the right phrase", function () {
    assert.strictEqual(returnPhrase(), "I am a library");
  });
});

En package.jsonedite la propiedad test con el siguiente valor:

"scripts": {
  "test": "mocha"
},

Ahora, cuando ejecutes npm run test en el terminal, obtendrás

Result of executing test script

Inicializa un repositorio Git usando git init, confirma los cambios y envíalos a un nuevo repositorio GitHub que has creado para este ejemplo.

Implementación de la mensajería WhatsApp

Cuando ejecutes GitHub Actions, necesitarás un ejecutor de acciones. El ejecutor de acciones proporciona la implementación de la Messages API que queremos utilizar. Los ejecutores de acciones requieren dos archivos:

• action.yml que proporciona el esquema para el corredor como entradas a recibir, variables de salida, y muchos más.

• El archivo principal (puede ser dist/index.js) que proporciona la implementación real a la que hace referencia el archivo action.yml.

Para este ejemplo, cree un archivo action.yml con la siguiente configuración:

name: 'Vonage WhatsApp Action'
description: 'Action to send WhatsApp messages'
runs:
  using: 'node12'
  main: 'dist/index.js'
inputs:
  message:
    description: The message you want to send to the WhatsApp number
    required: true

Vamos a crear un archivo whatsapp.js que se compilará en dist/index.js. Este archivo contiene el código necesario para enviar mensajes utilizando el canal de WhatsApp.

Este es el contenido del archivo whatsapp.js archivo:

const core = require("@actions/core");
const { default: axios } = require("axios");

const env = process.env;

const messageFromInput = core.getInput("message");

const messageToSend =
  `${messageFromInput}\n\n` +
  `Repository: ${env.GITHUB_REPOSITORY}\n` +
  `Workflow name: ${env.GITHUB_WORKFLOW}\n` +
  `Job name: ${env.GITHUB_JOB}`;

Const VONAGE_NUMBER = “<Number from Vonage>”
const WHATSAPP_NUMBER = "<A recipient>";
const API_KEY = “<API Key from your dashboard>”
const API_SECRET = “<API Secret from your dashboard>”

(async () => {
  try {
    await axios({
      method: "post",
      url: "https://messages-sandbox.nexmo.com/v0.1/messages",
      auth: {
        username: API_KEY,
        password: API_SECRET,
      },
      data: {
        from: {
          type: "whatsapp",
          number: VONAGE_NUMBER,
        },
        to: {
          type: "whatsapp",
          number: WHATSAPP_NUMBER,
        },
        message: {
          content: {
            type: "text",
            text: messageToSend,
          },
        },
      },
    });
  } catch (error) {
    core.setFailed(error.message);
  }
})();

@actions/core es una biblioteca que contiene varias funciones para aceptar entradas, exportar variables y hacer muchas otras cosas a través de las acciones. Su importancia radica en recibir entradas de los ejecutores de acciones en GitHub. Necesita ser instalada, así que ejecútala:

Axios es un cliente HTTP basado en promesas para realizar peticiones de red. Se utiliza para hacer una petición POST. También necesita ser instalado, así que ejecútelo:

process.env da acceso a variables de entorno que contendrían las variables expuestas por GitHub durante la ejecución del flujo de trabajo. Por ejemplo, GitHub expone la variable GITHUB_REPOSITORY a la que se puede acceder con process.env.GITHUB_REPOSITORY. Puedes encontrar más variables de entorno de GitHub por defecto aquí.

A message entrada (veremos cómo configurarlo en la sección de configuración de Acciones de GitHub), que sería el mismo mensaje que enviaremos al número de WhatsApp. Ahí puedes usar el número de la lista blanca que quieras, pero Vonage dice específicamente:

"No utilice + ni 00, empiece por el código del país, por ejemplo, 447700900000"

A continuación, se realiza la solicitud de publicación y se envía el mensaje de WhatsApp al número.

Tal y como se ve en el código de ejemplo de Vonage, especificamos el nombre de usuario y la contraseña para la autenticación del servidor. Para Axios, esto se hace con el objeto auth que contiene los objetos username y password propiedad.

Como se ve arriba, el mensaje de WhatsApp se envía en el formulario:

"**TEST FAILED!!**
Repository: <Repository name>
Workflow name: <Workflow name>
Job name: <Job name>"

También necesitamos instalar un paquete más: @vercel/ncc. Este paquete se utiliza para empaquetar archivos Node.js en un solo archivo. Lo usaremos para empaquetar whatsapp.js y todas las dependencias utilizadas en un solo archivo.

Añada lo siguiente a package.json:

"scripts": {
  "test": "mocha",
  "build": "ncc build whatsapp.js -o dist"
},

Antes de empujar, tendríamos que ejecutar npm run build para que todo en whatsapp.js sea exportado a dist/index.js.

Configuración de las acciones de Github

En primer lugar, cree un directorio workflows en el directorio .github Este directorio contendrá todos los flujos de trabajo que queremos para la aplicación.

En workflows, crea un archivo llamado "whatsapp-actions.yml". Las acciones de GitHub utilizan el formato YAML para describir los flujos de trabajo.

Para este ejemplo, queremos enviar un mensaje de WhatsApp cuando un nuevo commit es empujado al repositorio y el script de prueba falla. Aquí está el contenido del flujo de trabajo:

# .github/workflows/whatsApp-actions.yml
name: Whatsapp actions

on: push

jobs:
  run-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v1
      - run: npm i
      - run: npm test
      - name: WhatsApp Message
        if: ${{ failure() }}
        uses: dillionmegida/github-actions@master
        with:
          message: "*TEST FAILED*"

Antes de seguir adelante, vamos a entender claramente la configuración anterior.

name: Whatsapp actions

La propiedad name especifica el nombre del flujo de trabajo. Esto es lo que se ve en la pestaña de acciones en GitHub.

on: push

La propiedad on especifica el evento que desencadena el flujo de trabajo. En nuestro ejemplo, el evento push lo hace. Esto significa que el flujo de trabajo se ejecuta cada vez que alguien empuja un cambio a una rama en el repositorio. Aquí hay más eventos que puede utilizar. También puede especificar múltiples eventos.

jobs:
  run-tests:
    runs-on: ubuntu-latest

La propiedad jobs especifica los trabajos que se ejecutarán para ese flujo de trabajo. Voy a nombrar el primer trabajo run-tests. GitHub muestra todas las tareas que se ejecutan en tu flujo de trabajo en la pestaña de acciones agrupándolas bajo sus respectivos nombres de trabajo.

La siguiente línea (runs-on) especifica el tipo de sistema operativo y la versión que debe utilizarse para ejecutar el flujo de trabajo.

steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v1
      - run: npm i
      - run: npm test
      - name: WhatsApp Message
        if: ${{ failure() }}
        uses: dillionmegida/github-actions@master
        with:
          message: "*TEST FAILED*"

En la sección de empleos hay "pasos" a seguir. El bloque steps bloque describe la ejecución de las tareas que componen un trabajo.

En los dos primeros pasos, la acción "utiliza" actions/checkout@v2 y actions/setup-node@v1. actions/checkout@v2 es un ejecutor de acción para comprobar un repositorio. Esto es necesario para dar a tu entorno de trabajo acceso al código dentro del repositorio. actions/setup-node@v1 es un ejecutor de acciones para descargar Node. Esto da acceso a npm que necesitaremos en el tercer y cuarto paso.

En el repositorio repositorio de flujos de trabajo iniciales. Como se ve allí uses: actions/checkout@v2 y actions/setup-node@v1 también se utilizan en la sección de pasos. Estos son dos pasos vitales ya que hacen posible ejecutar el código que tienes en tu repositorio usando npm.

Ejecutando npm i instala todas las dependencias en package.json y npm test ejecuta el test script.

El siguiente paso en el flujo de trabajo es un grupo de pasos bajo el nombre "Mensaje de WhatsApp". Estas líneas activan el mensaje de WhatsApp utilizando la configuración de acciones que tenemos en action.yml. El paso tiene una condición en la línea siguiente (if: ${{ failure() }}) que indica que las pruebas restantes sólo se ejecutarán cuando fallen los pasos anteriores del trabajo. Puedes consultar más comprobaciones de estado de trabajos.

En el paso Mensajes de WhatsApp, la acción "usa" dillionmegida/github-actions@master (que es la rama maestra del mismo repositorio) como action runner para la implementación del código de Messages API. GitHub en este punto buscaría action.yml en el directorio raíz de este repositorio, que ya hemos configurado.

La acción envía una entrada al ejecutor de la acción (whatsapp.js) utilizando la propiedad with propiedad La entrada viene con una clave message y un valor *TEST FAILED*. Los asteriscos se añaden para que WhatsApp pueda poner ese texto en negrita.

Probar las acciones de Github

Ahora que tenemos todo configurado, podemos activar el flujo de trabajo enviándolo a un repositorio. Antes de eso, tenemos que asegurarnos de que la prueba falla, para que se ejecute la implementación del mensaje de WhatsApp.

Edite test.js a los siguientes:

assert.strictEqual(returnPhrase(), "I am not a library");

Podemos empaquetar nuestra aplicación (usando npm run build), confirmar los cambios y enviarla al repositorio.

Al empujar, el flujo de trabajo se activa, y obtenemos un error como se ve a continuación:

Error from running the workflow

Tras el error, recibiremos un mensaje de WhatsApp como el siguiente:

Screenshot of WhatsApp message sent to a whitelisted number

Conclusión

Puedes hacer muchas cosas con GitHub Actions y aún más con las API de comunicación de Vonage. También puedes enviar mensajes en Viber y Facebook Messenger.

En este artículo, hemos aprendido qué son las Acciones de GitHub, algunas utilidades que hacen que las Acciones de GitHub sean potentes y cómo integrar la API Messages API de Vonage para enviar mensajes de WhatsApp cuando un script de prueba falla después de enviar un commit a un repositorio.