Acompanhamento por SMS para chamadas efetuadas com o Vonage e o Zapier

SMS Follow Up ExampleEm um artigo anterior, “Fazer chamadas telefônicas a partir do Google Sheets”, mostrei como é fácil fazer chamadas sem precisar de um servidor ou de um aplicativo independente. Bastava ter uma planilha do Google Sheets com os contatos e um agente do AI Studio. Em outro artigo, “Criando um agente de voz resiliente: um guia para sistemas de failover”, mostrei como é possível acionar um SMS de acompanhamento caso sua chamada não seja atendida.

No entanto, eu não imaginava que alguém necessariamente os combinaria! Graças à Alice, do Slack da Comunidade Vonage, vi que estava errado. O problema era que o artigo sobre o Resilient Voice Agent dependia de um servidor Node. Mas e se você quiser criar uma solução totalmente sem código ou com pouco código, como a Alice? Você está com sorte, porque é exatamente isso que faremos neste artigo!

Este tutorial vai mostrar como você pode usar o Zapier para conectar um agente de Voice à um agente de acompanhamento por SMS de saída, sem precisar programar!

Pré-requisitos

• Account da API da Vonage

• 2 números virtuais da Vonage - Alugue 1 número para cada agente virtual

• Account do Google Sheets: Cadastre-se no Google

• Account no Zapier: Cadastre-se no Zapier

Como criar um voicebot de saída

Para criar seu agente, siga as instruções encontradas na documentação do AI Studio. Há três opções importantes a serem selecionadas:

• Tipo: Telefonia

• Modelo: Começar do zero

• Evento: Saída

A funcionalidade do seu agente será bem simples: uma única ligação automatizada com votos de feliz aniversário. Você usará um único Speak Node e um Nó “Encerrar Conversa”.

AI Studio Bot Overview

Como criar parâmetros personalizados no AI Studio

No seu SpeakNode, você precisará de 2 parâmetros. Então, 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

Certifique-se de que os parâmetros foram salvos e abra o seu Speak Node. 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, você deverá digitar $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 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.

Sua planilha terá 4 cabeçalhos de coluna:

1. nome

2. número_de_telefone

3. aniversário

4. mensagem

Adicione dados equivalentes a pelo menos 1 amigo, mas, para entender toda a lógica, adicione cerca de 10.

Google Sheet Sample Data

• 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 posteriormente.

  • 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, ela percorre cada linha, verificando se hoje é o aniversário da pessoa ao comparar os valores de dia e mês. Se for o caso, ela cria o objeto de carga útil que contém as informações do aniversariante. Depois, ela 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 quatro 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

2. 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”.

3. agent_id

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

4. Status_url

• Deixe o status_url em branco por enquanto. Ele será atualizado com a URL do Zapier.

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
"status_url": "", // Replace with webhook URL from Zapier

   "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());
}

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

Para fazer o teste, certifique-se de que pelo menos um dos contatos tenha aniversário no dia de hoje e um número de telefone ao qual você tenha acesso (como o seu número pessoal).

Legal, então já temos um agente automatizado de chamadas de saída! Agora, precisamos criar o agente de SMS de acompanhamento.

Como criar um chatbot de SMS para acompanhamento

Agora você precisará criar um segundo agente. Neste exemplo, usaremos o SMS como método de failover, mas você também pode usar o WhatsApp ou o HTTP da mesma forma. Existem três opções importantes para o nosso agente; selecione:

• Tipo: SMS

• Modelo: Começar do zero

• Evento: Saída

Nosso agente de SMS será bem simples. Adicione 2 nós:

1. A Enviar SMS com o texto “Oi, tentei ligar para te desejar um feliz aniversário. Espero que você tenha um dia fantástico!”

   • O campo “Para” deve ser definido com o parâmetro de sistema $SENDER_PHONE_NUMBER, cujo valor será obtido a partir da solicitação que enviaremos ao Studio na próxima seção.

   • O campo “De” deve ser substituído por $AGENT_PHONE_NUMBER.

2. (Opcional) Um Enviar e-mail que você pode configurar para o seu e-mail pessoal com um assunto e mensagem de sua escolha

Simple SMS Agent in AI Studio

Por fim, publique seu segundo agente da mesma forma que fez anteriormente com seu segundo número da Vonage.

Como usar o Zapier para conectar dois agentes de atendimento ativo

Vamos usar o Zapier para conectar nossos dois agentes em apenas quatro etapas:

1. Receba o webhook “Raw” do AI Studio

2. Limpar os dados JSON recebidos

3. Verifique se o status da chamada foi “atendida”; caso contrário:

4. Envie uma solicitação POST para acionar o acompanhamento por SMS 

Como capturar um webhook “raw” no Zapier

Primeiro, crie um novo Zap em branco. Como aplicativo de acionamento, selecione Webhooks by Zapier. Como evento de acionamento, selecione “Catch Raw Hook”.

Select Catch Raw Hook for your Zap Trigger

Ao clicar em “Continuar”, o Webhook criará uma URL de webhook. Esse endpoint é o “status_url” que deixamos em branco em nossa solicitação do Apps Script. Agora você pode substituir a string vazia pela URL do seu webhook do Zapier.

