Criação de um agente de voz resiliente: um guia para sistemas de failover

Se você nasceu depois de 1980, há cerca de 80% de chance de que tenha receio de atender ou fazer ligações telefônicas (de acordo com estudos realizados na Alemanha e nos EUA). Para as empresas, isso significa que, em breve, mais da metade da população consumidora global estará predisposta à “telefonofobia”.

Embora o contato com os clientes por meio de chamadas de voz seja um meio eficiente de comunicação, as empresas fariam bem em adotar formas alternativas para atender às preferências de seus clientes. Uma solução simples seria fazer o acompanhamento por mensagem de texto, WhatsApp ou e-mail. Isso poderia ter diversas aplicações na prática: confirmação de agendamentos, lembretes de pagamento, marketing proativo e muito mais.

O AI Studio da Vonage permite que você crie chatbots de telefonia de saída em uma plataforma intuitiva do tipo “no-code”/“low-code”. A plataforma é fácil de começar a usar e permite que você crie integrações poderosas para elevar a experiência do cliente a um novo patamar. Nesta postagem do blog, você aprenderá a acionar uma chamada de saída a partir do seu agente e, em seguida, enviar uma mensagem de SMS e um e-mail de acompanhamento caso a chamada não seja bem-sucedida.

Pré-requisitos

• Account de desenvolvedor da Vonage

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

• Node.js - baixe e instale o Node

• Account do Postman - Cadastre-se no Postman

• Ngrok Account - Cadastre-se no ngrok

Como criar um chatbot de telefonia de saída

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

• Tipo: Telefonia

• Modelo: Começar do zero

• Evento: Saída

Como a funcionalidade que você deseja criar se baseia na possibilidade de a chamada falhar de alguma forma, você precisará criar apenas o agente mais simples. Adicione um único nó “Falar” ao seu agente e insira uma frase para ele dizer. Em seguida, adicione um nó “Encerrar Chamada” para encerrar o fluxo.

Simple Voice Agent in AI Studio

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

Como acionar um chatbot de telefonia de saída

Agora que você criou seu agente, precisará acionar AI Studio API de Chamadas de Saídado AI Studio. Para isso, você pode usar o Postman. Após fazer login, crie uma nova Coleção. Em seguida, crie uma nova solicitação HTTP do tipo POST.

• Se o seu agente estiver localizado na Europa, a URL deve ser:
  https://studio-api-eu.ai.vonage.com/telephony/make-call

• Se o seu agente estiver localizado nos Estados Unidos, a URL deve ser:
  https://studio-api-us.ai.vonage.com/telephony/make-call

Você pode ver a localização do seu agente na seção “Detalhes do agente”.

Cabeçalhos

Na guia “Headers”, você precisa adicionar o seu AI Studio X-Vgai-Key. Você pode encontrar a X-Vgai-Key no canto superior direito da tela do seu AI Studio. Clique no ícone de “usuário” e, em seguida, em “Gerar chave de API”.

Outbound Agent Triggered From Postman

Corpo

Agora abra a Body aba e selecione o raw option e, no menu suspenso, selecione JSON. Por fim, adicione o seguinte:

{

    "to": “TESTING_NUMBER",
    "agent_id": "YOUR_AGENT_ID",
    "status_url": ""

}

Substitua TESTING_NUMBER pelo seu número de telefone ou qualquer outro número no qual você queira receber a ligação. O número deve estar no formato internacional, sem nenhum + ou 0. Substitua YOUR_AGENT_ID pelo ID do seu agente do Vonage AI Studio. Ele pode ser encontrado nos detalhes do agente. Deixe o status_url em branco por enquanto. Ele será atualizado com a URL do servidor do seu aplicativo.

Outbound Agent Postman Request with Data

Clique em “Salvar” e teste seu agente clicando em “Enviar”. Você deve receber uma ligação do seu agente, muito legal, né?!

Como criar um aplicativo Node para lidar com uma chamada com falha

Agora você vai criar um aplicativo para lidar com essa status_url chamada. Abra seu terminal e crie um novo projeto:

Em seguida, inicialize o projeto como um Node aplicativo e instale o Express pacote:

Por fim, crie um arquivo chamado app.js. É aqui que nosso código ficará.

touch app.js

Adicione o seguinte ao arquivo app.js. Esse código, em grande parte padrão, cria um servidor Express que roda na porta 3000 e processa solicitações POST. Quando uma solicitação POST for recebida, o aplicativo exibirá o conteúdo da solicitação por meio do console.log.

// app.js

const express = require('express');
const bodyParser = require('body-parser');
const app = express();
const port = 3000;

// Use bodyParser middleware to parse JSON requests
app.use(bodyParser.json());

