Reproduzir um arquivo de áudio durante uma chamada de Voice com PHP

Sempre que ligo para o centro de lazer da minha região para agendar uma sessão de natação, sou recebido com um anúncio das últimas notícias: o centro ficará fechado por duas horas na próxima segunda-feira, o horário da natação em família mudou, etc. Neste artigo, vou mostrar um exemplo de como eles fazem isso com a Voice API da Vonage e um backend em PHP escrito no Slim Framework para reproduzir áudio durante uma chamada telefônica em andamento.

Pré-requisitos

• PHP 8 ou superior

• Compositor 2

• Nó 20+ (para a interface de linha de comando)

• npm 6+

• Um Account da Vonage

Em primeiro lugar, precisamos de um novo aplicativo Slim. Vou torná-lo o mais básico possível — sem grandes códigos padrão, sem modelos automáticos. Teremos um endpoint que acionará uma chamada de saída e um endpoint de entrada para ler o webhook gerado quando o usuário final atender a chamada.

Crie um diretório que irá conter nosso código e, em seguida, use o Composer para gerar um novo projeto:

composer init

Você pode pular todas as perguntas interativas pressionando a tecla Enter, o que fará com que sejam usados os valores padrão. Quando for perguntado se você deseja adicionar pacotes de forma interativa, certifique-se de recusar; isso é para que eu possa mostrar os comandos deste artigo para instalar a estrutura.

O Composer irá gerar seu arquivo de configuração composer.json, e uma pasta de dependências, vendor. As configurações padrão também criarão o diretório que abrigará seu código, src.

Na linha de comando, precisaremos instalar o framework Slim e uma interface PSR-7 para as classes de solicitação/resposta. O comando final incluirá o SDK PHP da Vonage, que cuida de todo o trabalho pesado para fazer as chamadas de API por você. Por fim, nosso cliente Vonage é configurado por meio de variáveis de ambiente, portanto, precisaremos da biblioteca padrão para lidar com isso.

composer require slim/slim
composer require slim/psr7
composer require vonage/client
composer require vlucas/phpdotenv

Agora que já temos o Slim e as outras dependências necessárias, podemos começar a escrever o aplicativo. O SDK PHP da Vonage requer um ID de aplicativo e uma chave privada, que você obtém ao criar uma nova instância de aplicativo no Painel da Vonage. Como alternativa, você pode fazer isso usando o CLI da Vonage, que é o caminho que vamos seguir.

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

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 (exemplos, fictícios) para anotar:

Nome: aplicativo para reproduzir áudio

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

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 como C:\Users\YOUR-USER-NAME se estiver usando o PowerShell no Windows) e coloque o arquivo no diretório raiz do seu projeto.

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. 

Porque você deveria nunca colocar segredos no seu código, crie um novo arquivo na raiz do seu projeto chamado .env. Preencha as variáveis com as informações correspondentes, sendo que TO_NUMBER que é o número para o qual o discador liga. Falaremos sobre isso BASE_URL mais tarde. O VONAGE_PRIVATE_KEY_PATH pode ser deixado como está no exemplo abaixo, e o VONAGE_NUMBER deve ser um Número Virtual da Vonage adquirido no Painel de Controle.

No src diretório, crie um novo arquivo, index.php, e adicione o seguinte código:

<?php

use Psr\Http\Message\ResponseInterface as Response;
use Psr\Http\Message\ServerRequestInterface as Request;
use Slim\Factory\AppFactory;
use Vonage\Client\Credentials\Keypair;
use Vonage\Voice\Endpoint\Phone;
use Vonage\Voice\OutboundCall;
use Vonage\Voice\Webhook;

require DIR . '/../vendor/autoload.php';

$dotenv = Dotenv\Dotenv::createImmutable(__DIR__ . '/../');
$dotenv->load();

$app = AppFactory::create();

$app->get('/dial', function (Request $request, Response $response, array $args) {
   $privateKeyPath = realpath(__DIR__ . '/../' . $_ENV['VONAGE_APPLICATION_PRIVATE_KEY_PATH']);
   $credentials = new Keypair(
       file_get_contents($privateKeyPath),
       $_ENV['VONAGE_APPLICATION_ID']
   );

   $client = new \Vonage\Client($credentials);

   $call = new OutboundCall(
       new Phone($_ENV['TO_NUMBER']),
       new Phone($_ENV['VONAGE_NUMBER'])
   );

   $call
       ->setAnswerWebhook(
           new Webhook($_ENV['BASE_URL'] . '/webhooks/answer', 'POST')
       )
       ->setEventWebhook(
           new Webhook($_ENV['BASE_URL'] . '/webhooks/event', 'POST')
       )
   ;

   $client->voice()->createOutboundCall($call);
   $response->getBody()->write('Outbound Call Started');
   return $response;
});

$app->post('/webhooks/answer', function (Request $request, Response $response, array $args) {
   $builder = new Vonage\Voice\NCCO\NCCO();
   $builder->addAction(new \Vonage\Voice\NCCO\Action\Talk('Here is some soothing music for you'));
   $builder->addAction(new \Vonage\Voice\NCCO\Action\Stream($_ENV['BASE_URL'] . '/music.mp3'));

   $response->getBody()->write(json_encode($builder->jsonSerialize()));

   return $response->withHeader('Content-Type', 'application/json');

});

$app->post('/webhooks/event', function (Request $request, Response $response, array $args) {
   var_dump($request->getParsedBody());
});

$app->run();

Há muita coisa acontecendo aqui, então vamos analisar isso passo a passo.

$dotenv = Dotenv\Dotenv::createImmutable(__DIR__ . '/../');
$dotenv->load();

