Fazer chamadas telefônicas a partir do Google Sheets

Ultimamente, tenho esquecido de ligar para meus amigos nos aniversários deles. Não é de propósito, é só que morar do outro lado do mundo dificulta as coisas. Mas, ei, eu trabalho em uma empresa de API de comunicações; posso usar a tecnologia para resolver esse problema!

E, como era de se esperar, encontrei a solução perfeita! Criei uma planilha no Google Sheets com meus queridos contatos, suas datas de aniversário e mensagens sinceras. E agora meus amigos recebem ligações engraçadas de um robô no aniversário. Combinei o Apps Script do Google com o AI Studio da Vonage para enviar automaticamente uma mensagem de aniversário robótica a partir do Google Sheets. E tudo isso com uma interface de baixo código, do tipo arrastar e soltar!

Essa integração é perfeita para quem quer fazer ligações a partir de uma planilha ou de um arquivo CSV, mas não quer desenvolver uma solução totalmente programada.

Neste tutorial, você vai aprender a fazer ligações pelo Google Sheets e nunca mais vai perder outro aniversário!

Pré-requisitos

• Account de desenvolvedor da Vonage

• Número virtual da Vonage: Alugue um número para o seu agente virtual

• Account do Google Sheets: Cadastre-se no Google

Como criar um chatbot de voz para chamadas de saída

Para criar seu agente, siga as instruções contidas na documentação do AI Studio. Existem três opções importantes para o nosso agente; selecione:

• Tipo: Telefonia

• Modelo: Começar do zero

• Evento: Saída

A funcionalidade do seu agente será bem simples: uma única mensagem SMS com votos de feliz aniversário. Você usará um único Nó “Enviar Mensagem” e um Nó “Encerrar Conversa”.

Overview of Bot Architecture

Como criar parâmetros personalizados no AI Studio

Dentro do seu nó “Enviar mensagem”, você precisará de 2 parâmetros. Portanto, abra o painel “Propriedades” no lado esquerdo e selecione “parâmetros”. Em Parâmetros personalizados , crie as seguintes entradas:

• nome - @sys.any 

• mensagem - @sys.any

Salve os parâmetros e abra o seu nó “Speak”. Dentro do nó, adicione a seguinte mensagem. Use seus parâmetros digitando o símbolo $ seguido do nome do parâmetro. Por exemplo, para usar o valor do seu nome, digite $name.

<speak><break time='1s' /> <p> Dear $name</p> <p>Your loving friend YOUR_NAME has the following birthday message for you: $message </p> <p>Have a wondeful birthday!</p></speak>

Você vai perceber que está usando a linguagem de marcação para síntese de fala para poder inserir uma pausa de um segundo e criar parágrafos diferentes, de modo que o agente fale de forma mais natural.

Clique em “Salvar e sair”.

Como conectar seu agente virtual a um número virtual

A etapa final é conectar seu agente a um número virtual. Este guia explica como publicar seu agente.

Como criar um banco de dados no Google Sheets

Abra o Google Sheets e clique em “Planilha em branco”. Dê à sua planilha um título legal, como Mensagens de Aniversário. Além disso, nomeie sua planilha como aniversários.

Simple Birthday Database in Google Sheets

Sua planilha terá 4 cabeçalhos de coluna:

1. nome

2. número_de_telefone

3. aniversário

4. mensagem

Adicione o equivalente aos dados de 10 amigos.

• Para phone_number, insira seu número ou outro número de telefone ao qual você tenha acesso para receber SMS para teste. Os números de telefone devem estar no formato internacional, sem nenhum + ou 00. Por exemplo, um número dos EUA seria 15552345678

  • Certifique-se de que seu coluna phone_number esteja formatada como “Texto simples”, ou você terá problemas com os dados mais tarde.

• Certifique-se de que a data de nascimento esteja formatado como Data . Por exemplo: 26/09/2008.

Select Plain Text

Como converter sua planilha do Google Sheets para JSON

Agora você vai transformar sua planilha do Google em um aplicativo programável! Abra a aba “Extensões” e selecione “Apps Script”. O Apps Script permite que você escreva código em aplicativos do Google Workspace, como o Google Sheets ou o Google Docs, para automatizar e ampliar suas funcionalidades. 

Primeiro, dê ao seu novo projeto um título legal, como Messages API de Aniversário. Apague o código em code.gs e substitua-o pelo seguinte:

function sendBirthdayCall() {
 // Open the spreadsheet by name
 var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheetByName("birthdays");
  // Get today's date
 var today = new Date();
 var todayDay = today.getDate();
 var todayMonth = today.getMonth() + 1;
  // Get all the data from the sheet
 var data = sheet.getDataRange().getValues();
  // Iterate through each row to check for birthdays
 for (var i = 1; i < data.length; i++) {
   var name = data[i][0];
   var phoneNumber = data[i][1];
   var birthday = new Date(data[i][2]);
   var birthdayDay = birthday.getDate();
   var birthdayMonth = birthday.getMonth() + 1;
   var message = data[i][3];
  
   // Check if today is the person's birthday
   if (birthdayDay === todayDay && birthdayMonth === todayMonth) {
     // Prepare the JSON payload
     var payload = {
       "name": name,
       "phone_number": phoneNumber,
       "birthday": birthday.toISOString(),
       "message": message
     };
     const payload_string = JSON.stringify(payload)
 
     // Send POST request to AI Studio
     sendRequest(payload);
   }
 }
}

