Chamadas de voz com conversão de texto em fala usando PHP

Durante anos, fazer e receber chamadas telefônicas no seu código era algo complicado (e geralmente envolvia escrever um pouco de Java e conectar um telefone antigo ao seu laptop para servir como gateway!). Felizmente, hoje em dia isso não é nem de longe tão difícil, graças a serviços como Vonage (antigo Nexmo).

As Voice calls são um excelente meio de comunicação, pois são muito mais imediatas do que e-mails ou SMS. Se você precisar passar uma mensagem para alguém com urgência, ligar é a melhor maneira de fazer isso; é difícil ignorar um telefone tocando.

Nesta postagem, você vai criar um pequeno aplicativo que poderá ser usado para iniciar uma chamada telefônica de saída usando nosso cliente PHP.

O código completo desta postagem está disponível em nossos repositório de blocos de construção em PHP no GitHub.

Pré-requisitos

Você precisará ter o PHP instalado antes de seguir as instruções deste post. Estou usando o PHP 7.4, mas o código aqui deve funcionar no PHP 5.6 e versões posteriores. Você também precisará de o Composer disponível para instalar o cliente PHP da Nexmo.

Em seguida, você precisará de o NPM para instalar o Nexmo CLI.

Você precisará de uma maneira de disponibilizar ao público o aplicativo que está desenvolvendo, para que a Vonage possa se comunicar com ele. Você pode fazer isso usando uma ferramenta como ngrok. Se você não estiver familiarizado com a ferramenta, há uma ótima introdução ao ngrok disponível no blog da Vonage. Por enquanto, abra um terminal e execute ngrok http 8000. Anote seu ngrok URL, pois você precisará substituí-la https://example.com por ela ao configurar seu aplicativo da Vonage.

Por fim, se você ainda não tiver um aplicativo Vonage Voice pronta, você precisará criar um aplicativo, adquirir um número e vinculá-lo a ele. A maneira mais fácil de fazer isso é usando a ferramenta CLI da Nexmo. Aqui está o resumo:

• Instale a ferramenta CLI da Vonage executando npm install -g vonage-cli

• Faça a autenticação com seu CLI da Vonage executando vonage config:set --apiKey=<api_key> --apiSecret=<api_secret>. Substitua api_key e api_secret pelas suas credenciais encontradas no seu Painel de Controle

• Crie um aplicativo, substituindo voice-answer-url e voice-event-url pelos seus endpoints, executando vonage apps:create "Test Application 1" --vbc --voice_answer_url=http://example.com/webhooks/answer. Anote o ID do aplicativo que for retornado

• Encontre um número disponível para compra fazendo uma busca: vonage numbers:search US

• Compre um dos números exibidos nos resultados da pesquisa executando vonage numbers:buy <number>. Anote o número adquirido

• Por fim, vincule o número ao seu aplicativo executando vonage apps:link <application_id> --number=<number>

Crie seu espaço de trabalho

Vamos configurar o ambiente de trabalho para que você possa começar a desenvolver seu aplicativo. Este tutorial utiliza o framework Slim para receber eventos de chamadas da Vonage e retornar instruções sobre como essas chamadas devem ser tratadas. Use o Composer para inicializar um projeto com o Slim, executando os comandos abaixo:

Esses comandos criarão uma pasta chamada vonage-calls, mudar para o diretório recém-criado e instalar Slim no seu novo projeto. Copie o private.key arquivo que você salvou ao criar o aplicativo para esta pasta. Ele deve estar no mesmo nível que composer.json.

Em seguida, você precisa iniciar o servidor PHP local para poder fazer chamadas HTTP ao seu aplicativo. Para isso, abra um novo terminal e execute php -t public -S localhost:8000. Seu aplicativo agora está escutando na porta 8000 em sua máquina local e está disponível pela internet graças ao ngrok comando que você executou anteriormente.

Neste momento, você já tem uma aplicação Slim inicializada, em escuta e exposta à internet. Essa configuração é tudo o que é necessário para começar a enviar respostas à Vonage, a fim de instruí-la sobre como lidar com as chamadas telefônicas.

Criando seu NCCO

As chamadas da Vonage são controladas por meio dos Objetos de Controle de Chamadas da Nexmo (ou NCCOs). Um NCCO define uma lista de ações que o sistema da Vonage deve seguir quando uma chamada é atendida. Há diversas ações disponíveis, tais como:

• Transferir uma chamada para outro número com connect.

• Gravar uma ligação com record.

• Criar uma teleconferência com conversation.

• Gerar uma mensagem de conversão de texto em fala com talk.

• Além de outros — consulte nossa referência da NCCO para obter a lista completa.

Para começar, você vai criar um NCCO simples:

[
  {
    "action": "talk",
    "voiceName": "Amy",
    "text": "The amount of visible light from a lamp is measured in lumens"
  }
]

Crie um arquivo chamado index.php com o seguinte conteúdo. O exemplo de código abaixo inicializa o aplicativo Slim, define um manipulador e, em seguida, instrui Slim que esse handler seja usado sempre que receber uma GET solicitação para /webhook/answer:

<?php

use \Psr\Http\Message\ServerRequestInterface as Request;
use \Psr\Http\Message\ResponseInterface as Response;
use Slim\Factory\AppFactory;
require __DIR__ . '/vendor/autoload.php';

