Criação de um verificador de status de telefone com o Nexmo e PHP

Trabalhar em uma agência de web traz muitos desafios, pois temos a tarefa de lidar com vários clientes diferentes ao mesmo tempo. Nosso foco deve estar sempre nesses clientes, para garantir que suas necessidades sejam atendidas e que eles fiquem satisfeitos com o trabalho que estamos realizando. Portanto, algo que você provavelmente não quer são distrações externas. Era exatamente isso que acontecia em nosso escritório quase diariamente.

O cenário diário era o seguinte. Um gerente pegava o telefone para ligar para um cliente, o telefone não discava, e o gerente então gritava pelo escritório aberto: “Os telefones estão fora de serviço”, o que era repetido em tom de provocação por todo o escritório, dirigido ao engenheiro responsável pelo sistema telefônico. Ele parava o que estava fazendo, caminhava até o telefone com ar de derrota e voltava para sua mesa cinco minutos depois, após resolver o problema. Mais uma vez, isso acontecia quase diariamente.

Mas esse não era o único caso. O meu caso favorito foi quando, certa vez, as chamadas de telefones cujo número terminava em 87 não conseguiam se conectar ao nosso sistema telefônico.

Depois que isso aconteceu pela vigésima sétima vez, percebi que devia haver uma solução melhor para esse problema. Embora cinco minutos possam não parecer muito, o ritmo e a concentração dos engenheiros ainda eram interrompidos, o que levava a mais vinte minutos tentando retomar de onde haviam parado, lembrando o que estavam fazendo e voltando ao ritmo de trabalho.

Então, comecei a fazer alguns projetos.

Minha ideia inicial era criar um formulário simples no qual um gerente ou administrador pudesse definir um número de telefone personalizado, e esse número tentasse então ligar para o sistema telefônico. Se o número se conectar com sucesso ao sistema telefônico, nenhuma ação é necessária. Se a conexão falhar, algumas soluções possíveis são executadas automaticamente e, caso elas não funcionem, o plano alternativo é notificar o engenheiro sobre o problema para uma investigação mais aprofundada.

Phone number tree

É isso que vamos criar hoje. Vou mostrar a vocês como criar um aplicativo usando PHP e a Voice API da Nexmo. Para este tutorial, vou partir do princípio de que vocês têm pelo menos alguma experiência com PHP. Então, vamos começar!

Criação do aplicativo

Antes de escrevermos qualquer código, precisamos configurar um Aplicativo de Voice. O Aplicativo de Voice cuida da segurança e dos webhooks de URL.

Para o que estamos fazendo, precisaremos de um nome de aplicativo, uma URL de evento e gerar um par de chaves pública/privada.

O nome do aplicativo não será mencionado em nenhuma parte do nosso código; ele serve exclusivamente para fins de gerenciamento e organização dentro do painel do Nexmo. Sugiro nomear o aplicativo como “Phone System Debugger”.

A URL do evento será muito importante mais adiante. Ela enviará à nossa aplicação uma solicitação de status a cada etapa de uma chamada. Por enquanto, pode ser apenas uma URL provisória; voltaremos a essa opção mais tarde.

A chave pública e a chave privada serão usadas para nos proporcionar acesso seguro à API da Nexmo; pense nelas como um passaporte digital. Precisaremos baixar a chave privada e armazená-la em nosso aplicativo para que seja utilizada posteriormente pela API da Nexmo.

Depois de inserir todos esses dados e salvar a inscrição, receberemos um ID de inscrição e uma chave de API. Também precisaremos desses dados ao desenvolver nossa aplicação web.

O Cliente Nexmo

Uma das vantagens de usar PHP é que a Nexmo desenvolveu seu próprio cliente de terceiros, capaz de gerenciar a interação entre nosso aplicativo e a Nexmo. Isso reduzirá nossa carga de trabalho e poderá ser usado posteriormente para abstrair toda a nossa lógica relacionada à Nexmo em um único serviço pequeno.

Vamos instalar esse cliente como uma dependência usando Composer. O Composer é uma ferramenta para gerenciar dependências de terceiros em seu projeto.

Para usar o cliente Nexmo, precisaremos inserir várias credenciais no cliente. Essas credenciais são:

• Chave da API

• Segredo da API

• Chave de aplicação

• Localização do arquivo da chave privada

