){kind=small}
Encaminhar uma chamada por meio de um proxy de voz com o Koa.js
Tempo de leitura: 12 minutos
Este tutorial mostra como adicionar recursos de Voice ao seu aplicativo. Usaremos o Koa, um framework web para Node.js, para criar um servidor que processe chamadas e eventos recebidos e a Voice API da Vonage para encaminhar chamadas para outro número de telefone. Vamos começar.
Ao final deste projeto, é assim que a pasta do seu projeto deve ficar:
Para acompanhar este tutorial, você precisará de:
Node.js instalado
O Ngrok é instalado para expor seu servidor de desenvolvimento local à internet.
Um account de desenvolvedor da Vonage para acessar nossa Voice API.
Para que possamos expor endpoints de nossas máquinas locais sem precisar implantar nosso aplicativo em um ambiente de produção, tornaremos nosso servidor local acessível pela internet usando ngrok
Após a instalação, em uma nova janela do terminal/linha de comando, inicie ngrok na porta 3000:
ngrok http 3000
Você pode criar e gerenciar applications da Vonage usando a CLI da Vonage. Instale-a, caso ainda não o tenha feito:
npm install @vonage/cli -g
Execute o comando para definir a configuração da chave de API e do segredo de API. Depois disso, você verá Configuration saved no seu terminal ou no prompt de comando.
O VONAGE_KEY e VONAGE_SECRET podem ser encontradas no Painel da Vonage.
Vonage Dashboard
Use a CLI para criar um novo aplicativo com recursos de Voice e anote o ID do aplicativo fornecido no momento da criação. Execute o comando para criar um novo aplicativo da Vonage.
Em seguida, aparecerá uma janela de diálogo com alguns campos, e você deve chamar a função `fill` da seguinte maneira.
Você deve receber uma resposta semelhante a esta:
Em seguida, precisaremos de um número virtual que funcione como nossa “fachada pública” para as chamadas recebidas. Esse número estará vinculado ao nosso aplicativo da Vonage, e veja a seguir como obtê-lo:
Pesquise números disponíveis na região de sua preferência. Felizmente, podemos comprar números diretamente da CLI assim!
vonage numbers:search US(substitua “US” pelo código do seu país, se necessário).Compre um número:
vonage numbers:buy 12079460000 US.
Lembre-se de que alguns Numbers não podem ser adquiridos pela linha de comando; portanto, você deve comprá-los pelo painel de controle. Para isso, acesse o Painel da Vonage e na página página “Comprar Numbers”. Marque a opção “Voice” no filtro de busca e selecione o país onde deseja comprar um número.
Agora que escolhemos nosso número, é hora de conectá-lo ao nosso aplicativo da Vonage. Você pode vincular um número de telefone virtual diretamente no Painel de Controle da Vonage ou por meio da CLI. O vinculação garante que as chamadas para o seu número virtual sejam encaminhadas corretamente pelo seu aplicativo.
vonage apps:link --number=12079460000 APPLICATION_ID
Você também pode fazer isso pelo painel. Acesse a página “Applications” e clique no aplicativo que você criou anteriormente. Clique no botão “Vincular”, na seção Voice, ao lado do número que você deseja vincular.
Crie um novo diretório para o seu projeto e acesse-o. (Exemplo de pasta
VoiceWithVonage)Inicialize um novo projeto Node.js com
npm init -ypara aceitar todas as configurações padrão.
Nosso projeto depende de algumas dependências, que instalaremos com um único comando:
Usaremos variáveis de ambiente para armazenar informações confidenciais, como chaves de API e números de telefone, a fim de manter nosso aplicativo seguro e fácil de gerenciar.
Crie um .env arquivo na raiz do seu projeto e adicione suas variáveis Consulte a postagem no blog do Michael para obter uma explicação mais detalhada sobre como usar variáveis de ambiente no Node.js
// .env
VONAGE_API_KEY= Your Vonage API key, used for authenticating API requests.
VONAGE_API_SECRET= Your Vonage API secret
VONAGE_APPLICATION_ID= The ID of your Vonage application. Vonage applications allow you to manage your communication services and define how they interact with your web application.
VONAGE_PRIVATE_KEY= The path to your Vonage application's private key file. When you create a Vonage application that uses voice capabilities, you generate a public/private key pair. The private key authenticates your application when making API requests. It will look like nameOfTheFile.key.
FROM_NUMBER= The Vonage virtual number (purchased through Vonage) that calls will come from. It is the number displayed to the user receiving the call.
YOUR_SECOND_NUMBER= The destination phone number to which the call will be forwarded. It should be in [E.164 format](https://en.wikipedia.org/wiki/E.164).
O SDK do servidor da Vonage facilita a integração com os serviços da Vonage. Inicialize-o em seu projeto para habilitar a funcionalidade de Voice, certificando-se de que os valores provisórios sejam substituídos pelas suas credenciais de API armazenadas no seu .env arquivo.
Crie um arquivo chamado forward_a_call.js e o código abaixo.
// forward_a_call.js
require("dotenv").config();
const { Vonage } = require("@vonage/server-sdk");
// Initialize the Vonage Server SDK with your credentials
const vonage = new Vonage({
apiKey: process.env.VONAGE_API_KEY,
apiSecret: process.env.VONAGE_API_SECRET,
applicationId: process.env.VONAGE_APPLICATION_ID,
privateKey: process.env.VONAGE_PRIVATE_KEY,
});
Começamos configurando nosso ambiente de servidor:
require("dotenv").config();
const Koa = require("koa");
const Router = require("@koa/router");
const koaBody = require("koa-bodyparser");
const app = new Koa();
const router = new Router();
app.use(koaBody());Aqui, importamos os módulos necessários e inicializamos nossa aplicação Koa. O dotenv carrega as variáveis de ambiente (como suas credenciais da API da Vonage e números de telefone) a partir de um .env arquivo.
O middleware koaBodyparser é utilizado para analisar o corpo das solicitações recebidas, o que é essencial para a leitura de cargas JSON em nosso webhook /event.
Além disso, utilizamos o @koa/router, um middleware de roteamento, para definir e gerenciar rotas em nossa aplicação. Isso nos permite especificar ações para diferentes caminhos, como /answer para atender chamadas e /event para processar eventos de webhook.
A /answer rota é definida como a resposta a chamadas recebidas. Quando a plataforma da Vonage recebe uma chamada para o seu número virtual, ela solicita que esse /answer terminal recupere instruções, conhecidas como NCCO (Call Control Object), sobre como lidar com a chamada.
Neste exemplo, o NCCO instrui a Vonage a reproduzir primeiro uma mensagem (“Aguarde enquanto conectamos sua chamada.”) e, em seguida, conectar a chamada a outro número especificado (YOUR_SECOND_NUMBER), utilizando seu número da Vonage (FROM_NUMBER) como identificador de chamadas.
router.get("/answer", async (ctx) => {
const ncco = [
{
action: "talk",
text: "Please wait while we connect your call.",
},
{
action: "connect",
eventUrl: [],
from: process.env.FROM_NUMBER,
endpoint: [
{
type: "phone",
number: process.env.YOUR_SECOND_NUMBER,
},
],
},
];
ctx.body = ncco;
});
O /event rota captura e registra eventos relacionados à chamada. Esse endpoint é essencial para depurar e monitorar o ciclo de vida das suas chamadas. Os eventos podem incluir status da chamada, como atendida, concluída ou com falha. Ao registrar esses eventos, podemos obter informações sobre o fluxo da chamada e solucionar quaisquer problemas
Por fim, aplicamos nossas rotas ao aplicativo Koa e iniciamos o servidor.
router.post("/event", async (ctx) => {
console.log(ctx.request.body);
ctx.status = 204; // No content to send back
});
app.use(router.routes()).use(router.allowedMethods());
app.listen(3000, () => console.log("Server running on port 3000"));
O aplicativo fica à escuta na porta 3000 e registra uma mensagem no console assim que o servidor é iniciado. Nesse momento, as rotas que definimos ficam acessíveis, permitindo que a plataforma da Vonage interaja com nosso servidor com base nas URLs especificadas no Painel da Vonage para os webhooks de resposta e de eventos do nosso aplicativo.
Com tudo pronto, inicie o servidor executando o comando:
Teste o encaminhamento de chamadas discando seu número virtual da Vonage. A chamada deve ser redirecionada para o número especificado no seu .env arquivo.
Parabéns! Agora você já domina a arte do encaminhamento de chamadas com a Vonage. Se tiver alguma dúvida ou sugestão, ou se quiser compartilhar o que criou, participe da nossa Comunidade de Desenvolvedores da Vonage no Slack ou entre em contato pelo X, antes conhecido como Twitter.
Crie um plano de fuga com a Voice API da Vonage e receba uma chamada fantasma