Conectar chamadas usando a Voice API da Vonage e o Node.js

Introdução

Neste tutorial, vamos estabelecer uma chamada entre dois números de telefone e conectar outro número de telefone à chamada atual usando a Voice API da Vonage , com a ajuda do NCCOs.

Especificaremos um elemento NCCO no objeto de destino para controlar a chamada, indicando uma URL. Usaremos o ‘connect’ e 'talk’ NCCO ações.

Você pode encontrar o código completo do repositório do GitHub aqui.

Pré-requisitos

Antes de começar a compilar o projeto, certifique-se de que você tenha:

• A Account de desenvolvedor da Vonage.

• Node.js versão 20 ou superior e o npm instalados no seu computador.

• Ngrok para criar um túnel seguro para o seu localhost.

• Um editor de texto e conhecimentos básicos de JavaScript.

Configurar o aplicativo da Vonage

Criar uma aplicação de voz da Vonage

Criar um novo aplicativo: Acesse “Seus Applications” no painel e ative o recurso Voice.

Um vídeo explicativo sobre como criar um aplicativo da Vonage. 

Comprar e vincular um número de telefone virtual

Adquira um número virtual para seu aplicativo.

Vincule un número virtual ao seu aplicativo.

Recursos da Voice API

Iniciar uma instância de tunelamento do ngrok

O Ngrok é uma ferramenta que permite expor seu aplicativo à internet; você precisará dela para receber webhooks de eventos da Voice API da Vonage. Se você ainda não usou o ngrok, pode começar por aqui. Adicionei as etapas para executar uma instância abaixo da imagem. 

Execute o comando a seguir para iniciar uma instância de tunelamento do ngrok.

ngrok http 3000

ngrok                                                                 (Ctrl+C to quit)
                                                                                                 
👋 Goodbye tunnels, hello Agent Endpoints: https://ngrok.com/r/aep                               
                                                                                                 
Session Status                online                                                             
Account                       plan name                                         
Version                       3.22.0                                                             
Region                        Europe (eu)                                                        
Latency                       31ms                                                               
Web Interface                 http://127.0.0.1:4040                                              
Forwarding                    https://xyz.ngrok.app -> http://localhost:8000            
                                                                                                 
Connections                   ttl     opn     rt1     rt5     p50     p90                        
                              14      0       0.03    0.03    6.10    7.79  

Configurar os webhooks

De volta ao Painel da API da Vonage, na seção “Aplicativos”, ative a opção Voice em “Recursos” e defina a URL pública do seu servidor do ngrok como o endpoint para mensagens e eventos recebidos. Deve ficar assim: https://xyz.ngrok.com/answer para mensagens recebidas e https://xyz.ngrok.com/webhooks/status para status. Se você quiser saber mais sobre webhooks, consulte nossa documentação da Vonage.

Instale as dependências

É hora de abrir nosso editor de texto, criar um novo projeto e instalar as dependências necessárias. Usaremos o SDK de voz da Vonage para Node.js, Vonage JWT SDK para Node.js, Express, e Dotenv. 

Instale todos de uma vez sóe execute o comando a seguir para adicionar automaticamente esses pacotes ao seu package.json do seu projeto e ao diretório node_modules .

npm install @vonage/voice @vonage/jwt express dotenv

Implementar o código do lado do servidor

No seu arquivo src/server.js, inicie o projeto importando os módulos necessários. Você vai configurar o Express para lidar com as solicitações HTTP recebidas.

// src/server.js

// Import dependencies

require("dotenv").config();

const express = require("express");

const { NCCOBuilder, Talk, Connect } = require("@vonage/voice");

const { verifySignature } = require("@vonage/jwt");

// Create Express app

const app = express();

// Parse request body

app.use(express.json());

app.use(express.urlencoded({ extended: false })););

Variáveis de ambiente

Vamos criar um arquivo .env que que contenha todas as variáveis de ambiente que usaremos para esta aplicação web. Listei e expliquei todas elas abaixo. Você pode saber mais sobre uso de variáveis de ambiente no Node.js.

# .env

VONAGE_API_SIGNATURE_SECRET= this is the secret used to sign the request that corresponds to the signature secret associated with the API key included in the JWT claims. You can identify your signature secret on the Dashboard settings.

