Como lidar com entradas do teclado numérico (DTMF) usando PHP

Neste tutorial, vamos abordar tudo o que você precisa saber para configurar uma aplicação em PHP capaz de receber chamadas e capturar as entradas do usuário digitadas pelo teclado.

Ao seguir este tutorial, você terá, ao final, uma aplicação simples que pode ser ampliada para incluir elementos interativos mais complexos e que lhe dará uma vantagem inicial na criação de menus interativos para seus usuários.

O código deste tutorial pode ser encontrado no GitHub.

Pré-requisitos

Resumo - Você vai precisar do seguinte:

• Um número de telefone que ainda não esteja associado a outro aplicativo

• PHP (>5.6), Composer e o framework Slim

• ngrok

Aqui está a versão completa:

Se você quiser acompanhar, vai precisar de um Account no Nexmo para começar; portanto, cadastre-se agora, caso ainda não tenha um.

Receber uma ligação com o Nexmo custa €0,0045/min, e você precisará alugar um número para que as pessoas possam ligar. Falaremos sobre isso mais tarde.

O código de exemplo utiliza o framework Slim para lidar com as solicitações. Escolhemos esse framework por causa de sua simplicidade e legibilidade, mas, se você estiver familiarizado com PHP e quiser lidar com isso de uma maneira diferente, fique à vontade para usar outra opção. Você precisará instalar o Slim usando o Composer , portanto, certifique-se de que ele também esteja configurado.

Espera-se que o código que você criará funcione com qualquer versão do PHP 5.6 ou superior.

Nossa forma recomendada de trabalhar com o Nexmo, do ponto de vista administrativo, é utilizar nossa ferramenta de linha de comando, Nexmo-CLI.

Para tornar o código em nossa máquina local acessível ao mundo exterior, vamos usar o ngrok; portanto, certifique-se de que ele também esteja instalado.

Atendimento de uma chamada recebida

Quando a Nexmo recebe uma chamada em um número que você alugou, é enviada uma solicitação HTTP para uma URL (um “webhook”, que você especifica) que contém todas as informações necessárias para receber e responder à chamada. Isso é comumente chamado de URL de resposta.

Também coletaremos entradas DTMF dos nossos chamadores. DTMF significa Multifrequência de Duas Tonais e, no caso deste tutorial, ocorre quando um usuário pressiona um número no teclado.

Sempre que uma entrada DTMF for recebida do usuário, ela será enviada para uma URL diferente no seu aplicativo, que também precisaremos especificar.

A seguir, começaremos escrevendo o código necessário para processar essas solicitações.

Para instalar o Slim usando o Composer, execute o seguinte comando no terminal, dentro da pasta do projeto:

Em seguida, na sua pasta principal, crie um novo arquivo chamado index.php e adicione o seguinte código a ele:

<?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('/webhooks/answer', function (Request $request, Response $response) {
    $uri = $request->getUri();
    $ncco = [
        [
            'action' => 'talk',
            'text' => 'Please enter a digit'
        ],
        [
            'action' => 'input',
            'maxDigits' => 1,
            'eventUrl' => [
                $uri->getScheme().'://'.$uri->getHost().'/webhooks/dtmf'
            ]
        ]
    ];

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

$app->run();

Com esse código, estamos configurando uma nova URL em nosso aplicativo, webhooks/answer, que responderá a quaisquer chamadas recebidas no seu número de telefone com as instruções fornecidas na $ncco array.

O $ncco executará essas etapas assim que a chamada for atendida:

1. Leia em voz alta o texto “Digite um dígito”

2. Capture o dígito digitado pelo chamador

3. Encaminhar a entrada capturada para a rota responsável por processá-la, /webhooks/dtmf

Processar a entrada do usuário

Vamos adicionar o código para processar os sinais DTMF recebidos em index.php:

Após o código que inserimos acima, e antes de $app->run(); adicione o seguinte:

$app->post('/webhooks/dtmf', function (Request $request, Response $response) {
    $params = $request->getParsedBody();

    $ncco = [
        [
            'action' => 'talk',
            'text' => 'You pressed '.$params['dtmf']
        ]
    ];

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

A função desta rota executará as seguintes etapas:

1. Receba a entrada de /webhooks/answer

2. Analisar o corpo da solicitação e armazená-lo em uma variável, $params

3. Crie uma nova $ncco matriz que responda ao chamador e informe qual número ele digitou.

A título de referência, seu arquivo final index.php deve ficar exatamente igual a este aqui.

Agora que você já está configurado e pronto para executar o código, pode fazer isso digitando o seguinte comando no terminal:

Isso iniciará um servidor e redirecionará todo o tráfego http://localhost:3000 seu index.php arquivo.

Divulgue seu aplicativo com o ngrok

Para permitir que a Nexmo faça solicitações ao seu aplicativo, você precisa tornar o código em execução na sua máquina local acessível ao mundo.

O ngrok é a nossa ferramenta preferida para isso, e disponibilizamos uma excelente introdução à ferramenta que você pode ler para se familiarizar com ela, caso ainda não a tenha usado antes.

Depois de instalar o ngrok, execute ngrok http 3000 para expor seu aplicativo à internet. Você precisará anotar a ngrok URL gerada, pois precisaremos fornecê-la à Nexmo na próxima etapa (ela terá um formato semelhante a http://45hfh5.ngrok.io).

Compre um número e crie um aplicativo

Com o código concluído e nosso aplicativo disponível para o mundo, agora precisamos obter um número de telefone e vincular esse código — que será executado localmente — a ele.

Vamos começar comprando um número por meio da CLI do Nexmo:

Você pode usar um código de país diferente, se quiser. Anote o número que você comprar, pois vamos precisar dele na próxima etapa.

Agora precisamos criar um aplicativo Nexmo, que é um contêiner para todas as configurações necessárias para o seu aplicativo. Nesse caso, precisamos informar ao Nexmo para qual URL enviar uma solicitação quando for recebida uma chamada (o answer_url), e para onde enviar quaisquer informações de eventos sobre a chamada (o event_url; você pode saber mais sobre eventos na documentação do Call Flow ).

Use a CLI do Nexmo para criar seu aplicativo, certificando-se de substituir <your_ngrok_url> pela sua própria URL gerada que o ngrok forneceu anteriormente:

A resposta que você receberá conterá uma saída extensa da chave privada e, acima dela, um ID de aplicativo. Você pode ignorar a chave privada, pois ela não é necessária para o tratamento de chamadas recebidas.

Anote o ID do aplicativo (que tem o seguinte formato: e7a25242-77a1-42cd-a32e-09febcb375f4) e, em seguida, vincule-o ao seu novo número:

Isso é tudo o que você precisa para associar o código acima ao seu aplicativo Nexmo e ao seu número. Você pode testar ligando para o número que comprou e seguindo as instruções que, como por mágica, serão ditas para você do outro lado da linha!

Conclusão

Com apenas trinta linhas de PHP, você já tem um aplicativo capaz de receber uma chamada e coletar entradas DTMF do chamador. Como você poderia expandir isso a partir daqui?

Se você quiser saber mais sobre as possibilidades oferecidas pelas chamadas de voz recebidas e como torná-las mais complexas ao adicionar recursos como a gravação de áudio, você pode obter mais informações sobre como operar seus NCCOs na guia de 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.