// Handle POST requests to the root endpoint
app.post('/', (req, res) => {
  
  // Display the payload in the console
  console.log('Received POST request. Payload:', req.body);

  // Send a response back to the client
  res.status(200).send('POST request received successfully');
});

// Start the server
app.listen(port, () => {
  console.log(\`Server is running on http://localhost:${port}\`);
});

Agora salve o arquivo app.js e execute o aplicativo:

node app.js

Por fim, você precisará disponibilizar seu aplicativo usando o ngrok. Abra uma nova aba no seu terminal e execute:

ngrok http 3000

No seu terminal, o ngrok criará uma URL de túnel para você. Agora, você precisará copiar e colar essa URL de túnel como valor de status_url no corpo da sua solicitação no Postman.

Outbound Voice Agent with Status URL Webhook

Agora você pode clicar em “Enviar” para testar a chamada. Mas, desta vez, não atenda a chamada. Em seguida, volte para a aba do seu terminal em que o servidor do seu aplicativo está em execução. Você deverá ver o conteúdo da solicitação POST do AI Studio!

Node Server with Status URL Payload

Por que você pode não receber uma solicitação POST

Se você não receber uma resposta e tiver se certificado de que fez tudo corretamente, talvez a culpa não seja sua! O endpoint status_url depende das informações recebidas das operadoras de telefonia. Os dados fornecidos variam de país para país e até mesmo de operadora para operadora. Você pode testar isso tentando números de telefone de diferentes operadoras.

Como criar um chatbot de SMS com failover

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 “Olá, tentamos ligar para você!”

   • 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. A Enviar e-mail nó que você pode configurar para enviar para seu e-mail pessoal com o assunto e a mensagem de sua escolha

Simple SMS Agent in AI Studio

Mas como esse agente será acionado? Você adivinhou! Por meio de uma solicitação POST semelhante à do nosso agente de Voice. Essa solicitação POST virá de dentro do nosso aplicativo Node.js. Para isso, precisaremos do pacote axios. Então, desligue seu servidor e instale o axios:

npm i axios

Então, você precisará fazer algumas atualizações no arquivo app.js. Precisaremos incluir o pacote axios e preparar nossa solicitação de SMS de saída com os cabeçalhos e dados necessários e, em seguida, acionar a solicitação assim que recebermos o status do nosso Agente de Voice. Veja como fica o código final:

// app.js

const express = require('express');
const bodyParser = require('body-parser');
const axios = require('axios');

const url = 'https://studio-api-eu.ai.vonage.com/messaging/conversation';
const data = {
  "to": "DESTINATION_NUMBER",
  "agent_id": "YOUR_AGENT_ID",
  "channel": "sms"
  // optional to pass status_url
  // "status_url": "string"
}

const headers = {
  'Content-Type': 'application/json',
  'X-Vgai-Key': 'YOUR_VGAI_KEY',
};

const app = express();
const port = 3000;

// Use bodyParser middleware to parse JSON requests
app.use(bodyParser.json());

// Handle POST requests to the root endpoint
app.post('/', (req, res) => {
  axios.post(url, data, { headers })
    .then(response => {
    
    })
    .catch(error => {
      console.error('Error:', error);
    });

  // Send a response back to the client
  res.status(200).send('POST request received successfully');
});

app.get('/', (req, res) => {
  // Send a response back to the client
  res.status(200).send('GET request received successfully');
});


// Start the server
app.listen(port, () => {
  console.log(`Server is running on http://localhost:${port}`);
});

E pronto! Execute a solicitação no Postman, ignore a chamada, e você deve receber uma mensagem de texto no seu celular e um e-mail na sua caixa de entrada! Não é demais?

Observe que agent_id aqui deve constar o ID do seu agente de SMS de saída; o segundo agente que você criou.

Conclusão

Neste tutorial, abordamos como criar um chatbot de telefonia de saída usando o AI Studio da Vonage e como acioná-lo por meio de uma solicitação POST. Também exploramos como criar um aplicativo Node para lidar com uma chamada com falha e enviar uma mensagem de acompanhamento por SMS ou e-mail. Seguindo as etapas descritas neste tutorial, você pode criar uma experiência de cliente integrada que se adapta às preferências dos consumidores modernos.

Queremos saber se você está gostando (ou odiando) o AI Studio! Entre em contato comigo no nosso Slack da Comunidade de Desenvolvedores ou no X, antes conhecido como Twitter. Este artigo foi inspirado por uma pergunta no nosso Slack, então, quem sabe? Talvez meu próximo post no blog seja inspirado por você!

Recursos adicionais

• Como alternar entre bot e usuário humano pelo canal de texto no AI Studio

• Aproveitando o Low Code: AI Studio com o Airtable

• Entendendo API e JSON no Vonage AI Studio com exemplos de hambúrgueres