Creación de un comprobador del estado del teléfono con Nexmo y PHP

Trabajar en una agencia web plantea muchos retos, porque tenemos que hacer malabarismos con varios clientes. Nuestra atención debe centrarse siempre en esos clientes, para asegurarnos de que se cumplen sus requisitos y de que están satisfechos con el trabajo que estamos haciendo. Por lo tanto, lo que probablemente no queremos son distracciones externas. Esto es lo que ocurría en nuestra oficina casi a diario.

El escenario diario sería el siguiente. Un directivo cogía el teléfono para llamar a un cliente, el teléfono no marcaba, el directivo gritaba por toda la oficina abierta "Los teléfonos no funcionan", lo que era objeto de burla por toda la oficina hacia el ingeniero encargado del sistema telefónico. Éste dejaba de hacer lo que estaba haciendo, se dirigía al teléfono derrotado y volvía a su mesa cinco minutos después de solucionar el problema. De nuevo, esto ocurría casi a diario.

Pero este no era el único caso. Mi situación favorita fue que, en una época, las llamadas de teléfonos que terminaban en 87 no se conectaban a nuestro sistema telefónico.

Después de veintisiete veces, supe que tenía que haber una solución mejor. Aunque cinco minutos no parezcan mucho, la fluidez y la concentración de los ingenieros se veían interrumpidas, lo que obligaba a dedicar otros veinte minutos a retomar el trabajo donde se había dejado, recordar lo que se estaba haciendo y volver a la rutina.

Así que empecé a diseñar.

Mi idea inicial era crear un formulario sencillo en el que un gestor o administrador pudiera establecer un número de teléfono personalizado y ese número intentara llamar al sistema telefónico. Si el número se conecta con éxito al sistema telefónico, no se requiere ninguna acción. Si no se consigue conectar, se automatizan algunas posibles soluciones y, si éstas no funcionan, se notifica el problema al ingeniero para que lo investigue más a fondo.

Phone number tree

Esto es lo que vamos a construir hoy. Voy a mostrarte cómo crear una aplicación usando PHP y el Voice API de Nexmo. Para este tutorial, voy a asumir que tienes al menos algo de experiencia con PHP. Así que, ¡empecemos!

Creación de la aplicación

Antes de que podamos escribir cualquier código, necesitamos configurar una Aplicación de Voz. La Aplicación de Voz gestiona la seguridad y los webhooks URL.

Vonage API Account

To complete this tutorial, you will need a Vonage API account. If you don’t have one already, you can sign up today and start building with free credit. Once you have an account, you can find your API Key and API Secret at the top of the Vonage API Dashboard.

Ready to start building?

Experience seamless connectivity, real-time messaging, and crystal-clear voice and video calls—all at your fingertips.

Para lo que estamos haciendo necesitaremos un Nombre de Aplicación, una URL de Evento, y generar un par de claves Pública/Privada.

El nombre de la aplicación no va a ser referenciada en cualquier lugar de nuestro código, es puramente utilizado para nuestra propia gestión y organización dentro del tablero Nexmo. Sugiero llamar a la aplicación "Depurador del Sistema Telefónico".

La URL de Evento será muy importante más adelante. Esto enviará a nuestra aplicación una solicitud de estado durante cada paso a lo largo de una llamada. Por ahora, esto puede ser sólo un marcador de posición URL y volveremos a esta opción más adelante.

La Clave Pública / Clave Privada se utilizará para darnos acceso seguro a la API Nexmo, piensa en ello como un pasaporte digital. Tendremos que descargar la Clave Privada y almacenarla en nuestra aplicación para su posterior consumo por la API Nexmo.

Una vez introducidos todos estos datos y guardada la aplicación, se nos proporcionará un ID de aplicación y una clave de API. También necesitaremos estos datos cuando creemos nuestra aplicación web.

El cliente Nexmo

Una de las ventajas de utilizar PHP es que Nexmo ha construido su propio cliente de terceros, que puede manejar la interacción entre nuestra aplicación y Nexmo. Esto reducirá nuestra carga de trabajo y se puede utilizar más adelante para abstraer toda nuestra lógica Nexmo en un solo servicio pequeño.

Vamos a instalar este cliente como una dependencia utilizando Compositor. Composer es una herramienta para gestionar dependencias de terceros en tu proyecto.

Para utilizar el cliente Nexmo necesitaremos inyectar varias credenciales en el cliente. Estas credenciales son:

• Clave API

• Secreto API

• Clave de aplicación

• Ubicación del archivo de claves privadas

Afortunadamente, ya disponemos de estas credenciales, ya que las generamos cuando creamos nuestra aplicación 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',
       ]
   ]
]);
?>

Por lo tanto, lo que hemos hecho en el ejemplo anterior es pasar nuestras credenciales a dos clases separadas, la Clase de Credenciales Básicas, que contiene los detalles generales de su cuenta Nexmo y las Credenciales de Par de Claves, que contienen los detalles de nuestra Aplicación Voice.

Puede encontrar su Clave y Secreto API en la página 'Primeros pasos' en tu Account de Nexmo. El ID de la aplicación se generó cuando creamos nuestra aplicación de voz y el contenido de nuestra clave privada, y se puede descargar desde la página de gestión de aplicaciones.