$app = AppFactory::create();

$app->get('/webhook/answer', function (Request $request, Response $response) {
    $ncco = [
        [
            'action' => 'talk',
            'voiceName' => 'Amy',
            'text' => 'The amount of visible light from a lamp is measured in lumens'
        ]
    ];

    $response->getBody()->write(json_encode($ncco));

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

$app->run();

Como a Vonage faz um GET envia uma solicitação para o seu answer_url, você adiciona um manipulador que corresponda a essas solicitações ($router->get('/webhook/answer')) e retorna uma resposta JSON (return response()->json()).

Desde que você retorne o JSON no formato correto, a Vonage sabe como lidar com a chamada. É só isso! Salve suas alterações e, em seguida, ligue para o número que você adquiriu para ouvir sua mensagem de conversão de texto em voz.

Fazer uma chamada de saída

Você começou muito bem, mas nosso objetivo era fazer uma chamada de saída, não apenas atender chamadas recebidas. Felizmente para você, já fez a maior parte do trabalho. Quando você faz uma chamada de saída, a Vonage ainda liga para o seu answer_url para saber como lidar com a ligação.

Para iniciar uma chamada de saída, é necessário enviar uma POST solicitação à API da Vonage que contenha to, from e answer_url juntamente com algumas informações de autenticação.

Embora seja possível criar essa chamada manualmente, o cliente PHP da Nexmo facilita muito o processo. Então, vamos instalá-lo com o Composer. Execute o seguinte comando no mesmo diretório do seu composer.json:

Depois de instalar o cliente Nexmo, você poderá adicionar um novo endpoint que será chamado para acionar uma nova chamada de saída. Você precisará do ID do aplicativo e da chave privada que salvou anteriormente para autenticar suas chamadas de API; em seguida, precisaremos fazer uma chamada para a Voice API da Vonage. Você precisará copiar private.key na mesma pasta que o seu composer.json e substituir APPLICATION_ID e YOUR_VONAGE_NUMBER pelos seus valores. (Não se esqueça de fornecer sua própria ngrok em vez de example.com também!)

$app->get('/makeCall/{number}', function (Request $request, Response $response, array $args) {
    $keypair = new \Nexmo\Client\Credentials\Keypair(
        file_get_contents(__DIR__ . '/private.key'),
        'APPLICATION_ID'
    );

    $client = new \Nexmo\Client($keypair);

    $client->calls()->create([
        'to' => [[
            'type' => 'phone',
            'number' => $args['number']
        ]],
        'from' => [
            'type' => 'phone',
            'number' => 'YOUR_VONAGE_NUMBER'
        ],
        'answer_url' => ['https://afb8ad306a73.ngrok.io/webhook/answer']
    ]);

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

Depois de fazer isso, faça um GET solicitação para /makeCall/ para acionar uma chamada de saída com conversão de texto em fala via Nexmo.

NCCOs dinâmicos

Você conseguiu o que se propôs a fazer, mas ficou um pouco monótono. Você transmite a mesma mensagem toda vez que faz uma ligação. Para torná-la mais dinâmica, você poderia anunciar a hora atual, mas aqui vai uma ideia um pouco mais interessante. Sempre que fizer uma ligação, você enviará uma solicitação ao Banco de Dados do Chuck Norris e ler a resposta durante a ligação.

Para isso, você usará uma biblioteca HTTP leve chamada Guzzle. Para usar o Guzzle, você precisa instalá-lo usando o Composer. Execute o seguinte comando no mesmo diretório do seu arquivo composer.json:

Depois de instalar o Guzzle, você precisa fazer uma solicitação ao Banco de Dados do Chuck Norris e usar a resposta para preencher seu NCCO. Por padrão, você vai limitar a busca a piadas nerds. Adicione o seguinte no início do seu /answer handler:

$client = new GuzzleHttp\Client();
$apiResponse = json_decode($client->get('http://api.icndb.com/jokes/random?limitTo=[nerdy]')->getBody());

Isso retornará uma piada aleatória da categoria “nerd”. O próximo passo é atualizar o NCCO para usar o valor de $apiResponse:

$ncco = [
    [
        'action' => 'talk',
        'voiceName' => 'Amy',
        'text' => $apiResponse->value->joke
    ]
];

Agora, sempre que a Vonage fizer uma solicitação ao seu answer_url você buscará uma piada aleatória do banco de dados do Chuck Norris e a usará como resposta de conversão de texto em fala. Você pode testar isso agora, seja fazendo uma ligação para o seu número da Vonage ou acionando uma chamada de saída por meio do makeCall terminal.

Parabéns! Você acabou de criar um sistema de chamadas de voz com conversão de texto em fala capaz de lidar tanto com chamadas recebidas quanto com chamadas feitas. Daqui para frente, você poderá personalizar a resposta de acordo com quem está ligando, a hora do dia ou qualquer outro critério que vier à sua mente.

E agora?

E agora, o que vem a seguir? Você poderia ampliar seu aplicativo para um sistema de alertas críticos baseado em voz , percorrendo uma lista de contatos para fazer chamadas em massa e fazer com que os destinatários digitem um número para confirmar o recebimento das suas mensagens.