Recibir una llamada entrante de Voice con PHP

En nuestra última entrada del blog sobre PHP y Voice, explicamos cómo realizar una llamada de voz saliente usando Text-To-Speech. En este post, vamos a cambiar de dirección y escribir una aplicación que maneja las llamadas de voz entrantes y devuelve una respuesta dinámica.

El código fuente de esta entrada de blog está disponible en Github.

Requisitos previos

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.

Usted necesitará PHP instalado antes de trabajar a través de este post. Estoy ejecutando PHP 7.2, pero el código aquí debería funcionar en PHP 5.6 y superiores. También necesitarás Compositor para descargar nuestras dependencias.

Por último, necesitarás la CLI de Vonage instalada. La usaremos para configurar nuestra Account de Vonage y comprar un número de teléfono.

Recibir una llamada telefónica con PHP

Antes de entrar en detalles sobre cómo funciona todo, comenzaremos creando una aplicación PHP para manejar las llamadas de voz entrantes. Cuando se reciba una llamada de voz, Vonage hará una solicitud a tu aplicación para saber cómo responder a esa llamada.

Vamos a utilizar el Slim framework para gestionar las peticiones entrantes, así que vamos a instalarlo ahora con composer:

Una vez hecho esto, cree un nuevo archivo llamado index.php con el siguiente contenido. Esto creará una nueva aplicación Slim y registrará un único endpoint (/webhook/answer) que acepta una GET con un parámetro from y devuelve el valor from en el cuerpo.

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

Guarda este archivo y abre una nueva ventana de terminal. Iniciemos el servidor PHP incorporado y sirvamos nuestra aplicación en el puerto 8000.

Si visita http://localhost:8000/webhook/answer?from=14155550100verá el número from devuelto en el cuerpo de la respuesta.

Este es un gran comienzo, pero Vonage no sabrá qué hacer si sólo respondemos con el número de teléfono de la persona que llama. Para indicarle a Vonage cómo manejar la llamada, debemos devolver un mensaje NCCO.

Para simplificar las cosas, utilizaremos la tecnología de texto a voz para leer el número de teléfono de la persona que llama, dígito a dígito. Primero dividimos el número en una serie de caracteres y luego los unimos con espacios:

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

A continuación, definimos una NCCO que utiliza la acción talk para leer estos caracteres:

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

Finalmente, devolvemos esta OCNC en lugar de $params['from']:

return $response->withJson($ncco);

Cuando lo juntamos todo, index.php se parece a lo siguiente:

<?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 de nuevo y verá que se le devuelve lo siguiente:

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

Enhorabuena. Acabas de escribir una aplicación que recibe una llamada telefónica entrante y responde con contenido dinámico. Puedes personalizar tu respuesta usando cualquiera de los parámetros que Vonage proporciona, incluyendo to, from y conversation_uuid.

Exponga su aplicación con ngrok

Hemos creado una aplicación que responde como esperábamos, pero hay un gran problema por el momento. Se supone que Vonage le hace una solicitud cuando se recibe una llamada, ¡pero se está ejecutando en nuestra máquina local!

Pero no se preocupe, ngrok puede salvarle el día. Si no estás familiarizado con ngrok, hay una fantástica introducción a ngrok disponible en el blog de Vonage.

Una vez que tengas ngrok instalado, ejecuta ngrok http 8000 para exponer tu aplicación a Internet. Tendrás que tomar nota de la ngrok URL generada, ya que tendremos que proporcionársela a Vonage (será algo parecido a http://abc123.ngrok.io).

Configura tu Account de Vonage

Una vez que tu aplicación esté expuesta a Internet, lo último que debes hacer es conectarla a un número de teléfono de Vonage. Comencemos por comprar un número de teléfono usando la CLI de Vonage. Primero, busca un número:

A continuación, compre uno de los Numbers que aparecen como disponibles:

El siguiente paso es crear una aplicación de Vonage, que es un contenedor para todas las configuraciones necesarias para tu aplicación. En este caso, debemos indicarle a Vonage a qué URL debe realizar una solicitud cuando se recibe una llamada (answer_url), y dónde enviar cualquier información de eventos sobre la llamada (event_url).

Podemos utilizar el Nexmo CLI para crear una aplicación, asegurándose de sustituir http://abc123.ngrok.io por tu propia URL generada. Proporcionamos un nombre, luego un answer_url y event_url para la aplicación:

Anote el ID de su solicitud (será similar a aaaaaaaa-bbbb-cccc-dddd-0123456789ab) y siga leyendo.

Lo último que debes hacer es vincular el número que compraste a la aplicación que acabas de crear. Esto le indicará a Vonage que cuando se reciba una llamada, debe realizar una GET solicitud a la aplicación de answer_url para saber cómo proceder con la llamada.

Una vez más, podemos utilizar la CLI de Nexmo para hacer esto, reemplazando el número de teléfono de ejemplo y el ID de la aplicación por los suyos propios:

Eso es todo lo que necesitamos hacer para que Vonage asocie nuestra aplicación PHP a una llamada telefónica entrante. Pruébalo ahora llamando al número de teléfono que compraste.

Conclusión

Juntos acabamos de crear una aplicación capaz de recibir una llamada telefónica y generar dinámicamente una respuesta en sólo 22 líneas de código.

Si desea obtener más información sobre las llamadas de voz con PHP y Vonage, puede encontrar bloques de construcción de ejemplo en Nexmo Developer. Alternativamente, si quieres hacer tu respuesta de llamada entrante más compleja (por ejemplo, grabar el audio de la persona que llama) puedes aprender más sobre NCCOs en la Referencia 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.