Criação de Github Actions com a Messages API do Vonage

Para equipes e indivíduos, a comunicação é muito importante para o desenvolvimento de um projeto. Não apenas a comunicação entre os membros, mas também a comunicação direta com o projeto. Verificar manualmente o status do seu aplicativo pode ser cansativo, e é aí que reside a vantagem que a automação por meio de APIs de comunicação pode oferecer. Você pode ser facilmente notificado por mensagem de texto, chamada de voz, redes sociais ou qualquer outro meio (dependendo dos recursos da API) quando ocorrerem eventos em seu aplicativo.

O GitHub Actions é uma excelente integração do GitHub que permite acionar ações com base em eventos específicos que ocorrem. Isso pode ser útil para diversos fins, dependendo da criatividade do desenvolvedor. Um dos casos de uso é o envio de mensagens por meio de APIs de comunicação.

Neste artigo, aprenderemos como combinar o GitHub Actions com a Messages API do Vonage usando o canal do WhatsApp. Enviaremos mensagens para um número do WhatsApp quando ocorrer um evento específico. Você também pode praticar com os outros canais compatíveis da API.

Conhecimentos necessários: Para aproveitar ao máximo este artigo, é necessário ter um bom conhecimento sobre como as aplicações Node.js são criadas e como o GitHub Actions funciona. Aqui está uma artigo introdutório sobre o GitHub Actions que você talvez queira conferir primeiro.

O que são as Github Actions

O GitHub Actions permite que você execute comandos específicos quando ocorre um evento; por exemplo, quando alguém faz uma solicitação de pull, envia alterações para um branch e muitos outros eventos.

O GitHub Actions pode ser utilizado de várias maneiras, entre as quais se destacam:

• execução de testes em pull requests

• implantação automática após a atualização de um branch

• comunicar o status do aplicativo, problemas ou pull requests aos desenvolvedores

• muitos outros

Messages API da Vonage - Canal do WhatsApp

A Messages API permite enviar mensagens para um número do WhatsApp por meio do canal do WhatsApp. Para acessar a API, é necessário criar um Account no painel do desenvolvedor da Vonage. Em seguida, você receberá créditos gratuitos para começar a testar a API. Para usar o canal do WhatsApp, é necessário configurar um ambiente de teste.

Vonage Developer dashboard for setting up a sandbox

Em seguida, adicione o canal do WhatsApp à sandbox. Você receberá um link que o levará ao aplicativo do WhatsApp, com uma mensagem padrão no campo de entrada, pronta para ser enviada à Vonage. A mensagem padrão pode variar. Para este tutorial, a mensagem gerada foi “Participe do yam slice”. Para o aplicativo do WhatsApp na web, veja esta captura de tela:

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

Ao enviar essa mensagem, você receberá uma notificação informando que seu número foi adicionado à lista de permissões do Sandbox. Isso significa que agora você pode enviar mensagens para esse número.

Se você quiser adicionar mais números, basta enviar a mesma mensagem para o mesmo destinatário usando o número do WhatsApp que deseja adicionar.

Nessa mesma página, você encontrará algo parecido com isto:

Example code for using the WhatsApp API

Isso mostra como chamar a API para enviar uma mensagem para um número incluído na lista de permissões. Essa solicitação POST mostra:

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

• O nome de usuário e a senha no -u flag (ocultado intencionalmente na captura de tela). O primeiro conjunto, antes dos dois pontos, é sua chave de API, e o segundo conjunto é a senha gerada pela Vonage.

• Alguns cabeçalhos

• Os dados, que contêm o from (o número do WhatsApp fornecido pela Vonage para o envio de mensagens), to (o destinatário, que é um número incluído na lista de permissões) e message propriedade.

É isso que vamos usar em nossas GitHub Actions para enviar mensagens.

A seguir, vamos configurar um aplicativo de exemplo para ver como o GitHub Actions e a Messages API do Vonage funcionam na prática.

Combinando o GitHub Actions com a API do WhatsApp

Neste exemplo, vamos criar uma biblioteca npm que retorna “I am a library” quando executada. É um aplicativo bem simples, então podemos nos concentrar em como o GitHub Actions funciona com a API do WhatsApp.

