Llamadas de voz de texto a voz con PHP

Durante años, hacer y recibir llamadas telefónicas en tu código era difícil (y normalmente implicaba escribir algo de Java y conectar un viejo teléfono a tu portátil para que sirviera de pasarela). Afortunadamente, ya no es tan difícil gracias a servicios como Vonage (antes Nexmo).

Las llamadas de voz son un excelente método de comunicación, ya que son mucho más inmediatas que el correo electrónico o los SMS. Si necesitas hacer llegar un mensaje a alguien con urgencia, lo mejor es llamar por teléfono; un teléfono que suena es difícil de ignorar.

En este post, usted va a construir una pequeña aplicación que se puede utilizar para activar una llamada telefónica saliente utilizando nuestro cliente PHP.

El código completo de esta entrada está disponible en nuestra sección de bloques de construcción PHP en Github.

Requisitos previos

Usted necesitará PHP instalado antes de trabajar a través de este post. Estoy ejecutando PHP 7.4, pero el código aquí debería funcionar en PHP 5.6 y superiores. También necesitarás Compositor disponible para instalar el cliente Nexmo PHP.

A continuación, necesitará NPM para instalar el directorio Nexmo CLI.

Necesitarás una manera de exponer al público la aplicación que estás desarrollando para que Vonage pueda comunicarse con ella. Puedes hacerlo utilizando una herramienta como ngrok. Si no estás familiarizado con la herramienta, hay una fantástica introducción a ngrok disponible en el blog de Vonage. Por ahora, abre un terminal y ejecuta ngrok http 8000. Toma nota de tu ngrok ya que necesitarás reemplazar https://example.com cuando configures tu aplicación de Vonage.

Por último, si aún no tienes una cuenta de Vonage Voice tendrás que crear una aplicación y comprar y vincular un número. La manera más fácil de hacerlo es usando la herramienta Nexmo CLI. Esta es la versión abreviada:

• Instala la herramienta CLI de Vonage ejecutando npm install -g vonage-cli

• Autentícate con tu CLI de Vonage ejecutando vonage config:set --apiKey=<api_key> --apiSecret=<api_secret>. Reemplazando api_key y api_secret con tus credenciales que se encuentran en tu Panel de control

• Cree una aplicación, sustituyendo voice-answer-url y voice-event-url por sus endpoints ejecutando vonage apps:create "Test Application 1" --vbc --voice_answer_url=http://example.com/webhooks/answer. Anote el ID de la aplicación que devuelve

• Encuentre un número adquirible mediante búsqueda: vonage numbers:search US

• Adquiera uno de los números devueltos en la búsqueda ejecutando vonage numbers:buy <number>. Anote el número adquirido.

• Por último, vincule el número a su aplicación ejecutando vonage apps:link <application_id> --number=<number>

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.

Cree su espacio de trabajo

Vamos a configurar el espacio de trabajo para que puedas empezar a desarrollar tu aplicación. Este tutorial utiliza el marco de trabajo delgado para recibir eventos de llamadas de Vonage y devolver instrucciones sobre cómo se deben manejar las llamadas. Utiliza Composer para arrancar un proyecto con Slim ejecutando los siguientes comandos:

Estos comandos crearán una carpeta llamada vonage-calls, cambiarán el directorio por el recién creado e instalarán Slim en tu nuevo proyecto. Copie el archivo private.key que guardó al crear una aplicación en esta carpeta. Debe estar al mismo nivel que composer.json.

A continuación, debes iniciar el servidor PHP local para poder realizar llamadas HTTP a tu aplicación. Para ello, abre un nuevo terminal y ejecuta php -t public -S localhost:8000. Tu aplicación está ahora escuchando en el puerto 8000 de tu máquina local y está disponible a través de Internet gracias al comando ngrok que ejecutaste anteriormente.

En este punto, tienes una aplicación Slim arrancada, escuchando y expuesta a Internet. Esta configuración es todo lo que necesitas hacer para comenzar a servir respuestas a Vonage para indicarle cómo manejar las llamadas telefónicas.

Creación de su OCN

Las llamadas telefónicas de Vonage se controlan mediante objetos de control de llamadas de Nexmo (o NCCO). Un NCCO define una lista de acciones que el sistema de Vonage debe seguir cuando se gestiona una llamada. Hay muchas acciones diferentes disponibles, como:

• Conectar una llamada a otro número con connect.

• Grabar una llamada con record.

• Crear una multiconferencia con conversation.

• Generar un mensaje de texto a voz con talk.

• Además de otros: consulte nuestra referencia NCCO para obtener una lista completa.

Para empezar, vas a generar una OCN simple:

[
  {
    "action": "talk",
    "voiceName": "Amy",
    "text": "The amount of visible light from a lamp is measured in lumens"
  }
]

Cree un archivo llamado index.php con el siguiente contenido. El siguiente ejemplo de código arranca la aplicación Slim, define un manejador y luego ordena a Slim que utilice este manejador cada vez que reciba una GET solicitud a /webhook/answer:

<?php

use \Psr\Http\Message\ServerRequestInterface as Request;
use \Psr\Http\Message\ResponseInterface as Response;
use Slim\Factory\AppFactory;
require __DIR__ . '/vendor/autoload.php';

