Gravar uma mensagem de telefone com Java

Introdução

Em um tutorial anterior, mostramos a vocês como receber uma chamada telefônica com Java e responder usando a conversão de texto em fala. Também podemos permitir que os usuários deixem uma mensagem e, em seguida, recuperem essa mensagem gravada.

Pré-requisitos

Você utilizará o Gradle para gerenciar suas dependências e executar seu aplicativo. Além disso, você precisará ter uma cópia do JDK instalada. Usarei o JDK 8 neste tutorial.

Por fim, você precisará do CLI da Vonage instalada. Você a utilizará para adquirir um número de telefone e configurar sua conta da Vonage para que ela aponte para seu novo aplicativo.

Gravar uma mensagem de telefone com Java

Este tutorial irá guiá-lo pelas seguintes etapas:

1. Usando o Gradle para configurar um novo projeto em Java.

2. Usando o estrutura do Spark para controlar a chamada.

3. Adquirir um número e configurar sua conta da Vonage para usar esse número com seu aplicativo.

Usando o Gradle para configurar um novo projeto em Java

Você usará o Gradle para gerenciar suas dependências e para criar e executar sua aplicação Java.

O gradle init --type=java-application comando criará todas as pastas necessárias, além de uma classe de exemplo na qual você escreverá seu código.

Na linha de comando, crie um novo projeto Java com os seguintes comandos:

Utilização do Spark Framework para controlar a chamada

Você utilizará o framework Spark para receber uma chamada HTTP enviada pela Vonage quando seu número receber uma chamada e para receber a solicitação que a Vonage envia após a gravação da mensagem.

Adicionando as dependências

Adicione o seguinte ao dependencies bloco no seu build.gradle arquivo:

// Spark Framework
implementation 'com.vonage:client:[6.1.0,7.0.0)'
//Vonage Client
implementation "com.sparkjava:spark-core:2.6.0"

Seu dependencies bloco deve ficar assim:

dependencies {
    testImplementation 'junit:junit:4.12'

    implementation 'com.vonage:client:[6.1.0,7.0.0)'
    implementation "com.sparkjava:spark-core:2.6.0"
}

O Gradle criará a App classe na src/main/java pasta. Dentro dessa classe há um getGreeting e um main método. Você não precisará do getGreeting , então fique à vontade para removê-lo.

Definir a rota de resposta

Primeiro, você definirá a rota que será usada para atender a chamada. Quando uma chamada for recebida, a Vonage enviará uma solicitação para uma URL de webhook predefinida. Ela espera receber um Objeto de Controle de Chamadas da Vonage (NCCO) contendo uma lista de ações a serem executadas.

Quando a chamada for atendida, seu aplicativo instruirá a Vonage a executar três ações:

1. Uma talk ação para cumprimentar a pessoa que está ligando e orientá-la sobre como deixar uma mensagem.

2. Uma record ação que instruirá a Voice API a iniciar a gravação.

3. Uma talk ação para agradecer a eles por deixarem uma mensagem.

Este é o NCCO resultante que seu aplicativo irá criar:

[
  {
    "text": "Please leave a message after the tone, then press #. We will get back to you as soon as we can.",
    "action": "talk"
  },
  {
    "endOnSilence": 3,
    "endOnKey": "#",
    "beepStart": true,
    "eventUrl": [
      "http://your-web-address/webhooks/recordings"
    ],
    "action": "record"
  },
  {
    "text": "Thank you for your message. Goodbye",
    "action": "talk"
  }
]

Adicione o seguinte ao main método da App classe, certificando-se de resolver todas as importações:

/*
* Route to answer and connect incoming calls with recording.
*/
Route answerRoute = (req, res) -> {
    String recordingUrl = String.format("%s://%s/webhooks/recordings", req.scheme(), req.host());

    TalkAction intro = new TalkAction.Builder("Please leave a message after the tone, then press #. We will get back to you as soon as we can.")
            .build();

    RecordAction record = new RecordAction.Builder()
            .eventUrl(recordingUrl)
            .endOnSilence(3)
            .endOnKey('#')
            .beepStart(true)
            .build();

    TalkAction outro = new TalkAction.Builder("Thank you for your message. Goodbye").build();

    res.type("application/json");

    return new Ncco(intro, record, outro).toJson();
};

A record ação possui algumas propriedades diferentes. Por exemplo, é possível definir a URL do evento para a qual será enviada uma solicitação quando a gravação terminar, encerrar a gravação ao pressionar uma tecla específica e reproduzir um bipe no início da gravação.

Definir a rota das gravações