Estas dos clases de credenciales se pasan a la clase contenedora de credenciales como una matriz y el contenedor recién instanciado se pasa al cliente. Ya podemos utilizar la Voice API.

A continuación creamos una solicitud de llamada en un array con a quién queremos llamar, de quién es la llamada y qué le vamos a decir al destinatario utilizando el objeto NCCO.

Ahora que hemos añadido el Cliente Nexmo y creado un ejemplo sencillo, debería tener una idea de lo potente que puede ser esta herramienta.

Para lo que estamos haciendo no voy a explorar la NCCO, pero es una herramienta realmente poderosa. Te aconsejo que leas la documentación y jugar un poco; realmente revelará las posibilidades de lo que puedes lograr con la Voice API.

Ahora vamos a ampliar lo que hemos creado aquí para cumplir con los criterios que expuse anteriormente. Saltando algunas áreas de configuración, voy a escribir los siguientes ejemplos como si estuviera usando un framework, voy a mantenerlo bastante abstracto así que por favor usa cualquier framework que te guste. Personalmente recomiendo usar Symfony o Slim para lo que estamos haciendo aquí. Sólo necesitamos tener acceso a un router para escuchar las peticiones de la 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,
                ]
            ]
        ]);
    }
}

Así que, lo que he hecho aquí es abstraer lo que hicimos en nuestro simple script y empaquetarlo en una clase de servicio reutilizable. Ahora llamaremos a esa clase en nuestro controlador con un mensaje y un número de teléfono, que el usuario introducirá en un formulario.

Lo que todavía tengo que cubrir es cómo vamos a decir el estado actual de nuestro sistema telefónico de llamar a través de Nexmo, que es donde Nexmo Url de eventos entra en juego.

La página webhook de evento se envía después de cada evento durante una llamada. Lo que vamos a hacer en nuestra aplicación es reaccionar basándonos en el estado actual de la llamada. El evento al que queremos reaccionar es 'failed' e ignoraremos todos los demás estados por el momento.

Por lo tanto, lo que vamos a hacer es crear un controlador que será llamado cuando un evento webhook es enviado, esto comprobará el estado de ese evento. Si el estado es "fallido", entonces sólo se hará eco de una alerta al usuario.

En primer lugar, necesitamos una manera para que Nexmo realmente envíe el evento a nuestra aplicación mientras todavía estamos desarrollando localmente. Recomiendo usar una herramienta llamada Ngrok. Ngrok es una herramienta gratuita para abrir un número de puerto a la dirección web de acceso público.

Ngrok Example

He configurado Ngrok para que reenvíe mi puerto 8080 y he actualizado mi aplicación para que utilice la dirección de Ngrok.

Ngrok url

Por último, vamos a crear una función para obtener los datos de nuestra solicitud, comprobar el estado del evento.

Este ejemplo de código no es muy emocionante, así que lo que haremos ahora es añadir la posibilidad de enviarnos un SMS cuando el webhook de eventos devuelva el estado de 'fallido'.

Para ello podemos utilizar el Cliente Nexmo existente para configurar y enviar fácilmente un SMS a nuestro número de móvil. Esta adición es muy fácil de hacer, así que lo que vamos a hacer es ampliar nuestro servicio Nexmo para incluir la funcionalidad 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
       ]);
    }
}

Con ocho líneas adicionales, hemos añadido fácilmente la funcionalidad de enviar mensajes SMS a nuestro teléfono móvil. Todo lo que hemos hecho es pasar un array con el número al que queremos llamar, la persona de la que proviene y el mensaje que queremos enviar. Observe cómo nuestro número de origen es sólo una cadena; esto es soportado por la funcionalidad de mensajería de Nexmo.

Hay otra manera de añadir soporte SMS a nuestra aplicación. Esto es a través de la API de mensajería, en la actualidad, esta API no es compatible con el cliente Nexmo, pero trae las adiciones de WhatsApp, Facebook Messenger y Viber. Esto no es necesario para nuestra aplicación, sin embargo, recomiendo investigar la API de mensajería si usted está buscando una manera de ampliar su aplicación.

/**
* 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 último, acabo de añadir una llamada a la nueva función SMS en nuestra clase de controlador para que sea llamada cuando el Webhook de eventos devuelva un estado fallido. Y ¡voilá! Tenemos un sencillo comprobador del estado del teléfono.

Para recapitular lo que hemos conseguido: Hemos creado una aplicación que toma un número de teléfono, intenta llamar a ese número y, basándose en el estado de esa llamada, avisa a alguien si la llamada falla.

He creado un repositorio de Github con todo lo que hemos cubierto en este artículo. Así que si usted ha encontrado algo confuso o tener problemas con su aplicación, por favor no dude en descargar y jugar con ese ejemplo.

Ahora sólo estamos arañando la superficie de lo que se puede hacer con esta herramienta. Posibles mejoras podrían ser la validación de un número antes de intentar llamar al sistema, lo que se puede lograr con Number Insight de Nexmo. Se podría añadir un enlace entre las llamadas telefónicas y su estado y almacenarlas en una base de datos y mostrar las llamadas en una tabla.

Si quieres un poco de inspiración sobre cómo puedes ampliar esta aplicación, no dudes en echar un vistazo a mi proyecto proyecto Nexmo Status en GitHubque fue la primera iteración del depurador de teléfono. Si usted tiene alguna pregunta por favor no dude en dejar un comentario.