SECOND_PHONE_NUMBER= The phone number that will receive the control of the call

VONAGE_VIRTUAL_NUMBER= Your Vonage virtual number linked to the Vonage Application

> OBSERVAÇÃO: Ao inserir um número de telefone, não use um + ou 00 no início; comece com o código do país, como 16600700000.

Criar a função de verificação de JWT

Crie uma função JWT para verificar se a chamada recebida realmente veio da Vonage. Saiba mais sobre verificar a solicitação. 

// src/server.js

const verifyJWT = (req) => {

  // Verify if the incoming call came from Vonage

  const jwtToken = req.headers.authorization.split(" ")[1];

  if(!verifySignature(jwtToken, process.env.VONAGE_API_SIGNATURE_SECRET)) {

    console.error("Unauthorized request");

    throw new Error('Not a voice API request');

  }

  console.log('JWT verified');

}

Criar o endpoint para atender chamadas recebidas

Vamos criar um /answer ponto de extremidade, aquele ao qual adicionamos a URL no Painel da Vonage. Assim que uma chamada for feita para o telefone virtual da Vonage que adquirimos e vinculamos ao aplicativo, verificamos o JWT e adicionamos uma ação Talk: “Olá, esta é uma chamada de teste. A chamada será encaminhada em breve.”

// src/server.js

// Endpoint to handle inbound calls

app.all("/answer", (req, res) => {

 console.log("Received inbound call...");

 verifyJWT(req);

 // Build the NCCO for handling the call

 const builder = new NCCOBuilder();

 // Add the Talk action to greet the caller

 builder.addAction(

   new Talk("Hello, this is a test call. The call will be forwarded shortly.")

 );

Transferir a chamada atual para outro número

Em seguida, adicionamos um ação NCCO que conecta outro número de telefone à chamada, de modo que seja feita uma ligação para outro número de telefone, que é então conectado a essa chamada já existente.

// src/server.js

// Add the Connect action to forward the call to another number

 builder.addAction(

   new Connect(

     {

       type: "phone",

       number: process.env.SECOND_PHONE_NUMBER,

     },

     process.env.VONAGE_VIRTUAL_NUMBER

   )

 );

 let ncco = builder.build(); // Build the NCCO

 // Respond with the NCCO to control the call

 res.json(ncco);

});

Gerenciar eventos de chamadas da Vonage

Da mesma forma que /answer o que vimos anteriormente, também adicionamos um /webhooks/event  URL nas funcionalidades de Voice do Painel da Vonage; podemos registrar informações sobre os eventos para verificar, por exemplo, se a chamada foi rejeitada, o status da chamada, seu UUID etc.

// src/server.js

app.all("/webhooks/event", (req, res) => {

 console.log("Received Event:", req.body);

 const { status } = req.body;

 if (status === "rejected") {

   console.error("Call rejected. Check error code and message.");

 }

 // Ensure response is in JSON format

 res.status(200).json({ success: true }); // This should be a valid JSON response

});

Adicionar um ouvinte de porta

Por fim, adicionamos o trecho de código para que o servidor escute em uma porta específica; neste exemplo, defini a porta 3000.

// Listen on port 3000

app.listen(3000, () => {

  console.log("App listening on port 3000");

});

Execute e teste seu código

É hora de testar tudo. Comece executando o arquivo do servidor no seu terminal ou na linha de comando. 

node src/server.js

Certifique-se de que seu arquivo .env contém todas as variáveis de ambiente configuradas, que o ngrok esteja em execução e que as URLs corretas estejam configuradas no Painel da Vonage.

Ligue para o número de telefone virtual que você adquiriu e vinculou ao aplicativo. O primeiro número de telefone configurado recebe a ligação, que é então transferida para o segundo número, e você deverá receber a ligação nesse número.

Conclusão

Saiba mais sobre os Objetos de Controle de Chamadas no este Video do One-Dev-Minute e na documentação da Voice API da Vonage documentação do NCCO. 

Leitura complementar

Como atender uma chamada telefônica recebida com Python

Crie um plano de fuga com a Voice API da Vonage e receba uma chamada fantasma