Felizmente, já temos essas credenciais, pois as geramos quando criamos nosso aplicativo de Voice.

For the purpose of a quick demonstration, we are just going to implement the client into an `index.php` script, with the main purpose of just sending a test call to ourselves. We will later expand on what we learn here.
 
<?php

use Nexmo\Client;

require_once 'vendor/autoload.php';

$basic = new Nexmo\Client\Credentials\Basic(
   'API_KEY',
   'API_SECRET'
);

$keypair = new Nexmo\Client\Credentials\Keypair(
 file_get_contents('PRIVATE_KEY_PATH'),
 'APPLICATION_ID'
);

$container = new Nexmo\Client\Credentials\Container([$basic, $keypair]);

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

$client->calls()->create([
   'to' => [[
       'type' => 'phone',
       'number' => 'YOUR_PHONE_NUMBER',
   ]],
   'from' => [
       'type' => 'phone',
       'number' => '447418347739',
   ],
   'ncco' => [
       [
           'action' => 'talk',
           'text' => 'Hello world',
       ]
   ]
]);
?>

Então, o que fizemos no exemplo acima foi passar nossas credenciais para duas classes distintas: a Classe de Credenciais Básicas, que contém os detalhes gerais da sua conta Nexmo, e as Credenciais do Par de Chaves, que contêm os detalhes do nosso aplicativo de voz.

Sua chave e seu segredo da API podem ser encontrados na seção ‘Introdução" na sua conta Nexmo. O ID do aplicativo foi gerado quando criamos nosso aplicativo de voz, assim como o conteúdo da nossa chave privada, e pode ser baixado na página de gerenciamento de aplicativos.

Essas duas classes de credenciais são então passadas para a classe do contêiner de credenciais como uma matriz, e o contêiner recém-instanciado é passado para o Cliente. Agora podemos utilizar plenamente a Voice API.

Em seguida, criamos uma solicitação de chamada em um array, indicando para quem queremos ligar, de quem é a chamada e o que vamos dizer ao destinatário, utilizando o objeto NCCO.

Agora que adicionamos o Nexmo Client e criamos um exemplo simples, você já deve ter uma ideia do quanto essa ferramenta pode ser poderosa.

Para o que estamos fazendo, não vou abordar o NCCO, mas é uma ferramenta realmente poderosa. Recomendo vivamente que você leia a documentação e experimentar um pouco; isso vai realmente revelar as possibilidades do que você pode alcançar com a Voice API.

Agora vamos expandir o que criamos aqui para atender aos critérios que apresentei anteriormente. Pulando algumas etapas de configuração, vou escrever os exemplos a seguir como se estivesse usando um framework; vou mantê-los bastante abstratos, então, por favor, use qualquer framework que preferir. Pessoalmente, recomendo usar o Symfony ou o Slim para o que estamos fazendo aqui. Precisamos apenas ter acesso a um roteador para escutar as solicitações da API.

<?php

namespace App\Service;

use Nexmo\Client;

class NexmoService
{
    /** @var Client */
    private $client;

    public function __construct(Client $client)
    {
        $this->client = $client;
    }

    public function makeCall(string $message, string $fromNumber)
    {
        $this->client->calls()->create([
            'to' => [[
                'type' => 'phone',
                'number' => $_ENV['DEFAULT_RECEIVER_NUMBER'],
            ]],
            'from' => [
                'type' => 'phone',
                'number' => $fromNumber,
            ],
            'ncco' => [
                [
                    'action' => 'talk',
                    'text' => $message,
                ]
            ]
        ]);
    }
}

Então, o que fiz aqui foi abstrair o que fizemos em nosso script simples e transformá-lo em uma classe de serviço reutilizável. Agora, vamos chamar essa classe em nosso controlador com uma mensagem e um número de telefone, que o usuário irá inserir em um formulário.

O que ainda preciso abordar é como vamos determinar o estado atual do nosso sistema telefônico a partir de chamadas feitas pelo Nexmo, e é aí que entra a URL de evento do Nexmo.

O webhook de evento é enviado após cada evento durante uma chamada. O que faremos em nosso aplicativo é reagir com base no status atual da chamada. O evento ao qual queremos reagir é “failed” e, por enquanto, ignoraremos todos os outros status.

Então, o que vamos fazer é criar um controlador que será chamado quando um webhook de evento for enviado; ele verificará o status desse evento. Se o status for “falha”, simplesmente exibiremos um alerta para o usuário.

