Crie um lembrete de saldo com a API do Account Vonage e o Google Apps

Como freelancer, ajudei algumas empresas locais na Índia a implementar produtos da Vonage. Recentemente, um dos meus clientes perguntou se seria possível receber um e-mail de lembrete quando o saldo da Vonage ficasse abaixo de um limite especificado, já que não querem prejudicar suas operações por causa de saldo insuficiente. Como quase todos os meus clientes usam o Google Workspace, decidi criar uma integração entre o Vonage e o Google Apps Script para implementar esse fluxo de trabalho.

O Google Apps Script nos permite gerenciar todos os aplicativos do Google por meio de uma única plataforma na nuvem. O melhor de tudo é que a autenticação já está integrada às plataformas, e muitas empresas no mercado utilizam o Google Workspace — anteriormente conhecido como G-Suite.

Nesta postagem do blog, aprenderemos como criar notificações personalizadas quando o saldo da nossa conta Vonage estiver abaixo de um limite especificado. A postagem é voltada para os desenvolvedores da Vonage que desejam gerenciar sua base de clientes de forma eficaz, enviando-lhes lembretes sobre o saldo da conta Vonage.

Pré-requisitos

• Account do Google - Precisaremos de um Account do Google — pessoal ou do Google Workspace.

• Account da API da Vonage - Precisaremos de um Account da API da Vonage. Podemos nos cadastrar hoje mesmo e começar a desenvolver com crédito gratuito. Assim que tivermos um Account, poderemos encontrar nossa chave de API e nosso segredo de API na parte superior do Painel da API da Vonage.

Criar um projeto do Google Apps Script

Vamos começar criando nosso primeiro projeto do Google Apps Script. Precisamos acessar a página inicial do Apps Script e criar um Novo Projeto. Assim que o novo projeto estiver criado, precisamos dar a ele um nome fácil de lembrar. Vamos chamar nosso projeto de Lembrete de Saldo da Vonage.

Verificar saldo

Vamos começar pela parte mais importante e interessante do projeto.

O Google Apps Script é escrito em JavaScript; portanto, mesmo que você tenha apenas conhecimentos básicos de JavaScript, já pode começar a usá-lo.

Vamos criar uma nova função, fetchBalancee vamos tentar nos conectar à API REST da Vonage enviando uma GET solicitação para verificar nosso saldo. Precisamos escrever o seguinte código no Code.gs arquivo:

function fetchBalance() {
  // get these credentials from Vonage's dashboard
  const apiKey = '--------' 
  const apiSecret = '----------------'

  // construct the api endpoint
  const url = `https://rest.nexmo.com/account/get-balance?api_key=${apiKey}&api_secret=${apiSecret}`
  
  // send a get request
  const response = UrlFetchApp.fetch(url, {'method': 'GET'})

  // discard the execution if status code is other than 200
  if (response.getResponseCode() !== 200) return

  // convert the response text into a json object
  const jsonResponse = JSON.parse(response.getContentText())

  // inspect the response
  Logger.log(jsonResponse)
}

Primeiro, o mais importante. Antes de executar o script acima, precisamos obter nossa chave de API da Vonage e Segredo da API da Vonage. Ambas estão disponíveis no Painel da Vonage.

Substitua suas credenciais no script acima e execute a fetchBalance função.

Quando executarmos uma função pela primeira vez, seremos solicitados a autorizar a execução do script.

Receberemos uma lista de todas as permissões necessárias para executar o script.

Assim que autorizarmos nosso projeto do Google Apps Script, a função acima será executada e a resposta da API do Account da Vonage será registrada em nosso console do Logger.

Para obter o saldo a partir da resposta, vamos adicionar as seguintes linhas de código à nossa função:

// parse the response and extract the account balance
const currentBalance = jsonResponse.value

// inspect the balance
Logger.log(currentBalance)

Vamos executar a função novamente. Veremos que, desta vez, não seremos solicitados a conceder permissões e nossa função será executada diretamente.

Muito bem, agora conseguimos verificar o saldo da nossa Account da Vonage.

Especificar limite de saldo

O próximo passo é enviar um alerta (neste caso, um e-mail) caso nosso saldo atual fique abaixo do limite especificado. Para isso, precisamos fazer algumas alterações em nosso código:

function fetchBalance() {
  // get these credentials from Vonage's dashboard
  const apiKey = '--------' 
  const apiSecret = '----------------'

  const balanceLimit = 5 // in euros <- added

  // construct the api endpoint
  const url = `https://rest.nexmo.com/account/get-balance?api_key=${apiKey}&api_secret=${apiSecret}`
  
  // send a get request
  const response = UrlFetchApp.fetch(url, {'method': 'GET'})

  // discard the execution of the response status code is other than 200
  if (response.getResponseCode() !== 200) return

  // convert the json string into a json object
  const jsonResponse = JSON.parse(response.getContentText())

  // parse the response and extract the account balance
  const currentBalance = jsonResponse.value

  if (currentBalance < balanceLimit) { // <- added
    Logger.log('Balance is low') // <- added
  } // <- added
}