A record ação possui uma propriedade chamada eventUrl , que é usada para comunicar quando a gravação estiver concluída. A seguir, um exemplo dos parâmetros de retorno enviados para a URL do evento:

{
  "start_time": "2020-01-01T12:00:00Z",
  "recording_url": "https://api.nexmo.com/media/download?id=aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "size": 12345,
  "recording_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "end_time": "2020-01-01T12:01:00Z",
  "conversation_uuid": "bbbbbbbb-cccc-dddd-eeee-0123456789ab",
  "timestamp": "2020-01-01T14:00:00.000Z"
}

O Cliente Java da Vonage possui uma classe chamada RecordEvent que pode ser usada para desserializar o JSON enviado para eventUrl. Por enquanto, você vai exibir o recording_url no console.

Adicione o seguinte ao main método da App classe, resolvendo todas as importações:

/*
* Route which prints out the recording URL it is given to stdout.
*/
Route recordingRoute = (req, res) -> {
    RecordEvent recordEvent = RecordEvent.fromJson(req.body());
    System.out.println(recordEvent.getUrl());

    res.status(204);
    return "";
};

Registrar as rotas

Até agora, você definiu duas rotas:

• A primeira rota enviará um NCCO à Vonage quando a Vonage atender a chamada recebida.

• A segunda opção registrará a URL da gravação quando a Vonage concluir a gravação da mensagem.

Para utilizar essas rotas, precisamos configurar o Spark. Sua aplicação ficará à escuta na porta 3000, e as rotas serão configuradas em /webhooks/answer e /webhooks/recordings.

Adicione o seguinte ao main método da App classe:

Spark.port(3000);
Spark.get("/webhooks/answer", answerRoute);
Spark.post("/webhooks/recordings", recordingRoute);

Compra de um número

Você precisará de um número da Vonage para receber chamadas telefônicas. Caso não tenha um número, você pode usar o CLI da Vonage para adquirir um

Primeiro, procure um número disponível com Voice recursos

Depois de escolher um número de sua preferência, você pode comprá-lo por meio de:

Anote o número da sua compra. Você precisará desse número para vincular seu aplicativo e para realizar os testes.

Como disponibilizar seu aplicativo

Para enviar uma solicitação HTTP ao seu aplicativo, a Vonage precisa saber a URL em que o seu aplicativo está sendo executado.

Em vez de configurar sua rede local ou hospedar seu aplicativo em um serviço externo, você pode usar o ngrok para expor seu aplicativo à internet com segurança.

Baixe o ngrok e execute o seguinte comando:

Anote o endereço de encaminhamento, pois você precisará dele ao configurar sua conta. Na imagem a seguir, o endereço de encaminhamento é http://99cad2de.ngrok.io.

Screenshot of ngrok running in terminal with forwarding address http://99cad2de.ngrok.io

Configure seu Account da Vonage

Se você não tiver uma aplicação, pode usar a CLI da Vonage para criar uma utilizando seu endereço de encaminhamento do ngrok:

Você também pode passar sua própria chave pública com --public_keyfile. Mais instruções aqui

Após executar esse comando, será exibido um ID de aplicativo. Por exemplo: notreal-1111-2222-3333-appid. Você precisará desse ID de aplicativo para vincular seu número de telefone ao aplicativo.

Você pode usar a CLI da Vonage para vincular seu número de telefone ao aplicativo:

Este comando instrui a Vonage a criar um novo aplicativo em sua Account. O aplicativo enviará uma solicitação para a primeira URL ao receber uma chamada telefônica. O aplicativo enviará solicitações para a segunda URL quando o status da chamada for alterado.

Teste seu aplicativo

Inicie seu aplicativo com o gradle run comando dentro do seu record-a-message diretório.

Ligue para o seu número da Vonage e teste seu aplicativo. Você ouvirá a mensagem: “Por favor, deixe uma mensagem após o sinal e, em seguida, pressione #. Entraremos em contato assim que possível.” Assim que ouvir o bipe, deixe uma mensagem e, em seguida, pressione #. Você deverá ouvir “Obrigado pela sua mensagem. Até logo.” e o link da gravação será exibido no seu console.

Conclusão

Com apenas algumas linhas de código, você criou um aplicativo capaz de receber uma ligação, gravar uma mensagem e, em seguida, exibir a URL dessa gravação.

Confira nossa documentação no Vonage Developer, onde você poderá saber mais sobre fluxo de chamadas ou Objetos de Controle de Chamadas da Vonage. Confira nossos Exemplos de Início Rápido da Vonage para Java para exemplos completos de código sobre este tutorial e muito mais.