Este código carrega o conteúdo do arquivo arquivo .env no superglobal do PHP $_ENV para configurar nosso cliente Vonage. $app = AppFactory::create() cria uma nova instância da aplicação Slim, para que possamos, então, configurar nossos endpoints.

Nosso discador de chamadas de saída está definido como uma rota HTTP GET, /dial. Portanto, o código abaixo será executado ao acessar essa rota. É aqui que configuramos o Vonage Client usando nossas credenciais, que podem ser acessadas a partir do $_ENV objeto:

$privateKeyPath = realpath(__DIR__ . '/../' . $_ENV['VONAGE_APPLICATION_PRIVATE_KEY_PATH']);
$credentials = new Keypair(
   file_get_contents($privateKeyPath),
   $_ENV['VONAGE_APPLICATION_ID']
);

$client = new \Vonage\Client($credentials);

Existem várias maneiras de usar credenciais no Vonage. No entanto, o importante a se observar é que o objeto Keypair aceita a string do arquivo da chave privada do seu aplicativo Vonage e o ID do aplicativo. O que o SDK do PHP faz de bastante útil é que, em tempo de execução, seu JWT é criado e adicionado ao cabeçalho automaticamente para você. Isso é importante para o aplicativo porque, enquanto você é possível usar a autenticação básica com algumas APIs do Vonage, a configuração de webhooks de entrada só funcionará com um JWT por motivos de segurança.

É possível configurar uma aplicação da Vonage no Painel de Controle para que ela sempre acesse a mesma URL de resposta e a mesma URL de evento para atualizações contínuas da aplicação. No entanto, como você pode ver no código utilizado, também é possível definir dinamicamente esses pontos de extremidade de webhooks. Isso seria útil quando você tiver instâncias de vários fluxos de trabalho diferentes e estiver acompanhando o andamento de chamadas individuais. Por exemplo, você pode adicionar uma tabela de banco de dados que, então, possa realizar operações do tipo CRUD com um UUID no caminho da URL. Isso oferece flexibilidade para lidar com várias consultas ao mesmo tempo, caso você utilize algo como Ligação de Modelo de Rota com Laravel Octane. Nosso código Slim é um pouco mais simples para facilitar a leitura:

$call = new OutboundCall(
   new Phone($_ENV['TO_NUMBER']),
   new Phone($_ENV['VONAGE_NUMBER'])
);

$call
   ->setAnswerWebhook(
       new Webhook($_ENV['BASE_URL'] . '/webhooks/answer', 'POST')
   )
   ->setEventWebhook(
       new Webhook($_ENV['BASE_URL'] . '/webhooks/event', 'POST')
   );

$client->voice()->createOutboundCall($call);

$response->getBody()->write('Outbound Call Started');

return $response;

O caminho do Webhook é configurado por meio da variável de ambiente BASE_URL. Agora que temos o caminho da chamada de saída, precisaremos definir o que é essa BASE_URL é.

Você precisará primeiro executar o aplicativo localmente. Para simplificar ao máximo, usaremos o servidor embutido no PHP. Acesse o arquivo src e, em seguida, inicie-o:

php -S localhost:8080

Nossos Webhooks são POST que vêm diretamente da Vonage. Portanto, sem expor nosso aplicativo à Internet, não há como a Vonage acessar nosso aplicativo no localhost. A ferramenta mais comumente usada para expô-lo seria o o Ngrok, cujas instruções de instalação aqui. Se você quiser mantê-lo estritamente em PHP, pode usar o Expose da Beyond Code, que aproveita o poder de um loop de eventos fornecido pelo ReactPHP. O importante é executar uma dessas ferramentas e anotar a URL que for retornada. Em seguida, cole-a no campo BASE_URL no arquivo .env e pronto! Uma maneira de receber dados.

A última parte do nosso código de execução pega esses dados, avisa que o som está prestes a tocar e, em seguida, reproduz o som.

$app->post('/webhooks/answer', function (Request $request, Response $response, array $args) {
   $builder = new Vonage\Voice\NCCO\NCCO();
   $builder->addAction(new \Vonage\Voice\NCCO\Action\Talk('Here is some soothing music for you'));
   $builder->addAction(new \Vonage\Voice\NCCO\Action\Stream($_ENV['BASE_URL'] . '/audio.mp3'));

   $response->getBody()->write(json_encode($builder->jsonSerialize()));

   return $response->withHeader('Content-Type', 'application/json');
});

Esse código basicamente cria um JSON para enviar à Vonage, que então processará as instruções. Isso é feito por meio de objetos NCCO exclusivos da Vonage, e a boa notícia é que o SDK do PHP possui um construtor para facilitar esse processo! Temos duas ações: em primeiro lugar, um Talk a ser acionada quando a chamada for atendida e, em seguida, uma Stream para o áudio. Você vai notar que há uma URL aqui que usa o BASE_URL e, em seguida, um arquivo chamado audio.mp3. Trata-se de um espaço reservado — portanto, para que funcione, coloque qualquer arquivo chamado audio.mp3 na pasta src , e esse será o arquivo reproduzido durante a chamada. A Vonage consegue fazer isso porque o arquivo de áudio está no mesmo diretório que será exposto pelo servidor web integrado.

Está tudo pronto: acesse a URL para /dial e curta o que você escolher como arquivo de áudio, seja um jazz relaxante de elevador ou, se você realmente não gosta dos seus usuários finais, um pouco de dubstep moderno.

Conclusão

Nesta postagem, você aprendeu como reproduzir áudio em uma chamada existente e sobre o NCCO que que controlam o fluxo da chamada. Fique à vontade para fazer testes, substituindo diferentes arquivos de áudio e ações do NCCO ações. 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)

• Código-fonte do SDK do PHP