Crea una conferencia telefónica con PHP y la Voice API de Vonage

Introducción

En este tutorial, aprenderás a crear una aplicación de llamadas en conferencia usando PHP y la Voice API de Vonage. Al final, tendrás un número de teléfono al que podrán llamar varios participantes para unirse a la misma conversación en directo.

Configuraremos una aplicación de Vonage, gestionaremos las llamadas entrantes con un objeto de control de llamadas (NCCO) y devolveremos respuestas dinámicas desde un simple punto final PHP. Este proyecto es un punto de partida práctico para crear líneas de reuniones de equipo, líneas directas para eventos o experiencias de voz colaborativas.

El código fuente completo de este tutorial está disponible en el repositorio GitHub de la comunidad de Vonagepara que puedas seguirlo o adaptarlo a tu propio caso de uso.

Requisitos previos

• PHP8.3+

• Una cuenta API de Vonage

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.

Responder a una llamada entrante con PHP

En este ejemplo, los usuarios llamarán a un número virtual de Vonage y el código de tu aplicación responderá a esa llamada entrante. Vonage hace esto utilizando un objeto de control de llamadas o NCCO.

En primer lugar, tendremos un saludo hablado de texto a voz (TTS) y, a continuación, el usuario se unirá a la multiconferencia.

Para ello, añadiremos un archivo answer.php al directorio public/ (nuestra raíz web) y haremos que devuelva la NCCO. El NCCO es JSON, por lo que el PHP también necesita incluir un encabezado apropiado Content-Type apropiado:

<?php

$ncco = [
    [
        "action" => "talk",
        "text" => "Thank you for joining the call today. You will now be added to the conference.",
        "language" => "en-GB",
        "style" => 0,
        "premium" => true
    ],
    [
        "action" => "conversation",
        "name" => "weekly-team-meeting"
    ]
];

header("Content-Type: application/json");
echo json_encode($ncco);

La variable $ncco contiene la OCN que devolverás al servidor de Vonage para indicarle cómo manejar una llamada entrante. Este ejemplo incluye una acción "hablar" que saluda al usuario, seguida de una acción "conversación" que agrega al usuario a la llamada en conferencia. Este código utiliza header() para que PHP envíe la cabecera Content-Type seguido del propio JSON.

Si tiene curiosidad por saber qué más puede hacer con una NCCO, puede consultar la documentación de referencia NCCO en nuestro portal para desarrolladores.

Servir la respuesta

Llegados a este punto, puedes empezar a probar las partes móviles de la aplicación. Inicie el servidor web PHP desde el directorio public/ directorio:

cd public/
php -S localhost:8080

Comprueba que tu aplicación devuelve correctamente la OCNC cuando realizas una petición a http://localhost:8080/answer.php utilizando tu cliente HTTP favorito (cURL, Postman o incluso tu navegador sería una buena herramienta para utilizar aquí).

Hacer público el código

Para que Vonage notifique a tu aplicación de una llamada entrante, necesita poder alcanzarla, por lo que este código debe estar disponible públicamente. Una opción es implementarlo en un servidor, pero para fines de desarrollo, prefiero usar ngrok para exponer mi entorno de desarrollo local. Una vez que tengas el servidor web funcionando (el mío está en el puerto 8080), ejecuta ngrok así:

ngrok http 8080

Esto te dará un tablero que muestra un enlace a la interfaz web (muy útil, haz clic en él), la URL https de tu túnel (cópiala, la necesitaremos en un momento), y una sección que mostrará las peticiones que llegan cuando haces algunas.

Pruebe su nuevo túnel haciendo una llamada a su aplicación a través de él-puede reemplazar http://localhost:8080 por su URL https ngrok, intente la petición a /answer.php de nuevo.

Establecer un Numbers para llamar

Comprar un número de Vonage

Crear una aplicación de Vonage habilitada para voz

