Receber uma chamada de Voice com PHP

Em nossa última postagem no blog sobre PHP e Voice, abordamos como fazer uma chamada de voz de saída usando a conversão de texto em fala. Nesta postagem, vamos mudar de rumo e criar um aplicativo que atenda chamadas de voz recebidas e retorne uma resposta dinâmica.

O código-fonte desta postagem do blog está disponível no GitHub.

Pré-requisitos

Você precisará ter o PHP instalado antes de seguir as instruções deste post. Estou usando o PHP 7.2, mas o código aqui deve funcionar no PHP 5.6 e versões posteriores. Você também precisará de o Composer para baixar nossas dependências.

Por fim, você precisará do CLI da Vonage instalada. Vamos usá-la para configurar nossa conta da Vonage e adquirir um número de telefone.

Recebendo uma ligação telefônica com PHP

Antes de entrarmos nos detalhes sobre como tudo isso funciona, vamos começar criando um aplicativo em PHP para lidar com chamadas de voz recebidas. Quando uma chamada de voz for recebida, a Vonage enviará uma solicitação ao seu aplicativo para saber como responder a essa chamada.

Vamos usar o framework Slim para processar a solicitação recebida; então, vamos instalá-lo agora com composer:

Assim que isso estiver concluído, crie um novo arquivo chamado index.php com o seguinte conteúdo. Isso criará um novo aplicativo Slim e registrará um único endpoint (/webhook/answer) que aceita uma GET solicitação com um from parâmetro de string de consulta e retorna o from valor no corpo.

<?php
use \Psr\Http\Message\ServerRequestInterface as Request;
use \Psr\Http\Message\ResponseInterface as Response;

require 'vendor/autoload.php';

$app = new \Slim\App;
$app->get('/webhook/answer', function (Request $request, Response $response) {
    $params = $request->getQueryParams();
    return $response->withJson($params['from']);
});

$app->run();

Salve este arquivo e, em seguida, abra uma nova janela do terminal. Vamos iniciar o servidor PHP integrado e disponibilizar nosso aplicativo na porta 8000.

Se você visitar http://localhost:8000/webhook/answer?from=14155550100, você verá o from número retornado no corpo da resposta.

Esse é um ótimo começo, mas a Vonage não saberá o que fazer se respondermos apenas com o número de telefone do chamador. Para informar à Vonage como lidar com a chamada, precisamos retornar um NCCO.

Para simplificar, vamos usar a função de conversão de texto em fala para ler o número de telefone da pessoa que está ligando para ela mesma, dígito por dígito. Primeiro, dividimos o número em uma matriz de caracteres e, em seguida, os unimos usando espaços:

$fromSplitIntoCharacters = implode(" ", str_split($params['from']));

Em seguida, definimos um NCCO que utiliza a talk ação para ler esses caracteres:

$ncco = [
    [
        'action' => 'talk',
        'text' => 'Thank you for calling from '.$fromSplitIntoCharacters
    ]
];

Então, por fim, retornamos esse NCCO em vez de $params['from']:

return $response->withJson($ncco);

Quando juntamos tudo isso, index.php fica assim:

<?php
use \Psr\Http\Message\ServerRequestInterface as Request;
use \Psr\Http\Message\ResponseInterface as Response;

require 'vendor/autoload.php';

$app = new \Slim\App;
$app->get('/webhook/answer', function (Request $request, Response $response) {
    $params = $request->getQueryParams();
    $fromSplitIntoCharacters = implode(" ", str_split($params['from']));

    $ncco = [
        [
            'action' => 'talk',
            'text' => 'Thank you for calling from '.$fromSplitIntoCharacters
        ]
    ];

    return $response->withJson($ncco);
});

$app->run();

Visite http://localhost:8000/webhook/answer?from=14155550100 novamente e você verá o seguinte resultado:

[
  {
    "action": "talk",
    "text": "Thank you for calling from 1 4 1 5 5 5 5 0 1 0 0"
  }
]

Parabéns! Você acabou de criar uma aplicação que recebe uma chamada telefônica e responde com algum conteúdo dinâmico. Você pode personalizar sua resposta usando qualquer um dos parâmetros fornecidos pela Vonage, incluindo to, from e conversation_uuid.

Como disponibilizar seu aplicativo com o ngrok

Criamos uma aplicação que funciona como esperávamos, mas há um grande problema no momento. A Vonage deveria enviar uma solicitação para ela quando uma chamada é recebida, mas ela está rodando na nossa máquina local!

Mas não se preocupe, o ngrok pode resolver tudo. Se você ainda não conhece o ngrok, há uma fantástica introdução ao ngrok disponível no blog da Vonage.

Depois de instalar o ngrok, execute ngrok http 8000 para expor seu aplicativo à internet. Você precisará anotar a ngrok URL gerada, pois precisaremos fornecê-la à Vonage (ela terá um formato semelhante a http://abc123.ngrok.io).

Configure seu account da Vonage

Assim que seu aplicativo estiver disponível na internet, a última coisa a fazer é associá-lo a um número de telefone da Vonage. Vamos começar comprando um número de telefone usando a CLI da Vonage. Primeiro, procure um número:

Então, compre um dos números listados como disponíveis:

O próximo passo é criar um aplicativo Vonage, que funciona como um contêiner para todas as configurações necessárias ao seu aplicativo. Neste caso, precisamos informar à Vonage para qual URL deve ser enviada uma solicitação quando uma chamada for recebida (answer_url), e para onde enviar quaisquer informações de eventos relacionadas à chamada (event_url).

Podemos usar a CLI do Nexmo para criar uma aplicação, lembrando-nos de substituir http://abc123.ngrok.io pela sua própria URL gerada. Forneçamos um nome e, em seguida, um answer_url e event_url para o aplicativo:

Anote o ID do seu aplicativo (será algo parecido com aaaaaaaa-bbbb-cccc-dddd-0123456789ab) e continue lendo.

A última coisa a fazer é vincular o número que você comprou ao aplicativo que acabou de criar. Isso indicará à Vonage que, quando uma chamada for recebida, ela deve fazer uma GET solicitação ao aplicativo answer_url para saber como proceder com a chamada.

Mais uma vez, podemos usar a CLI do Nexmo para fazer isso, substituindo o número de telefone e o ID do aplicativo do exemplo pelos seus:

Isso é tudo o que precisávamos fazer para que a Vonage associasse nosso aplicativo em PHP a uma chamada telefônica recebida. Experimente agora mesmo ligando para o número de telefone que você adquiriu.

Conclusão

Juntos, acabamos de criar uma aplicação capaz de receber uma chamada telefônica e gerar dinamicamente uma resposta com apenas 22 linhas de código!

Se você quiser saber mais sobre chamadas de voz com PHP e Vonage, pode encontrar modelos de código de exemplo no Nexmo Developer. Alternativamente, se você quiser tornar sua resposta a chamadas recebidas mais complexa (por exemplo, gravando o áudio do chamador), pode saber mais sobre NCCOs na referência do NCCO

Como sempre, se você tiver alguma dúvida sobre esta postagem, sinta-se à vontade para enviar um e-mail para devrel@nexmo.com ou participe do canal da comunidade Nexmo no Slack, onde estamos à sua disposição, prontos para ajudar.