Configuração do ambiente

No terminal, acesse o diretório desejado onde você quer que o projeto fique e, em seguida, faça o seguinte:

• mkdir simple-lib: para criar um diretório chamado “simple-lib”

• cd simple-lib: para acessar esse diretório

• npm init -y: configurar package.json

• touch index.js: criar um arquivo index.js onde colocaremos o código de execução da nossa biblioteca

Adicione o código a seguir a index.js:

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

module.exports = returnPhrase;

Digamos que queiramos configurar um conjunto de testes para nossa biblioteca. Execute os seguintes comandos no seu terminal:

Mocha é uma estrutura de testes para aplicativos em JavaScript. Teremos o conjunto de testes em test.js com o seguinte 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");
  });
});

Em package.json, edite a test propriedade com o seguinte valor:

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

Agora, ao executar npm run test no terminal, você verá:

Result of executing test script

Inicialize um repositório Git usando git init, faça o commit das alterações e envie para um novo repositório do GitHub que você criou para este exemplo.

Implementação do sistema de mensagens do WhatsApp

Ao executar o GitHub Actions, você precisa de um executor de ação. O executor de ação fornece a implementação da Messages API que queremos usar. Os executores de ação exigem dois arquivos:

• action.yml que fornece o esquema para o executor, como as entradas a serem recebidas, as variáveis de saída e muito mais.

• O arquivo principal (pode ser dist/index.js) que fornece a implementação propriamente dita referenciada pelo action.yml.

Para este exemplo, crie um action.yml arquivo com a seguinte configuração:

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 criar um whatsapp.js arquivo que será compilado em dist/index.js. Esse arquivo contém o código necessário para enviar mensagens usando o canal do WhatsApp.

Aqui está o conteúdo do whatsapp.js arquivo:

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 é uma biblioteca que contém várias funções para receber entradas, exportar variáveis e realizar muitas outras tarefas nas ações. Isso é importante para receber entradas dos executores de ações no GitHub. É necessário instalá-la; portanto, execute:

Axios é um cliente HTTP baseado em promessas para realizar solicitações de rede. Ele é usado para fazer uma solicitação POST. Também precisa ser instalado; portanto, execute:

process.env permite acessar variáveis de ambiente que conteriam as variáveis expostas pelo GitHub durante a execução do fluxo de trabalho. Por exemplo, o GitHub expõe a GITHUB_REPOSITORY variável, que pode ser acessada com process.env.GITHUB_REPOSITORY. Você pode encontrar mais variáveis de ambiente padrão do GitHub aqui.

Uma message será recebida uma entrada (veremos como configurar isso na seção de configuração do GitHub Actions), que seria a mesma mensagem que enviaremos para o número do WhatsApp. Você pode usar qualquer número da lista de permissões que desejar, mas a Vonage especifica:

"Não use um + nem 00; comece diretamente com o código do país, por exemplo, 447700900000"

Em seguida, a solicitação é enviada e a mensagem do WhatsApp é enviada para o número.

Assim como visto no código de exemplo da Vonage, especificamos o nome de usuário e a senha para a autenticação no servidor. No Axios, isso é feito com o auth objeto que contém o username e password propriedade.

Como visto acima, a mensagem do WhatsApp é enviada no seguinte formato:

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

Precisamos instalar mais um pacote: @vercel/ncc. Esse pacote é usado para agrupar arquivos do Node.js em um único arquivo. Usaríamos isso para agrupar whatsapp.js e todas as dependências utilizadas em um único arquivo.

Adicione o seguinte a package.json:

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

Antes de fazer o push, precisaríamos executar npm run build para que todo o conteúdo do arquivo whatsapp.js seja exportado para dist/index.js.

Configuração do GitHub Actions

Primeiro, crie um workflows diretório no .github diretório na raiz do seu projeto. Esse diretório conterá todos os fluxos de trabalho que queremos para o aplicativo.

Na seção “Fluxos de trabalho”, crie um arquivo chamado “whatsapp-actions.yml”. O GitHub Actions usa o sintaxe YAML para descrever fluxos de trabalho.