Zapier Webhook Endpoint used for status_url

Seu script de atualização no Google Sheets deve ficar mais ou menos assim:

Updated Apps Scripts code to include Zapier Webhook URL

Agora você pode clicar em “Executar” no Google Sheets. Mas, desta vez, ignore ou rejeite a solicitação. Isso fará com que o AI Studio envie uma solicitação ao Webhook do Zapier. Em seguida, você pode voltar ao Zapier e testar o gatilho. Você deverá ver um registro retornado. Ao examinar o registro, você verá uma série de dados. Pode parecer complicado, mas não se preocupe; vamos organizar tudo isso a seguir.

Test results for trigger test

Como limpar a carga útil JSON no Zapier

Na última etapa, retornamos dados não formatados da nossa solicitação POST. Você deve ter notado que todas as informações importantes estão dentro do corpo bruto. 

Se você olhar dentro do corpo bruto, você verá um atributo chamado status. Essa informação do AI Studio nos permite saber se a chamada foi ou não atendida. Para obtê-la, vamos adicionar o ação “Code by Zapier” .

Add the Code by Zapier as the second step in your ZapPara o “Evento de ação”, selecione “Executar JavaScript”. Usaremos este bloco de código para limpar os dados brutos e transformá-los em JSON utilizável.

Para os Dados de Entrada, crie uma nova chave chamada Payload. Para o valor, clique no sinal + e selecione Corpo bruto.

Em seguida, no código personalizado, adicione o seguinte:

let Payload = JSON.parse(inputData.Payload.replace(/%g/,""));
output = [{Payload}];

Este código limpa o `inputData` e o converte em um objeto JSON. Dessa forma, podemos usar as chaves e os valores para a lógica nas etapas seguintes.

Transform the Raw Body into a Javascript Object called Payload

Ao testar esse bloco, você verá que agora tem acesso a campos de dados chamados “Payload From” (seu número do Voice Agent), “Payload To” (seu número de telefone de teste) e, o mais importante, “Payload Status”. 

Agora que temos acesso ao valor do “Payload Status”, vamos criar uma condição.

Como criar condições com a ação “Filtro” do Zapier

Adicione mais uma etapa ao seu Zap e insira o Ação “Filtrar pelo Zapier” . Crie a seguinte condição: “Só continuar se:  O status da carga útil não corresponder exatamente a respondido

Create the condition to filter Payload Status

O Zap continuará em todos os casos, a menos que o status da carga seja “respondido”. Portanto, agora podemos adicionar nossa ação final: conectar-se ao nosso agente de SMS de acompanhamento!

Como criar uma solicitação POST com o Zapier

Em nosso gatilho, usamos o Zapier para monitorar as solicitações POST do AI Studio. Mas agora, vamos usar o Zapier para enviar uma solicitação POST para AI Studio e acionar nossa mensagem de acompanhamento por SMS. 

Mais uma vez, selecione Webhooks do Zapier para o evento App. Desta vez, para o evento Ação, escolha POST.

Select POST webhook action

Clique em “Continuar” para configurar a solicitação POST. Aqui, você deve preencher seis campos: a URL e o tipo de carga útil, três campos na seção “Dados” e um campo na seção “Cabeçalhos”.

URL

Quanto à URL, você deve verificar se o seu agente está nos EUA ou na UE. Adicione a URL correspondente:

• https://studio-api-eu.ai.vonage.com/messaging/conversation para a UE

• https://studio-api-us.ai.vonage.com/messaging/conversation para os EUA

Tipo de carga útil

Altere o tipo de carga útil para json.

Dados

Adicione os três campos a seguir com os valores correspondentes:

1. Legenda: para
   Valor: Carga útil para

2. Chave: agent_id
   Valor: o ID do seu agente de SMS de saída; o segundo agente que você criou

3. Legenda: canal
   Valor: SMS

Cabeçalhos

Adicione o seguinte campo e valor:

1. Chave: X-Vgai-Key
   Valor: sua chave de API do AI Studio

POST request properly formatted

Você pode então testar essa etapa e receber a mensagem SMS no seu celular. Se tudo funcionou, publique seu Zap, e pronto!

Conclusão

E é isso aí — uma solução de chamadas e SMS de saída totalmente sem código/com pouco código! Você conseguiu fazer funcionar? Teve alguma dificuldade? Você tem outras plataformas de baixo código preferidas além do Zapier e do Google Sheets? Adoraria saber sua opinião! Como disse antes, a inspiração para este tutorial foi uma pergunta da comunidade em nosso Slack da Comunidade. Junte-se a mim no canal #AI Studio e me conte o que achou deste tutorial. Você também pode seguir o o VonageDev no X para ficar por dentro das últimas notícias para desenvolvedores da Vonage.

Recursos adicionais

• Como enviar lembretes por SMS do Google Agenda com o Zapier

• Integre a conversão de texto em fala personalizada com o Vonage AI Studio e o Deepgram

• Bot para agendamento de videoconferências com tecnologia da IA e da Video API da Vonage