Compartilhar:
){kind=small}
Ex-redator técnico da Vonage. Adora experimentar e documentar APIs.
Reproduzir um arquivo de áudio durante uma chamada de Voice com Java e Spark
Tempo de leitura: 17 minutos
Este tutorial mostra como transmitir áudio durante uma chamada usando a Voice API Nexmo.
O caso de uso mais óbvio para isso é reproduzir música de espera ou mensagens. Ninguém gosta muito de ficar em espera. Mas você pode tornar essa experiência o mais agradável possível, oferecendo aos seus clientes algo para ouvir, em vez de silêncio. Estudos demonstraram que o tempo parece passar mais rápido quando os clientes têm algo para ouvir, e isso também pode reduzir significativamente seus níveis de ansiedade — o que é ótimo quando eles ligam para o seu atendimento ao cliente para reclamar.
No entanto, os mesmos estudos também indicaram que quem liga pode reagir negativamente se não gostar do que é obrigado a ouvir. Portanto, escolha sua música ou mensagem com cuidado e, faça o que fizer, não faça um “Rick Roll” neles!
Para atender uma chamada recebida, é necessário criar um webhook e configurar sua conta Nexmo para usá-lo. Usaremos Java e a framework web Spark para criar o webhook. Assim que a chamada estiver em andamento, usaremos a Biblioteca Cliente da API REST da Nexmo para Java para transmitir o áudio para ele. Você pode encontrar uma versão do código deste tutorial no GitHub.
O JDK ou seu equivalente de código aberto, o OpenJDK. Este tutorial foi escrito usando o OpenJDK 11, mas qualquer uma das versões a partir da 8 deve funcionar bem.
Gradle (versão 3.4 ou posterior) para compilar seu projeto e gerenciar suas dependências.
ngrok para disponibilizar seu webhook na Internet pública.
Você precisa de um número virtual da Nexmo para receber chamadas. É possível adquirir um diretamente no painel do desenvolvedor, mas, neste tutorial, você utilizará a ferramenta CLI da Nexmo .
Instale a CLI do Nexmo:
Em seguida, configure-o com o seu NEXMO_API_KEY e NEXMO_API_SECRET no painel do desenvolvedor:
Use a CLI da Nexmo para exibir os Numbers com voice recursos que estão disponíveis para compra no seu país, substituindo GB no comando a seguir pelo seu próprio código de país de dois caracteres:
Escolha um número e compre-o:
Você deve tornar seu webhook acessível às APIs da Nexmo. Uma ótima maneira de fazer isso durante o desenvolvimento é usar ngrok. Para saber mais, leia nossa postagem no blog sobre o ngrok.
Baixe e instale ngroke, em seguida, execute o comando a seguir para disponibilizar seu aplicativo na porta 3000 para a Internet pública:
Anote as URLs públicas que ngrok são fornecidas e deixe o programa em execução durante todo este tutorial (pois você precisará configurar seu aplicativo com essas URLs, e ngrok ele fornece URLs novas e aleatórias toda vez que você o executa, a menos que você se inscreva em um plano pago):
Terminal showing the ngrok URLs
Crie um diretório para o seu projeto chamado play-audio-into-call, vá para esse diretório e, em seguida, use gradle para inicializar o projeto:
Aceite todas as configurações padrão e, em seguida, abra o projeto gerado no seu IDE.
Localize o build.gradle arquivo e altere o repositório de dependências de jcenter() para mavenCentral():
repositories {
mavenCentral()
}Substitua a dependencies seção pelo seguinte:
dependencies {
// Spark framework
implementation 'com.sparkjava:spark-core:2.8.0'
// Nexmo client library
implementation 'com.nexmo:client:4.4.0'
// Use JUnit test framework
testImplementation 'junit:junit:4.12'
}Não vamos usar JUnit neste exemplo, mas você pode deixá-lo lá por enquanto, sem problema.
O Gradle criou a App classe no src/main/java/play/audio/into/call diretório.
Abra App.java no seu IDE. Remova o getGreeting() método que gradle foi criado para você e adicione a instrução necessária import instrução necessária para o spark pacote.
Em seguida, chame o método port para indicar que seu aplicativo está à espera de solicitações na porta 3000.
O seu App.java deveria ficar assim:
package play.audio.into.call;
import static spark.Spark.*;
public class App {
public static void main(String[] args) throws Exception {
port(3000);
System.out.println("I'm listening!");
}
}Execute seu aplicativo digitando gradle run no play-audio-into-call diretório. Verifique se está funcionando acessando http://localhost:3000 no seu navegador e ver a mensagem “I’m listening” exibida na página.
Um aplicativo de Voice API é um conceito da Nexmo e não deve ser confundido com o aplicativo que você vai desenvolver. Trata-se, na verdade, de um “contêiner” para as configurações de autenticação e configuração necessárias para trabalhar com a API.
Você pode criar um aplicativo da Voice API usando a CLI da Nexmo. É necessário fornecer um nome para o aplicativo e as URLs de dois endpoints de webhook: o primeiro é aquele para o qual as APIs da Nexmo enviarão uma solicitação quando você receber uma chamada recebida no seu número virtual, e o segundo é onde a API pode enviar dados de eventos.
Neste tutorial, estamos interessados apenas no webhook “answer”; portanto, você pode fornecer qualquer URL para o webhook “event”. Substitua o nome de domínio no comando da CLI do Nexmo a seguir pelo seu ngrok nome de domínio e execute-o no diretório raiz do seu projeto:
Este comando baixa um arquivo chamado private.key que contém informações de autenticação e retorna um ID exclusivo do aplicativo. Anote esse ID, pois você precisará dele nas etapas seguintes.
Agora você precisa vincular seu número virtual da Nexmo ao seu aplicativo da Voice API. Execute o seguinte comando da CLI da Nexmo, substituindo NEXMO_NUMBER pelo seu número virtual da Nexmo (incluindo o código de discagem internacional, mas omitindo quaisquer zeros à esquerda) e APPLICATION_ID pelo ID do aplicativo que você gerou na etapa anterior:
A configuração está concluída. Vamos voltar a programar seu aplicativo.
Quando a Nexmo receber uma chamada no seu número virtual, ela enviará uma GET solicitação ao seu /webhooks/answer ponto de extremidade. Esse ponto de extremidade ainda não existe, mas você o criará em breve.
A Nexmo espera que seu webhook forneça uma resposta que contenha um Objeto de Controle de Chamadas da Nexmo (NCCO). Trata-se de uma matriz de objetos no formato JSON, cada um dos quais descreve um action que informa à Nexmo como lidar com a chamada.
Neste exemplo, você lerá uma mensagem de boas-vindas para quem está ligando usando a função de conversão de texto em fala e, em seguida, colocará essa pessoa em uma conferência. As duas ações do NCCO que permitem fazer isso são talk e conversation, respectivamente. Portanto, o NCCO que você precisa incluir em sua resposta terá a seguinte forma:
[
{
"action": "talk",
"voiceName": "Russell",
"text": "Please wait while we connect you to the conference"
},
{
"action": "conversation",
"name": "Test Conference"
}
]A talk ação deve ser bastante autoexplicativa. Tudo o que você está fazendo é ler a text string de volta para o usuário na Russell Voice. (Você pode encontrar uma lista completa das vozes disponíveis aqui).
A conversation ação exige que você forneça um name para a conferência, para que você possa incluir vários participantes na mesma conferência. Neste tutorial, você provavelmente será o único participante, mas ainda assim é necessário nomeá-la. Estamos usando a conversation ação apenas para manter a chamada aberta, para que possamos transmitir áudio para ela mais tarde.
A Biblioteca cliente da API REST da Nexmo para Java oferece algumas classes auxiliares para criar esse NCCO; portanto, vamos configurá-lo primeiro.
Inclua a seguinte importação no seu App.java arquivo:
import com.nexmo.client.NexmoClient;Em seguida, no seu main método, logo abaixo da chamada para port(3000), instancie a biblioteca do cliente, substituindo /path/to/your/private.key pelo caminho para o seu private.key arquivo e APPLICATION_ID pelo seu ID de aplicativo da Voice API:
public class App {
public static void main(String[] args) throws Exception {
port(3000);
NexmoClient client = NexmoClient.builder()
.applicationId("APPLICATION_ID")
.privateKeyPath("/path/to/your/private.key")
.build();
}
}
Então, primeiro você precisa criar esse endpoint. A rota que você usará para isso é /webhooks/answer.
Inclua as seguintes import instruções:
import com.nexmo.client.voice.VoiceName;
import com.nexmo.client.voice.ncco.Ncco;
import com.nexmo.client.voice.ncco.TalkAction;
import com.nexmo.client.voice.ncco.ConversationAction;E adicione este código ao seu main método:
get("/webhooks/answer", (req, res) -> {
String callId = req.queryParams("uuid");
System.out.println("Call answered. The UUID for this call is: " + callId);
TalkAction intro = TalkAction.builder("Please wait while we connect you to the conference.")
.voiceName(VoiceName.RUSSELL)
.build();
ConversationAction conversation = ConversationAction.builder("Test conference")
.build();
res.type("application/json");
return new Ncco(intro, conversation).toJson();
});
Este código utiliza o TalkAction e ConversationAction classes auxiliares da biblioteca do cliente Nexmo para construir o NCCO, que é então retornado na resposta à Nexmo.
Teste isso verificando primeiro se ngrok está em execução e, em seguida, execute gradle run. Em seguida, ligue para o seu número virtual da Nexmo. Seu aplicativo exibirá o UUID da chamada e você deverá ouvir a mensagem de boas-vindas. A linha permanecerá aberta até que você desligue.
Agora você precisa de uma maneira de reproduzir o áudio na teleconferência. Para isso, você criará uma rota chamada /play/:id, em que :id é o UUID da chamada na qual você deseja transmitir o áudio. Você chamará essa rota manualmente assim que a teleconferência estiver em andamento.
Adicione a seguinte import instrução:
import com.nexmo.client.voice.StreamResponse;Para criar a /play/:id rota no seu main :
get("/play/:id", (req, res) -> {
String id = req.params(":id");
final String URL = "http://example.com/your/audio/file.mp3";
System.out.println("Playing audio into " + id.toString());
StreamResponse startStreamResponse = client.getVoiceClient().startStream(id, URL, 0);
System.out.println(startStreamResponse.getMessage());
Thread.sleep(5000);
client.getVoiceClient().stopStream(id);
return "";
});
Substitua URL pela URL de um arquivo de áudio de sua escolha. Você pode usar https://nexmo-community.github.io/ncco-examples/assets/voice_api_audio_streaming.mp3 para testar.
Essa rota extrai o UUID da chamada da GET URL da solicitação e o utiliza no startStream método para identificar a chamada correta para a qual o áudio deve ser transmitido. Ele reproduz o áudio por cinco segundos e, em seguida, interrompe a reprodução chamando stopStream. Se você não o interrompesse dessa forma, a reprodução continuaria indefinidamente, conforme especificado pelo terceiro parâmetro de startStream que informa à Nexmo quantas vezes o áudio deve ser reproduzido, sendo que zero significa infinito.
Está tudo pronto! Agora você pode testar.
Execute seu aplicativo Java a partir do diretório do aplicativo:
Ligue para o seu número virtual, ouça a mensagem de boas-vindas e anote o UUID da chamada exibido no console.
Em um navegador, ou usando o Postman ou uma ferramenta semelhante, crie uma GET solicitação para o /play ponto de extremidade, passando o UUID da chamada, por exemplo:
http://localhost:3000/play/d2af966a2fa415b7080b2762940a828c
Você deve ouvir um áudio que termina após cinco segundos.
Neste tutorial, você aprendeu a criar um aplicativo Java com o framework Spark para atender uma chamada no seu número virtual da Nexmo usando a Voice API, criar uma conferência e, em seguida, transmitir áudio para ela. Convide um amigo para ligar para o número ao mesmo tempo que você, para que ambos possam participar da conferência. Experimente usar diferentes arquivos de áudio e crie um /stop/:id ponto de extremidade para que você possa controlar a duração do áudio manualmente.