Neste exemplo, queremos enviar uma mensagem pelo WhatsApp quando um novo commit for enviado ao repositório e o script de teste falhar. Aqui está o conteúdo do fluxo de trabalho:

# .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 prosseguirmos, vamos entender bem a configuração acima.

name: Whatsapp actions

A name propriedade especifica o nome do fluxo de trabalho. É isso que você vê na aba “Ações” no GitHub.

on: push

A on propriedade especifica o evento que aciona o fluxo de trabalho. No nosso exemplo, o push evento faz exatamente isso. Isso significa que o fluxo de trabalho é executado sempre que alguém envia uma alteração para um ramo no repositório. Aqui estão outros eventos que você pode usar. Você também pode especificar vários eventos.

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

A jobs propriedade especifica os trabalhos que seriam executados para esse fluxo de trabalho. Vou nomear o primeiro trabalho como run-tests. O GitHub mostra todas as tarefas em execução no seu fluxo de trabalho na aba “Ações”, agrupando-as sob os respectivos nomes de tarefa.

A próxima linha (runs-on) especifica o tipo e a versão do sistema operacional que devem ser usados para executar o fluxo de trabalho.

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*"

Na seção de tarefas, há “etapas” a serem seguidas. O steps bloco descreve a execução das tarefas que compõem um trabalho.

Nas duas primeiras etapas, a ação “usa” actions/checkout@v2 e actions/setup-node@v1. actions/checkout@v2 é um executor de ação para fazer o check-out de um repositório. Isso é necessário para dar ao seu ambiente de trabalho acesso ao código contido no repositório. actions/setup-node@v1 é um executor de ação para baixar o Node. Isso dá acesso a npm que precisaremos na terceira e na quarta etapa.

Um modelo para a criação de ações do GitHub pode ser encontrado no repositório de fluxos de trabalho iniciais. Como pode ser visto ali, uses: actions/checkout@v2 e actions/setup-node@v1 também são usados na seção de etapas. Essas são duas etapas essenciais, pois permitem executar o código que você tem em seu repositório usando npm.

Ao executar npm i instala todas as dependências em package.json e npm test executa o test script.

A próxima etapa do fluxo de trabalho é um grupo de etapas chamado “Mensagem do WhatsApp”. Essas linhas acionam a mensagem do WhatsApp usando a configuração da ação que temos em action.yml. A etapa possui uma condição na linha seguinte (if: ${{ failure() }}), que indica que os testes restantes só serão executados caso as etapas anteriores do trabalho falhem. Você pode conferir mais verificações de status de tarefa.

Na etapa “Mensagem do WhatsApp”, a ação “utiliza” dillionmegida/github-actions@master (que é o branch master do mesmo repositório) como executor de ações para a implementação do código da Messages API. O GitHub, neste momento, procuraria action.yml no diretório raiz deste repositório, que já configuramos.

A ação envia uma entrada para o executor de ações (whatsapp.js) usando a with propriedade. A entrada vem com uma chave message e um valor *TEST FAILED*. Os asteriscos são adicionados para que o WhatsApp possa colocar esse texto em negrito.

Testando o GitHub Actions

Agora que já temos tudo configurado, podemos acionar o fluxo de trabalho fazendo um push para um repositório. Antes disso, precisamos garantir que o teste falhe, para que a implementação da mensagem do WhatsApp seja executada.

Editar test.js para o seguinte:

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

Podemos empacotar nosso aplicativo (usando npm run build), fazer o commit das alterações e enviar para o repositório.

Ao clicar no botão “Enviar”, o fluxo de trabalho é acionado e recebemos uma mensagem de erro, conforme mostrado abaixo:

Error from running the workflow

Após o erro, receberemos uma mensagem no WhatsApp com o seguinte conteúdo:

Screenshot of WhatsApp message sent to a whitelisted number

Conclusão

Há muitas coisas que você pode fazer com o GitHub Actions e ainda mais com as APIs de comunicação da Vonage. Você também pode enviar mensagens pelo Viber e pelo Facebook Messenger.

Neste artigo, aprendemos o que são as GitHub Actions, alguns recursos que as tornam poderosas e como integrar a Messages API do Vonage para enviar mensagens pelo WhatsApp quando um script de teste falha após o envio de um commit para um repositório.