Manejar la entrada de teclado (DTMF) con PHP

En este tutorial, vamos a repasar todo lo que necesita saber para configurar una aplicación PHP que pueda recibir llamadas entrantes y capturar la entrada del usuario introducida a través del teclado.

Siguiendo este tutorial obtendrá una aplicación sencilla que puede ampliarse para incluir elementos interactivos más complejos y que le permitirá empezar a crear menús interactivos para sus interlocutores.

El código de este tutorial se encuentra en GitHub.

Requisitos previos

TL;DR - Necesitarás las siguientes cosas:

• Un número de teléfono que no esté ya asociado a otra aplicación

• PHP (>5.6), Composer y el framework Slim

• ngrok

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.

This tutorial also uses a virtual phone number. To purchase one, go to Numbers > Buy Numbers and search for one that meets your needs.

Ready to start building?

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

Esta es la versión larga:

Si quieres seguirnos, necesitarás una Account Nexmo para empezar, así que regístrate ahora si aún no la tienes.

Recibir una llamada telefónica con Nexmo se cobra a 0,0045 €/min y tendrás que alquilar un número para que la gente llame. Esto lo veremos más adelante.

El código de ejemplo utiliza el marco Slim para gestionar las peticiones. Lo hemos elegido por su simplicidad y legibilidad pero, si estás familiarizado con PHP y te gustaría manejar esto de otra manera, eres bienvenido a usar algo diferente. Necesitarás instalar Slim usando Compositor así que asegúrate de tenerlo instalado también.

Se espera que el código que creará funcione con cualquier versión de PHP 5.6 o superior.

Nuestra forma recomendada de trabajar con Nexmo, desde el punto de vista de la administración, es utilizar nuestra herramienta de línea de comandos, Nexmo-CLI.

Para que el código de nuestra máquina local sea accesible al mundo exterior, vamos a utilizar ngrokasí que asegúrate de tenerlo instalado también.

Recepción de la llamada entrante

Cuando Nexmo recibe una llamada en un número que ha alquilado, se realiza una solicitud HTTP a una URL (un "webhook", que usted especifica) que contiene toda la información necesaria para recibir y responder a la llamada. Esto se denomina comúnmente URL de respuesta.

También recogeremos datos DTMF de nuestros interlocutores. DTMF significa Multifrecuencia de doble tono y, en el caso de este tutorial, se produce cuando un usuario pulsa un número en su teclado.

Cada vez que se recoge una entrada DTMF del usuario, ésta se envía a una URL diferente en tu aplicación que también tendremos que especificar.

A continuación, empezaremos a escribir el código necesario para gestionar estas peticiones.

Para instalar Slim usando Composer ejecute el siguiente comando dentro de la carpeta del proyecto en su terminal:

A continuación, en su carpeta principal, cree un nuevo archivo llamado index.php y añádele el siguiente código:

<?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();

Con este código estamos configurando una nueva URL en nuestra aplicación, webhooks/answerque responderá a cualquier llamada entrante a tu número de teléfono con las instrucciones proporcionadas en la matriz $ncco matriz.

El $ncco realizará estos pasos una vez contestada la llamada:

1. Lea en voz alta el texto "Introduzca un dígito".

2. Capturar el dígito introducido por el llamante

3. Pasa la entrada capturada a la ruta que gestiona la entrada, /webhooks/dtmf

Manejar la entrada del usuario

Vamos a añadir el código para manejar DTMF entrante en index.php:

Después del código que hemos introducido anteriormente, y antes de $app->run(); añada lo siguiente:

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

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

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

La función de esta ruta realizará los siguientes pasos:

1. Recibir la entrada de /webhooks/answer

2. Analiza el cuerpo de la solicitud en una variable, $params

3. Crea un nuevo $ncco que responda a la persona que llama y le diga qué número ha pulsado.

Como referencia, el archivo index.php debe ser exactamente como éste.

Ahora, ya estás preparado y listo para ejecutar el código, puedes hacerlo introduciendo el siguiente comando en tu terminal:

Esto iniciará un servidor y enrutará cualquier tráfico a http://localhost:3000 a través de su archivo index.php archivo.

Exponga su aplicación con ngrok

Para permitir que Nexmo haga peticiones a tu aplicación, necesitas exponer al mundo el código que se ejecuta en tu máquina local.

ngrok es nuestra herramienta preferida para esto, y hemos proporcionado una gran introducción a la herramienta que puedes leer para ponerte al día si no la has usado antes.

Una vez que tengas ngrok instalado, ejecuta ngrok http 3000 para exponer tu aplicación a Internet. Tendrás que tomar nota de la ngrok URL generada ya que tendremos que proporcionársela a Nexmo en el siguiente paso (será algo parecido a http://45hfh5.ngrok.io).

Comprar un número y crear una aplicación

Con el código terminado y nuestra aplicación disponible para el mundo, ahora tenemos que conseguir un número de teléfono y vincular este código, que se ejecutará localmente, a él.

Vamos a empezar por la compra de un número a través de la CLI Nexmo:

Si lo deseas, puedes utilizar un código de país diferente. Anote el número que adquiera, ya que lo necesitaremos para el siguiente paso.

Ahora tenemos que crear una aplicación Nexmo, que es un contenedor para todos los ajustes necesarios para su aplicación. En este caso, tenemos que decirle a Nexmo a qué URL hacer una solicitud cuando se recibe una llamada entrante (el campo answer_url), y dónde enviar cualquier información de eventos sobre la llamada (el campo event_urlPuedes encontrar más información sobre eventos en la sección Flujo de llamadas ).

Utiliza la CLI de Nexmo para crear tu aplicación asegurándote de sustituir <your_ngrok_url> por tu propia URL generada que ngrok te dio antes:

La respuesta que recibirás contendrá una enorme salida de clave privada y, sobre ella, un ID de aplicación. Puedes ignorar la clave privada, ya que no es necesaria para gestionar las llamadas entrantes.

Anota el identificador de la solicitud (que tiene este aspecto: e7a25242-77a1-42cd-a32e-09febcb375f4) y luego vincúlalo a tu nuevo número:

Eso es todo lo que necesitas para asociar el código anterior a tu aplicación Nexmo y a tu número. Puedes probarlo marcando el número que has comprado y siguiendo los pasos que se te indican mágicamente al otro lado de la línea.

Conclusión

En sólo treinta líneas de PHP, ahora tienes una aplicación que puede recibir una llamada entrante y recoger la entrada DTMF de la persona que llama. ¿Cómo podrías ampliar esto a partir de aquí?

Si desea obtener más información sobre las posibilidades que ofrecen las llamadas de voz entrantes y sobre cómo hacerlas más complejas añadiendo funciones como la grabación de audio, puede obtener más información sobre el funcionamiento de las NCCO en la sección Referencia de NCCO.

Como siempre, si tienes alguna pregunta sobre este post no dudes en enviar un correo electrónico a devrel@nexmo.com o únete al canal Slack de la comunidad Nexmodonde estamos esperando y listos para ayudar.