Criando um honeypot para chamadas automáticas com o Vonage AI Studio – Parte 1

Vonage AI Studio é um criador de assistentes virtuais com baixo ou nenhum código que permite que desenvolvedores e não desenvolvedores projetem, criem e implantem agentes virtuais que operam com compreensão de linguagem natural. Ele utiliza sua conta da API da Vonage para criar interações com os clientes por meio dos canais de voz, SMS, HTTP e WhatsApp.

Passei cerca de 15 minutos criando uma armadilha para golpistas. É que recebo muitas ligações fraudulentas porque gosto de zoar com eles. Recentemente, porém, muitas ligações são apenas robôs pedindo para eu apertar o “2” e desligando imediatamente (tenho certeza de que os golpistas estão fazendo isso só para me zoar). Tive uma ideia: como posso combater esse incômodo? Abri o Vonage AI Studio e comecei a trabalhar. Os requisitos do aplicativo são simples:

• Se receber uma ligação de um número que esteja nos meus contatos, deixe a ligação passar.

• Se o número não estiver nos meus contatos, a pessoa que está ligando deve digitar um número antes de encaminhar a chamada para mim.

• Por fim, desligue a chamada se o número apresentar alto índice de suspeita de fraude (usando o Vonage Fraud Defender).

Pré-requisitos

Antes de começar, certifique-se de ter o seguinte:

• Node.js instalado. O Node.js é um ambiente de execução de JavaScript de código aberto e multiplataforma.

• ngrok - É necessária uma conta gratuita. Essa ferramenta permite que os desenvolvedores exponham um servidor de desenvolvimento local à Internet.

Configurando o Node.js para Webhooks de entrada

Vamos integrar o Fraud Defender no próximo post. Por enquanto, vamos abordar os dois primeiros requisitos. Precisamos de uma maneira de verificar se o número está em nossos contatos. Para isso, vamos criar um pequeno servidor Express que possa ser usado para confirmar se o número é conhecido. Comece abrindo um prompt de comando/terminal, criando um diretório de trabalho e inicializando um projeto Node.js.

Vamos dar andamento às solicitações com Express. Instale com

Crie um arquivo index.js, instancie o Express e configure o servidor para escutar na porta 3000. Você deve manter a mesma porta, pois configurou o ngrok para expor o localhost:3000.

import Express from 'express';
import path from 'path';

const app = new Express();
const port = process.env.PORT || 3000;

const catchAsync = (fn) => (req, res, next) => {
  fn(req, res, next).catch(next);
};

app.use(Express.json());

Para esta demonstração, vamos simplesmente inserir manualmente alguns contatos, desta forma:

const contactNumbers = [
    {phone: '19999999991', record: false},
    {phone: '19999999992', record: false},
];

Agora, adicione o endpoint para comparar o número com a lista de contatos:

app.post('/contact', catchAsync(async (req, res) => {
  const { caller } = req.body;
  const contact = contactNumbers.find({phone} => caller);

  if (contact) {
    res.status(200).json(contact);
    return

  }

  res.status(404).json({record: true});
}));

E conclua o restante da configuração do Express:

/**
 * Setup a 404 handler
 */
app.all('*', (req, res) => {
  res.status(404).json({
    status: 404,
    title: 'Not Found',
  });
});

/**
 * Setup an error handler
 */
app.use((err, req, res, next) => {
  res.status(500).json({
    status: 500,
    title: 'Internal Server Error',
    detail: err.message,
  });
});

/**
 * Start Express
 */
app.listen(port, () => {
  log(`app listening on port ${port}`);
});

Executar o aplicativo

Digite o seguinte no prompt do comando/terminal para executar o aplicativo:

node index.js

É apenas um aplicativo Express básico com nosso endpoint para verificar nossa lista de contatos. Você deve ter notado que retornamos “record” na resposta, o que será usado para que o agente comece a gravar a chamada.

Executar o ngrok

O ngrok é um aplicativo multiplataforma que permite aos desenvolvedores expor um servidor de desenvolvimento local à Internet com o mínimo de esforço. Vamos usá-lo para expor nosso serviço à Internet. Depois de configurar o ngrok e fazer login (novamente, a conta gratuita é suficiente), execute o seguinte comando:

ngrok http 3000

Depois que o ngrok for executado, ele fornecerá um URL de redirecionamento que usaremos como base para nossos Webhooks mais adiante neste artigo. O meu é semelhante ao seguinte:

ngrok running successfully in the command line

Configuração do agente

Primeiro, vamos configurar o aplicativo. Você pode acessar o painel de IA pela barra de navegação à esquerda no Painel.

Dashboard left hand navigation.

Uma vez dentro, vamos criar um novo agente. Os agentes são o principal motor do AI Studio.

Create agent from the Dashboard

Selecione o tipo “Telefonia” para habilitar o evento de chamada telefônica.

Agent creation: Agent type

Dê um nome ao agente, escolha a Voice de TTS que preferir e selecione um fuso horário.

Agent creation: Details form

Vamos criar nosso Honeypot do zero, então certifique-se de selecionar esse modelo.

Agent creation: Template screen

Em seguida, escolha o evento que irá acionar nosso agente. Para o nosso Honeypot, vamos selecionar “chamada recebida”.

Agent creation: Event screen

Agora, o agente contém um nó inicial. Os nós são ações que o agente seguirá, e que precisarão de parâmetros para seguir caminhos diferentes. Os parâmetros são variáveis armazenadas junto ao agente. Cada agente possui alguns parâmetros definidos pelo sistema, associados à sessão de chamada, e precisamos adicionar dois parâmetros personalizados: “START_RECORDING” e “PRESS_42”.