Lo otro que necesitas es una aplicación de Vonage: ésta contiene la configuración de la llamada y puede vincularse a los números que deseas utilizar. Esta separación es muy útil si quieres que números de distintas geografías se unan a la misma multiconferencia.

Las aplicaciones de Vonage utilizan claves públicas/privadas. En este ejemplo, simplemente estás recibiendo una llamada entrante, por lo que no necesitarás la clave privada por ahora. Sin embargo, es una buena práctica guardar el archivo private.key en tu directorio de trabajo, en caso de que decidas construir más funcionalidades sobre este ejemplo.

La creación de la aplicación requiere que le des un nombre y configures algunos puntos finales de webhook importantes:

• La URL de respuesta será el answer.php que ya ha creado.

• Establezca la URL del evento en event.php. Crearemos este archivo en la siguiente sección.

Vincula la aplicación a tu número de Vonage

Con tu aplicación de Vonage creada, tus números virtuales disponibles aparecerán en la parte inferior de la pantalla, incluido el que acabas de comprar en el paso anterior.

Seleccione el número que desea utilizar para este tutorial y, a continuación, haga clic en el botón Vincular junto a él para vincular tu número virtual y tu aplicación de Vonage.

Como resultado, cuando ahora llames a tu número virtual, Vonage buscará instrucciones de flujo de llamadas en la URL que especificaste como URL de respuestay enviará webhooks de eventos a tu URL de eventos.

A continuación, vamos a comprobar que todo lo que hemos hecho hasta ahora funciona. Llama al número y comprueba si oyes el saludo; si es así, pide a otra persona que llame y disfruten de una charla.

Si no funciona la primera vez, no te preocupes. El siguiente paso es construir el manejo de eventos para que puedas ver lo que está pasando-y si hay errores, así es como los verás.

Gestión de eventos de llamada

Para simplificar las cosas, la aplicación espera que su URL de eventos sea/event.php-y si ya has probado esto, habrás visto algunas peticiones fallidas llegando allí.

Para crear un simple manejador de eventos, cree un archivo public/event.php y añada el siguiente código:

<?php

$post_params = json_decode(file_get_contents("php://input"), true);
$input_params = $_GET;

if (is_array($post_params)) {
    $input_params = array_merge($input_params, $post_params);
}

if (isset($input_params['status'])) {
    error_log("Status: " . $input_params['status']);
}
error_log("Event data: " . json_encode($input_params));

Es posible configurar la URL del evento para que utilice GET o POST por lo que este código se encargará de ambas. Es muy simple y escribe los datos en el archivo error_logpor lo que si estás usando el servidor web PHP local como hice en este ejemplo, verás los eventos en la salida del proceso del servidor web. En una aplicación del mundo real, puedes enlazar tu URL de eventos a algo más formal.

Poner en marcha la teleconferencia del partido

Si aún no lo has probado, llama a tu número de Vonage. Luego, invita a tus amigos, familiares y colegas a hacer lo mismo. Verás los eventos durante las llamadas llegar a event.phpy las distintas llamadas que se responden, con solicitudes realizadas a answer.php.

¿Su próximo paso?

Hay algunas cosas que te gustaría hacer a continuación:

• Consulte la documentación de NCCO para saber cómo grabar estas llamadas, reproducir música de espera o asignar un moderador específico a la llamada.

• Ver el código de este proyecto en GitHub.

• Consulta nuestros otros fragmentos de código para trabajar con Voice API de Vonage.

Conclusión

En este tutorial, creamos una llamada en conferencia con PHP utilizando la Voice API de Vonage. Configuraste una aplicación de Voice, manejaste webhooks de llamadas entrantes y devolviste una NCCO para colocar varias llamadas en la misma conversación.

A partir de aquí, puede ampliar este proyecto añadiendo grabación de llamadas, asignando moderadores, reproduciendo música de espera o generando dinámicamente nombres de salas de conferencias. También puede combinar este flujo de trabajo con la Messages API para enviar recordatorios, o integrar autenticación para controlar quién puede participar.