Como lidar com chamadas recebidas usando o Node.js

Introdução

A Voice API da Vonage é a maneira mais fácil de criar aplicativos de voz de alta qualidade na nuvem. Com a Voice API, você pode:

• Crie aplicativos que se adaptem às tecnologias da web que você já utiliza.

• Controle o fluxo de chamadas recebidas e efetuadas em JSON com Objetos de Controle de Chamadas da Nexmo (NCCO). (Observação: a Nexmo agora é a Vonage).

• Gravar e armazenar chamadas recebidas ou realizadas

• Criar teleconferências

• Envie mensagens com conversão de texto em fala em 40 idiomas, com diferentes gêneros e sotaques.

• E muito mais!

Neste tutorial, você aprenderá a receber chamadas recebidas implementando um webhook usando o Node.js.

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.

• OPCIONAL - CLI do Vonage Depois de instalar o Node.js, instale a CLI digitando npm install -g @vonage/cli. Essa ferramenta permite criar e gerenciar Applications da Vonage a partir de uma interface de linha de comando, em vez de usar o Portal do Desenvolvedor da Vonage.

Criar uma aplicação da Vonage com recursos de voz

Para usar a Voice API da Vonage, é necessário criar uma Aplicativo Vonage no portal do desenvolvedor. Se você ainda não tem uma conta, crie uma, pois oferecemos créditos para você começar. Não é necessário cartão de crédito.

Precisaremos configurar os webhooks do aplicativo e outras coisas. Observe que isso pode ser feito por meio do Portal do Desenvolvedor da Vonage ou pela CLI da Vonage. Para este tutorial, usaremos o Painel de Controle do Desenvolvedor da Vonage.

Depois de criar um Account, faça login no Painel do Desenvolvedor da Vonage e procure a seção “Aplicativos”e crie um novo aplicativo. Dê um nome ao seu aplicativo, como InboundCall.

InboundCall.png

Role a página para baixo e certifique-se de que o Voice esteja ativada.

Anote o Respostae URLs , pois vamos preenchê-las em breve. Vamos deixar a URL de reserva em branco.

VoiceCapability.png

Imprensa Gerar novo pedido na parte inferior da página para continuar.

Este tutorial também utiliza um número de telefone virtual. Para adquirir um, acesse Numbers > Comprar Numbers e procure um que atenda às suas necessidades. Depois de obter um número, vincule-o ao Painel do Desenvolvedor da Vonage, conforme mostrado abaixo.

LinkedNumber.png

A seguir, usaremos o ngrok para expor nossos endpoints de webhook em nossa máquina local como uma URL pública.

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 4001

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.png

Lembre-se do Resposta e URLs no Portal do Desenvolvedor da Vonage, conforme mencionado anteriormente? Precisaremos usar a URL do ngrok e preencher cada campo, acrescentando /answer e /event, para a URL de resposta e a URL de evento.

webhooksection.png

Quando você ligar para o número associado ao aplicativo e a ligação for atendida, o webhook definido no URL de Resposta é acionado. Da mesma forma, os eventos são registrados por meio de uma solicitação POST e são acionados ao ligar para o número ou se o número estiver ocupado, etc.

Configuração de um projeto Node.js

Agora que criamos nosso aplicativo Vonage Voice no painel do desenvolvedor, vamos ver como devemos configurar nosso aplicativo Node.js.

Comece abrindo uma janela de comando/terminal, criando um diretório de trabalho e inicializando um projeto Node.js.

Vamos dar andamento às solicitações com Express e usaremos o body-parser para analisar os corpos das solicitações recebidas. Instale ambos com:

npm install express body-parser --save

Crie um index.js arquivo, instancie o Express e escute o servidor na porta 4001. Como você configurou o ngrok para expor localhost:4001, você deve usar a mesma porta.

'use strict'
const app = require('express')();
const bodyParser = require('body-parser');
app.use(bodyParser.json());
app.use(bodyParser.urlencoded({ extended: true }));
const server = app.listen(process.env.PORT || 4001, () => {
  console.log('Express server listening on port %d in %s mode', server.address().port, app.settings.env);
});

Vamos definir o endpoint para a URL da resposta como /answer e a URL do evento como /event.

Crie uma rota HTTP GET para processar as solicitações de /answer para recuperar seu NCCO:

app.get('/answer', function (req, res) {
  const ncco = [
    {
      action: 'talk',
      voiceName: 'Jennifer',
      text: 'Hello, thank you for calling. This is the Jennifer voice from Vonage.'
    }
  ];
  res.json(ncco);
});

Defina o texto a ser lido por uma voz sintetizada em JSON (ou objeto JavaScript, neste caso). Você pode personalizar o objeto NCCO com parâmetros opcionais , escolhendo entre diversos agentes por idioma, gênero e até mesmo sotaque.

O endpoint para a event_url precisa ser POST, então vamos definir /event:

app.post('/event', function (req, res) {
  console.log(req.body);
  res.status(204).end();
});

Lembre-se de que vamos monitorar o status do nosso terminal. Veja este exemplo de código para ver um exemplo de plano alternativo que lida com situações como tempo limite, linha ocupada, chamada não atendida etc.

Executar o aplicativo

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

node index.js

Vamos fazer uma ligação para verificar se seu aplicativo funciona! Ligue para o seu número virtual usando seu telefone físico. Se tudo funcionar, você deverá ouvir a mensagem que definiu no seu NCCO.

Além disso, verifique no seu terminal o status da sua chamada. Veja abaixo um exemplo de como fica o meu:

{
  headers: {},
  from: '19999999999',
  to: '19999999999',
  uuid: '912e...',
  conversation_uuid: 'CON-07f...',
  status: 'ringing',
  direction: 'inbound',
  timestamp: '2023-02-22T19:27:47.276Z'
}

O status mudará dependendo da fase em que a chamada se encontra no momento. Por exemplo, começamos com ringing, depois passamos para started, depois answered, e, finalmente, completed se a chamada for bem-sucedida.

Conclusão

Agora que você criou uma chamada recebida com a Voice API da Vonage e o Node.js, por que não aprender a enviar mensagens de conversão de texto em fala em mais de 40 idiomas? Você também pode saber mais sobre nossa Voice API e explorar vários trechos de código.

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