Adicionamos uma nova variável, balanceLimit, para especificar o valor abaixo do qual devemos ser alertados por e-mail. Em seguida, no final do script, adicionamos um simples condição “if” para comparar nosso saldo atual e limite de saldo. Vamos executar o script acima e verificar se há algum registro no nosso logger.

Enviar um e-mail

A lógica do nosso aplicativo está completa e a última coisa que precisamos adicionar é o código para enviar um e-mail. É aqui que você vai se apaixonar pelo Google Apps Script. Basta adicionar esta única linha de código e já estaremos prontos para enviar um e-mail. Não precisamos especificar protocolos, portas e outros detalhes de baixo nível com os quais estamos tão acostumados.

Para qualquer e-mail, precisamos de três elementos: destinatário, assunto e corpo do e-mail. Vamos modificar nossa fetchBalance função e adicionar a funcionalidade de e-mail:

function fetchBalance() {
  // get these credentials from Vonage's dashboard
  const apiKey = '--------' 
  const apiSecret = '----------------'

  const balanceLimit = 5 // in euros
  
  const emailSubject = 'Vonage Balance is low' // <- added
  const emailTo = '--------------------' // <- added

  // construct the api endpoint
  const url = `https://rest.nexmo.com/account/get-balance?api_key=${apiKey}&api_secret=${apiSecret}`
  
  // send a get request
  const response = UrlFetchApp.fetch(url, {'method': 'GET'})

  // discard the execution of the response status code is other than 200
  if (response.getResponseCode() !== 200) return

  // convert the json string into a json object
  const jsonResponse = JSON.parse(response.getContentText())

  // parse the response and extract the account balance
  const currentBalance = jsonResponse.value

  // send a reminder email in case the balance is lower than limit
  if (currentBalance < balanceLimit) {
    const emailBody = `Your current Vonage balance: €${currentBalance} as of ${new Date()}. Please recharge soon.` // <- added
    GmailApp.sendEmail(emailTo, emailSubject, emailBody) // <- added
  }
}

Fique à vontade para modificar o emailSubject e emailBody conforme sua preferência.

Seremos solicitados a conceder permissões novamente. Isso ocorre porque adicionamos um trecho de código para enviar um e-mail que requer a autorização do usuário, já que o script enviará o e-mail em nome do usuário. Portanto, precisamos autorizar as novas permissões.

Assim que a execução do script for concluída, precisamos verificar se o e-mail chegou à nossa caixa de entrada.

Observação: o e-mail só será enviado se o saldo da sua conta for inferior ao limite de saldo que você definiu no script.

Verifique o saldo periodicamente

Uma das melhores funcionalidades do Google Apps Script é o seu gatilhos. Os gatilhos, ou tarefas CRON, como às vezes dizemos, permitem que executemos nosso script de forma automatizada, sem qualquer intervenção humana. O Google Apps Script oferece várias maneiras de criar gatilhos, tanto por meio de uma interface de usuário quanto programaticamente.

A frequência do gatilho depende inteiramente do nosso caso de uso. Se nossa API da Vonage for usada com frequência, faz sentido executar o script com mais frequência, por exemplo, a cada hora. Caso contrário, podemos criar um gatilho que execute nossa fetchBalance função uma vez por dia ou uma vez por semana. A decisão é sua!

Vamos criar um gatilho programaticamente. Em Code.gs, precisamos adicionar a seguinte função:

function createTrigger() {
  // create a trigger to run fetchBalance function every hour
  ScriptApp.newTrigger('fetchBalance')
      .timeBased()
      .everyHours(1)
      .create()
}

O script acima faz exatamente o que diz. Ele cria um gatilho que executa nossa fetchBalance função a cada hora. Vamos executar a createTrigger função selecionando-a na barra de ações.

Será exibida novamente uma solicitação de autorização. Os gatilhos exigem que Permitir que este aplicativo seja executado quando você não estiver presente . Vamos autorizar o script e aguardar sua execução.

Assim que a execução for concluída, precisamos verificar se um novo gatilho foi criado ou não.

Na barra lateral, vamos até Gatilhos.

Tudo bem. Podemos ver que um gatilho foi criado. Precisamos esperar um pouco antes que o gatilho seja executado.

Acabamos de criar nosso lembrete personalizado de saldo. É realmente útil para a continuidade do serviço.

E agora?

Existem várias maneiras de criar notificações. Podemos enviar notificações pelo Slack ou até mesmo usar a API da Vonage para enviar mensagens pelo WhatsApp ou SMS aos nossos clientes. Você pode saber mais sobre a API da Vonage em Vonage API Developer.