Agent builder: parameters

Nós de agente

Antes de definirmos o caminho que o agente seguirá, vamos adicionar todos os nós de que vamos precisar

Nó de Webhook

Vamos fazer com que nosso agente chame nosso aplicativo Express. Precisamos adicionar um novo nó Webhook (localizado em “Integrações”) e configurá-lo para enviar uma solicitação POST para o endereço do aplicativo Express. A configuração desse nó precisará enviar uma solicitação POST para o nosso aplicativo Express. Selecione a aba “body” e preencha o seguinte:

{
  "caller": "$CALLER_PHONE_NUMBER"
}

Webhook node: step one

$CALLER_PHONE_NUMBER é uma variável do sistema que o agente preencherá antes de enviar a solicitação. Podemos mapear os dados da resposta para nossos parâmetros. Usando o JSONPath, preencha “$.record” e mapeie-o para “$USER.START_RECORDING” desta forma. Adicione mais um código de resposta para 404, nomeie-o como “Verificar chamador”, salve e saia.

Webhook node: step two

Nó de coleta de entrada

Adicione um novo nó “Collect Input”. Vamos salvar a resposta em “USER.PRESS_42”. Peça ao usuário que digite 42 usando a aba “text-to-speech”.

Collect input node step one

Altere a entrada de resposta para DTMF e defina “Máx. de dígitos” como 2. Nomeie este nó como “Desafiar o chamador”.

Collect input node step two

Nós de condição

Os nós de condição permitem que o agente siga caminhos diferentes com base nos parâmetros definidos. Os nós de condição verificam se um parâmetro atende a uma condição. É possível definir várias verificações para cada nó, mas são necessárias duas para o nosso Honeypot:

O primeiro é usado para verificar se o chamador digitou 42. Adicione um nó “Condições” e edite-o. Em seguida, clique em “criar condição” na caixa de diálogo de edição. Defina o parâmetro como nosso PRESS_42, a operação como “é igual a” e o valor deve ser 42. Nomeie a condição como “O chamador digitou 42” e nomeie o nó como “Verificar DTMF”.

Condition node: Check 42

Lembra-se do parâmetro “record” de antes? Se quisermos iniciar a gravação, é necessária outra condição. Vá em frente e adicione esse nó para verificar se “USER.START_RECORDING” é igual a “true” e nomeie a condição como “Iniciar gravação” e o nó como “Verificar gravação”.

Condition node: Start Recording

Nós de gravação

É melhor avisar que a ligação está sendo gravada para evitar problemas legais. Precisamos apenas de dois nós para isso. Um “nó de voz” que contenha a mensagem de TTS: “Esta ligação está sendo gravada”

Speak node: Announce recording

Adicione um nó “Iniciar gravação” (localizado na seção “Ações”)

Start recording node

Estabelecer a ligação

Conectar a chamada exige um pouco de lógica se quisermos gravar. Se usarmos o nó “Roteamento de chamadas”, a chamada será encaminhada, encerrando a gravação. Mesmo assim, adicione o nó “Roteamento de chamadas” para os casos em que não quisermos gravar e “NCCO”. Você precisa adicionar seu número de telefone para o roteamento de chamadas, mas, para o NCCO, precisamos colocá-lo em uma conferência. O NCCO usa JSON para controlar o que acontece na chamada. Você pode ver todas as opções aqui. Para o Honeypot, adicione o seguinte:

{
  "action": "connect",
  // You can get this number from your Vonage dashboard
  "from": "<vonage phone number>",
  "endpoint": [
    {
      "type": "phone",
      "number": "<your personal phone number>"
    }
  ]
}

NCCO Node

Conectando tudo

Agora que todos os nós estão configurados, vamos definir nossos caminhos, o que é bem simples. Basta clicar nos círculos abertos em cada nó e arrastar até o próximo nó. Vamos explicar como os caminhos devem se desenrolar:

• Verificar quem está ligando:

  • 2XX vai para “Verificar gravação”

  • Falha, e o código 404 leva à mensagem “Desafie o autor da chamada”.

• Autor do desafio:

  • A opção é “Verificar DTMF”.

  • Se não houver entrada e se a chamada for perdida, vá para o nó “Encerrar chamada”

• Verificar DTMF:

  • A pessoa que ligou digitou 42 para “Verificar a gravação”.

  • Por padrão, o sistema volta para “Desafiar o chamador”.

• Verificar a gravação:

  • Inicie a gravação para “Anunciar gravação”

  • Definir como padrão “Encaminhar para mim”

• Digamos que a gravação passe para “Iniciar gravação”, depois para “Incluir-me na conferência” e, por fim, para “Sair do fluxo”

• Encaminhe para mim:

  • seu número vai para o fluxo de saída

  • Em caso de falha, o fluxo segue para outro nó de encerramento de chamada

Quando tudo estiver pronto, deve ficar assim:

Agent builder workflow

O fluxo para o nosso agente está pronto para ser utilizado. Na barra de navegação à esquerda, clique no ícone de raio ao lado de “Eventos” e selecione “Chamada recebida”. Quando a página carregar, volte aos nós e adicione um nó “Fluxo”. Selecione o fluxo que criamos. Basta clicar em “Publicar”, atribuir um número de telefone da Vonage e o agente estará pronto. Agora, todas as chamadas recebidas deverão passar por esse Honeypot.

Conclusão

Se você tiver dúvidas ou sugestões, junte-se a nós no Slack dos desenvolvedores da Vonage ou me envie uma mensagem no Mastodon, e eu entrarei em contato com você. Mais uma vez, obrigado pela leitura, e nos vemos no próximo post!