Este código cria um função sendBirthdayCall que procura em nossa planilha os aniversários da planilha. Em seguida, ele percorre cada linha, verificando se hoje é o aniversário da pessoa ao comparar os valores de dia e mês. Se for o caso, ele cria o objeto de carga útil que contém as informações do aniversariante. Depois, ele passa essas informações para a função sendRequest , que enviará as informações de aniversário para o AI Studio.

Como enviar uma solicitação POST no Apps Script

Agora você vai criar sua função sendRequest para acionar seu Agente Virtual de Saída. Você pode colar o código a seguir abaixo da função seção .

Para que esse código funcione, você precisará atualizar três valores:

1. aiStudioUrl 

• O endpoint depende da região que você selecionou para o seu agente:

Para agentes da UE → https://studio-api-eu.ai.vonage.com/telephony/make-call

Para agentes dos EUA --> https://studio-api-us.ai.vonage.com/telephony/make-call

1. X-Vgai-Key

• Adicione sua chave de API do AI Studio. Você pode encontrar a X-Vgai-Key no canto superior direito da tela do AI Studio. Clique no ícone “usuário” e, em seguida, em “Gerar chave de API”.

1. agent_id

• Adicione o ID do seu agente do Vonage AI Studio. Ele pode ser encontrado nos detalhes do agente.

function sendRequest(payload) {
// Replace with either the US or EU URL
 var url = '';


  // Define headers for the POST request
 var headers = {
   'Content-Type': 'application/json',
   'X-Vgai-Key': '' // Replace with your key
 };
  // Define the body for the POST request
 var body = {
   "to": payload.phone_number,
   "agent_id": "", // Replace with your agent ID
   "session_parameters": [
     {
       "name": "name",
       "value": payload.name
     },
     {
       "name": "message",
       "value": payload.message
     }
   ]
 };
  // Make sure to set proper options for your API request (e.g., headers, authentication)
 var options = {
   'method': 'post',
   'headers': headers,
   'payload': JSON.stringify(body)
 };


  // Send the POST request
 var response = UrlFetchApp.fetch(url, options);


 // Add a two-second delay before sending the next request
 Utilities.sleep(2000);
  // Log the response (you can do more error handling here)
 Logger.log(response.getContentText());
}

Então, o que esse código faz? Ele cria uma solicitação POST, preparando a URL, os cabeçalhos e o corpo da solicitação. Nos cabeçalhos, o X-Vgai-Key garante que esse agente pertença a você. No corpo da solicitação, você informa a AI Studio qual agente acionar e para quem enviar as mensagens. E você passa os valores para nome e mensagem no AI Studio, que você preparou anteriormente. Tudo isso é agrupado em opções e, usando UrlFetchApp você faz a solicitação. 

Recentemente, o AI Studio adicionou limites de frequência aos pedidos. Para se adaptar a isso, foi adicionado um atraso de 2 segundos entre os pedidos usando Utilities.sleep(2000);

E pronto! Agora você pode testar se o seu código funciona clicando em Executar.

Para o teste, certifique-se de que pelo menos três dos contatos tenham aniversário no dia de hoje e um número de telefone ao qual você tenha acesso.

Que legal isso! 

Como criar uma tarefa Cron no Apps Script

O aplicativo deve ser executado diariamente para verificar se alguém está fazendo aniversário. Você pode fazer isso com bastante facilidade no Apps Script da seguinte maneira:

1. No painel à esquerda, selecione “Gatilhos”.

2. Clique em “Adicionar gatilho”.

3. Escolha as seguintes configurações:

   1. Escolha qual função executar: sendBirthdayCall

   2. Escolha qual implantação deve ser executada: HEAD

   3. Selecione a fonte do evento: Orientado por tempo

   4. Selecione o tipo de acionador baseado no tempo: Temporizador diurno

   5. Selecione o horário do dia: decida quando você quer que suas mensagens sejam enviadas

4. Clique em “Salvar”

Conclusão

Agora que você aprendeu a ligar para números de telefone a partir do Google Sheets, o que vem a seguir?

Talvez você possa enviar um e-mail de aniversário com AI Studio Nó de E-mail. Talvez seus amigos tenham “telefobia”, então você poderia criar um agente de SMS como alternativa. Ou você poderia usar a integração de IA generativa para enviar aos seus amigos uma foto divertida de aniversário.

Seja qual for a sua decisão, queremos saber! Entre em contato conosco na nossa Slack da Comunidade de Desenvolvedores ou no X, antes conhecido como Twitter.

Recursos adicionais

• Google Sheets com SMS

• Crie um aplicativo de despedida usando o Vonage AI Studio e o Notion como banco de dados

• Aproveitando o Low Code: AI Studio com o Airtable