Primeiro, precisamos de uma maneira de fazer com que o Nexmo realmente envie o evento para nosso aplicativo enquanto ainda estamos desenvolvendo localmente. Recomendo usar uma ferramenta chamada Ngrok. O Ngrok é uma ferramenta gratuita que permite abrir um número de porta para um endereço da web acessível publicamente.

Ngrok Example

Configurei o Ngrok para redirecionar minha porta 8080 e atualizei meu aplicativo para usar o endereço do Ngrok.

Ngrok url

Por fim, vamos criar uma função para obter os dados da nossa solicitação e verificar o status do evento.

Esse exemplo de código não é muito empolgante, então o que vamos fazer agora é adicionar a funcionalidade de enviar um SMS para nós mesmos quando o webhook do Event retornar o status “falha”.

Para isso, podemos usar o Nexmo Client já existente para configurar e enviar facilmente um SMS para o nosso número de celular. Essa adição é muito fácil de fazer; portanto, o que faremos é ampliar nosso serviço Nexmo para incluir a funcionalidade de SMS.

<?php

namespace App\Service;

use Nexmo\Client;

class NexmoService
{
    /** @var Client */
    private $client;

    public function __construct(Client $client)
    {
        $this->client = $client;
    }

    public function makeCall(string $message, string $fromNumber)
    {
        $this->client->calls()->create([
            'to' => [[
                'type' => 'phone',
                'number' => $_ENV['DEFAULT_RECEIVER_NUMBER'],
            ]],
            'from' => [
                'type' => 'phone',
                'number' => $fromNumber,
            ],
            'ncco' => [
                [
                    'action' => 'talk',
                    'text' => $message,
                ]
            ]
        ]);
    }
    
    public function sendSMS(string $message)
    {
       $this->client->message()->send([
           'to' => $_ENV['MOBILE_NUMBER'],
           'from' => 'Phone Debugger',
           'text' => $message
       ]);
    }
}

Com oito linhas a mais, já conseguimos adicionar facilmente a funcionalidade de enviar mensagens SMS para nosso celular. Tudo o que fizemos foi passar uma matriz com o número para o qual queremos ligar, o remetente da mensagem e o texto que queremos enviar. Observe que nosso número de remetente é apenas uma string; isso é compatível com a funcionalidade de mensagens da Nexmo.

Existe outra maneira de adicionar suporte a SMS ao nosso aplicativo. Isso é feito por meio da Messages API. Atualmente, essa API não é compatível com o cliente Nexmo, mas traz os recursos do WhatsApp, do Facebook Messenger e do Viber. Isso não é necessário para nosso aplicativo; no entanto, recomendo que você explore a Messages API caso esteja procurando uma maneira de expandir seu aplicativo.

/**
* Route: api/event-webhook
*/
public function postEvent(Request $request)
{
   //Get data as an array
   $data = $request->getContent();

   if (isset($data['status']) && $data['status'] === 'failed') {
       $this->nexmoService->sendSMSMessage('Phone System is down!!!');
   }
}

Por fim, acabei de adicionar uma chamada à nova função SMS em nossa classe controladora, para ser executada quando o Webhook de evento retornar um status de falha. E pronto! Temos um verificador simples do status do telefone.

Para recapitular o que conseguimos: criamos um aplicativo que recebe um número de telefone, tenta ligar para esse número e, com base no resultado da ligação, avisa alguém caso a ligação não seja bem-sucedida.

Criei um repositório no GitHub com tudo o que abordamos neste artigo. Portanto, se você achou alguma coisa confusa ou está tendo problemas com seu aplicativo, fique à vontade para baixar e experimentar esse exemplo.

No momento, estamos apenas arranhando a superfície do que é possível fazer com essa ferramenta. Entre as possíveis melhorias, está a validação de um número antes de tentar ligar para o sistema, o que pode ser feito com o Number Insight da Nexmo. Você poderia criar uma ligação entre as chamadas telefônicas e seu status, armazená-las em um banco de dados e exibir as chamadas em uma tabela.

Se você quiser se inspirar sobre como pode ampliar essa aplicação, fique à vontade para conferir meu projeto Nexmo Status no GitHub, que foi a primeira versão do depurador para celular. Se tiver alguma dúvida, fique à vontade para deixar um comentário.