$app = AppFactory::create();

$app->get('/webhook/answer', function (Request $request, Response $response) {
    $ncco = [
        [
            'action' => 'talk',
            'voiceName' => 'Amy',
            'text' => 'The amount of visible light from a lamp is measured in lumens'
        ]
    ];

    $response->getBody()->write(json_encode($ncco));

    return $response
            ->withHeader('Content-Type', 'application/json');
});

$app->run();

A medida que Vonage realiza una GET solicitud a su answer_urlagrega un controlador que coincida con estas solicitudes ($router->get('/webhook/answer')) y devuelve una respuesta JSON (return response()->json()).

Siempre y cuando devuelvas JSON en el formato correcto, Vonage sabrá cómo manejar la llamada. ¡Eso es todo! Guarda tus cambios y luego llama al número que compraste para escuchar tu mensaje de texto a voz.

Hacer una llamada saliente

Has empezado muy bien, pero nuestro objetivo era hacer una llamada saliente, no sólo responder a las llamadas entrantes. Afortunadamente para ti, ya has hecho la mayor parte del trabajo. Cuando realizas una llamada saliente, Vonage aún realiza una llamada a tu answer_url para averiguar cómo manejar la llamada.

Para activar una llamada saliente, debes realizar una POST solicitud a la API de Vonage que contenga to, from y answer_url junto con cierta información de autenticación.

Mientras que usted podría construir esa llamada a mano, el cliente PHP de Nexmo lo hace extremadamente fácil. Así que vamos a instalarlo con Composer. Ejecute el siguiente comando en el mismo directorio que su composer.json:

Una vez que tengas instalado el cliente Nexmo, puedes agregar un nuevo punto final al que llamarás para activar una nueva llamada saliente. Necesitarás el ID de la aplicación y la clave privada que guardaste anteriormente para autenticar tus llamadas a la API, y luego debemos realizar una llamada a la Voice API de Vonage. Deberás copiar private.key en la misma carpeta que tu composer.json y reemplazar APPLICATION_ID y YOUR_VONAGE_NUMBER con tus valores. (No olvide indicar su propia ngrok en lugar de example.com )

$app->get('/makeCall/{number}', function (Request $request, Response $response, array $args) {
    $keypair = new \Nexmo\Client\Credentials\Keypair(
        file_get_contents(__DIR__ . '/private.key'),
        'APPLICATION_ID'
    );

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

    $client->calls()->create([
        'to' => [[
            'type' => 'phone',
            'number' => $args['number']
        ]],
        'from' => [
            'type' => 'phone',
            'number' => 'YOUR_VONAGE_NUMBER'
        ],
        'answer_url' => ['https://afb8ad306a73.ngrok.io/webhook/answer']
    ]);

    return $response
        ->withHeader('Content-Type', 'application/json')
        ->withStatus(200);
});

Una vez hecho esto, haga una GET solicitud a /makeCall/ para activar una llamada saliente de texto a voz a través de Nexmo.

OCN dinámicas

Has conseguido lo que te habías propuesto, pero es un poco aburrido. Emite el mismo mensaje cada vez que hace una llamada. Para hacerlo dinámico, podrías leer en voz alta la hora actual, pero aquí tienes una idea un poco más interesante. Cada vez que hagas una llamada saliente, harás una petición a la Base de Datos Chuck Norris y leer la respuesta en su llamada.

Para ello, utilizará una biblioteca HTTP ligera llamada Guzzle. Para usar Guzzle, necesitas instalarlo usando Composer. Ejecuta lo siguiente en el mismo directorio que tu composer.json:

Una vez que tengas Guzzle instalado, tienes que hacer una petición a la base de datos de Chuck Norris y utilizar la respuesta para rellenar tu NCCO. Vas a limitar la búsqueda a chistes de empollones por defecto. Añade lo siguiente al principio de tu /answer handler:

$client = new GuzzleHttp\Client();
$apiResponse = json_decode($client->get('http://api.icndb.com/jokes/random?limitTo=[nerdy]')->getBody());

Esto devolverá un chiste aleatorio de la categoría nerd. El siguiente paso es actualizar la NCCO para utilizar el valor de $apiResponse:

$ncco = [
    [
        'action' => 'talk',
        'voiceName' => 'Amy',
        'text' => $apiResponse->value->joke
    ]
];

Ahora, cada vez que Vonage haga una solicitud a tu answer_url buscará un chiste al azar de la base de datos de Chuck Norris y lo utilizará como respuesta de texto a voz. Puedes probarlo ahora realizando una llamada telefónica a tu número de Vonage o activando una llamada saliente a través del punto final de makeCall punto final.

Enhorabuena. Acabas de crear un sistema de llamadas de voz de texto a voz que puede gestionar tanto llamadas entrantes como salientes. Además, puedes personalizar la respuesta en función de quién llama, la hora del día o cualquier otra cosa que se te ocurra.

¿Y ahora qué?

¿Y ahora qué? Puede convertir su aplicación en un sistema de alerta crítica por voz mediante un bucle a través de una lista de contactos para emitir llamadas y hacer que los destinatarios pulsen un número para confirmar la recepción de sus mensajes.