Transmitir áudio durante uma ligação telefônica com Node.js

Introdução

Quando você está falando com sua cliente por Voice, você tem toda a atenção dela. Por que não aproveitar essa oportunidade para contar a ela as últimas novidades sobre sua empresa, transmitir uma mensagem inspiradora do seu CEO ou até mesmo tocar para ela o seu mais recente jingle publicitário?

Nesta postagem do blog, você aprenderá como reproduzir um arquivo de áudio em uma chamada ativa por meio de programação, utilizando a Voice API da Vonage e o Node.js.

Antes de começar

Para seguir este exemplo, você precisará do Node.js. Caso ainda não o tenha, instale-o a partir do site do Node.js.

Você pode provisionar um número no Painel do Desenvolvedor da Vonage, mas vamos explicar passo a passo como usar o CLI da Vonage para adquirir um número, criar um aplicativo de voz e, em seguida, vincular seu número a ele.

Por fim, você vai querer o código-fonte usado neste artigo no GitHub. 

Clone o repositório e cd para o diretório raiz do aplicativo.

Instalar e configurar a CLI da Vonage

Instale a CLI do Vonage globalmente usando o seguinte comando:

npm install @vonage/cli -g

Em seguida, configure a CLI com sua chave e seu segredo da API da Vonage, que você encontrará no Painel do Desenvolvedor:

Vonage auth set –api-key=’VONAGE_API_KEY –api-secret=’VONAGE_API_SECRET’

Substitua o VONAGE_API_KEY e VONAGE_API_SECRET pelos seus dados para autenticar a CLI.

Você pode verificar sua autenticação para ter certeza de que tudo está funcionando corretamente usando o seguinte comando:

vonage auth check

Se você tiver instalado a CLI no seu projeto local, em vez de globalmente, pode adicionar um sinalizador extra para verificar:

vonage auth check –local

Adquira um número da Vonage

Você precisa de um número para fazer chamadas. Adquira um executando o comando a seguir, substituindo o código do país conforme o caso. Por exemplo, se você estiver nos EUA, substitua [CÓDIGO DO PAÍS] por US:

vonage numbers search [COUNTRYCODE]

Você pode adquirir o número de telefone executando o código abaixo no seu terminal. É importante observar que alguns países exigem a validação do endereço, e a compra deve ser feita pelo painel do Vonage, e não pela linha de comando.

vonage numbers buy [COUNTRYCODE] [MSIDSN]

Anote o número de telefone que o comando retorna.

Criar o aplicativo de voz

Para usar a Voice API, é necessário criar uma Voice API aplicativo. Isso não é a mesma coisa que o aplicativo web que você está desenvolvendo. Trata-se apenas de um contêiner para as informações de configuração e segurança necessárias para se conectar às APIs da Vonage.

vonage apps create "Play audio app" --private-key-file=~/private.key

Você receberá os seguintes dados para anotar:

Nome: aplicativo para reproduzir áudio

ID do aplicativo: 7a319bf9-49e7-413d-914b-402fe8e68228

Melhorar a IA: Desativado

Chave privada/pública: Definir

Você vai perceber que passamos ao comando o argumento private-key-file. Isso fará o download da sua chave privada assim que o comando for executado: localize esse arquivo de chave (no comando, usei o caminho no estilo UNIX ~/ location, que é a pasta pessoal; você deve definir como algo semelhante a. C:\Users\YOUR-USER-NAME se estiver usando o PowerShell no Windows) e coloque o arquivo no diretório raiz do código do artigo do blog que acompanha este texto.

Ainda não configuramos o aplicativo para usar a Voice API; portanto, execute o comando a seguir para adicionar o recurso de voz:

vonage apps capabilities update [VONAGE_APPLICATION_ID] --voice-answer-url=https://example.com/answer --voice-event-url=https://example.com/event-status

Você vai perceber que estamos definindo o voice-answer-url e o voice-event-url no nível do aplicativo. Por enquanto, esses são espaços reservados, e você não precisa alterar esses valores. Isso ocorre porque o código usado para fazer a chamada irá criá-los dinamicamente durante as chamadas HTTP realizadas. 

Inicializar as dependências

Para desenvolver esse aplicativo, vamos considerar os requisitos mínimos necessários para fazer uma chamada de voz e poder atualizar a instância da chamada para reproduzir áudio durante a ligação. Você precisará do seguinte:

• dotenv - uma biblioteca leve que permite ler um arquivo de variáveis de ambiente (o padrão de fato é nomeá-lo como .env. Precisaremos disso para inserir a chave da API e o segredo do Painel da Vonage em tempo de execução.

• express - A estrutura de nós mais leve e mais utilizada para funcionalidades básicas de HTTP. 

• @vonage/server-sdk - a biblioteca cliente REST para Node.js.

• @vonage/Voice - SDK do Voice do Vonage para Node.js

Podemos instalar um desses na linha de comando. Primeiro, precisaremos inicializar o projeto como um projeto npm, que então fará uma série de perguntas para definir as características gerais do projeto. Você pode escolher as opções padrão por enquanto; ele também perguntará se há algum pacote que você queira instalar, mas vamos pular essa etapa para esclarecer como adicionaremos as dependências posteriormente. Você também pode usar yarn para isso, então incluí essa opção como um trecho de código separado no terminal. Escolha a opção que for mais conveniente para você:

npm init

yarn init

Pressione Enter para selecionar todos os valores padrão — você pode dar o nome que quiser a esse pacote, já que isso não é importante neste contexto. Depois de fazer isso, o npm ou o yarn criará um package.json arquivo para você. A partir daqui, podemos adicionar os pacotes individuais:

npm install dotenv express @vonage/server-sdk @vonage/voice

Torne suas aplicações acessíveis pela Internet

Precisamos expor nosso aplicativo à Internet para que os servidores da Vonage possam enviar os webhooks da Voice API ao nosso aplicativo. Recomendamos usar o ngrok para isso.

Você pode saber mais sobre como configurar e executar o ngrok para instalar e executar o ngrok na porta 3000 (essa é a porta padrão do Express.js). Por exemplo:

ngrok http 3000

O ngrok fornecerá uma URL temporária, como https://914288e7.ngrok.io. Anote-a.

Mantenha o ngrok em execução enquanto estiver usando o aplicativo; caso contrário, as URLs serão alteradas e você precisará reconfigurá-lo.

Configurar o ambiente

Entendido. example.env para .env e insira os detalhes que você coletou nas etapas acima:

VONAGE_APPLICATION_ID= The Voice API application ID

VONAGE_APPLICATION_PRIVATE_KEY_PATH= private.key

VONAGE_NUMBER= The number you rented from Vonage

TO_NUMBER= The number you want the application to call

BASE_URL= The ngrok temporary URL

Agora você está pronto para ver o aplicativo em ação!

Executar o aplicativo

Inicie o aplicativo executando o seguinte comando:

node server.js

Se seu aplicativo express.js estiver funcionando corretamente, você deverá ver uma mensagem de log informando que o aplicativo está escutando na porta 3000. Acesse http://localhost:3000/call no seu navegador. Isso gera um solicitação GET para o /call ponto de extremidade do seu aplicativo e faz com que ele acione o TO_NUMBER em .env.

Você ouvirá uma mensagem, seguida de uma música que tocará por 20 segundos; em seguida, a ligação será encerrada.

Como isso funciona?

Vamos ver como tudo isso se encaixa no código. O funcionamento do aplicativo se divide em três partes:

1. Faça a chamada de saída.

2. Forneça à Vonage o objeto NCCO que definirá o que acontecerá quando o cliente final atender a chamada.

3. Transmita o áudio da música de espera para uma chamada ativa.

Faça a chamada de saída

O código a seguir é executado quando você envia um solicitação GET para o /call ponto de extremidade:

try {

   console.log("Making the outbound call...");

   const resp = await voice.createOutboundCall(

     {

       to: [{ type: "phone", number: TO_NUMBER }],

       from: { type: "phone", number: VONAGE_NUMBER },

       answer_url: [answer_url],

       answer_method: HttpMethod.POST, // This will hit the NCCO response

       event_url: [event_url], // Event URL to track events like answered

     }

   );

   console.log("Outbound call response:", resp);

   res.status(200).send("Call initiated!");

 } catch (error) {

   console.error("Error making the outbound call:", error);

   res.status(500).send("Failed to make call.");

 }

O biblioteca dotenv cuida de importar as .env variáveis do arquivo, para que saibamos para quem ligar. O answer_url informa à Vonage o que fazer quando a chamada for atendida — o que faremos aqui é retornar um NCCO, que criaremos usando a classe NCCO Builder no SDK do Node.

Definindo a resposta NCCO

Definimos o answer_url como um endpoint em nosso aplicativo express.js com o seguinte código:

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

 const builder = new NCCOBuilder();

 builder.addAction(

   new Talk('Here is some soothing music for you')

 )

 builder.addAction(

   new Stream(audio_url)

 );

 // Send back the generated NCCO

 res.json(builder.build());

});

Em primeiro lugar, é app.post() que define o caminho para o aplicativo. O que acontece a seguir se divide em duas partes: a Vonage espera receber instruções na forma de um NCCO para saber o que fazer quando a chamada for atendida; portanto, há duas partes nesse processo.

1. Use o Talk para informar ao cliente final que a música está a caminho

Você pode ver que criamos um novo NCCOBuilder objeto. Essa classe lida com todos os métodos necessários e encapsula a construção do objeto JSON do NCCO de forma organizada para o desenvolvedor. A primeira tarefa é informar ao usuário final que uma música agradável está a caminho; assim, o código cria um Talk() objeto que recebe um argumento de string como texto a ser convertido em fala. Usando o addAction(), você pode adicionar quaisquer objetos de valor que desejar para instruir a Vonage a realizar durante a chamada. Isso pode incluir a captura de entradas do usuário via DTMF, a captura de gravações de áudio e a conversão de texto em fala.

2. Transmitir o áudio para uma chamada em andamento

Este NCCO será executado de forma síncrona; portanto, as instruções contidas na carga útil do NCCO serão executadas uma de cada vez. A próxima instrução consiste em fornecer uma URL pública do nosso arquivo de música hospedado para ser transmitido durante a chamada. Isso é muito semelhante à Talk() ação. Fornecemos ao construtor uma nova ação sequencial a ser executada, que é uma Stream() ação. O primeiro argumento é uma string da URL para a qual queremos apontar, que já definimos como variável .

E pronto! Dois comandos para dar à Vonage durante a ligação, ao atender o telefone, e agora temos uma música agradável e relaxante enquanto esperamos em uma fila fictícia — e, provavelmente, estressante — para… ingressos de show ou uma consulta médica.

Conclusão

Nesta postagem, você aprendeu como reproduzir um arquivo de áudio durante uma chamada existente e sobre o NCCO actions que controlam o fluxo da chamada. Fique à vontade para fazer testes, substituindo por diferentes arquivos de áudio e NCCO actions. Os recursos a seguir podem ajudar:

• Referência da Voice API

• Referência NCCO

• Uso do SSML na TTS (conversão de texto em fala)

• A API REST biblioteca cliente para Node.js