Inicio rápido de voz programable para PHP
Con solo un par de líneas de código, la aplicación web de PHP puede realizar y recibir llamadas telefónicas con voz programable de Twilio.
Este inicio rápido de Voice para PHP te enseñará a hacer esto con el uso de la API REST de voz de Twilio, la biblioteca auxiliar de Twilio para PHP, el servidor web de desarrollo de PHP incorporado y ngrok para exponer tu servidor local a Twilio.
Utilizaremos el administrador de paquetes Composer para la gestión de dependencias. (¿No deseas hacerlo? Prueba el inicio rápido de Voice para PHP sin Composer).
En este inicio rápido, aprenderás lo siguiente:
- Registrarte en Twilio y obtener tu primer número de teléfono de Twilio con voz habilitada
- Revisar e instalar cualquier requisito previo de PHP usando Composer
- Realizar una llamada telefónica saliente y reproducir MP3
- Recibir y responder una llamada telefónica entrante que lee un mensaje a un agente de llamada mediante la conversión de texto a voz
¿Prefieres ver un video para comenzar? Mira nuestro video sobre cómo realizar y recibir llamadas telefónicas con PHP.
Regístrate en Twilio y obtén un número de teléfono
¿Ya tienes una cuenta de Twilio y un número de teléfono de Twilio con voz habilitada? Inicia sesión y, a continuación, dirígete al paso siguiente.
You can sign up for a free Twilio trial account here.
- When you sign up, you'll be asked to verify your personal phone number. This helps Twilio verify your identity and also allows you to make calls to your phone from your Twilio account while in trial mode.
- Once you verify your number, you'll be asked to create a project. For the sake of this tutorial, you can click on the "Learn and Explore" template. Give your project a name, or just click "skip remaining steps" to continue with the default.
- Once you get through the project creation flow, you'll arrive at your project dashboard in the Twilio Console. This is where you'll be able to access your Account SID, authentication token, find a Twilio phone number, and more.
If you don't currently own a Twilio phone number with Voice functionality, you'll need to purchase one. After navigating to the Buy a Number page, check the "Voice" box and click "Search."
You’ll then see a list of available phone numbers and their capabilities. Find a number that you like and click "Buy" to add it to your account.
Instala PHP y la biblioteca auxiliar de Twilio para PHP
Si ya tienes PHP y la biblioteca auxiliar de Twilio para PHP instalados en tu directorio de trabajo, ya tienes todo listo para este paso. No dudes en continuar y pasar a enviar tu primer mensaje de texto.
Para hacer tu primera llamada de voz saliente, asegurémonos de que tienes PHP y de que puedes instalar la biblioteca auxiliar de Twilio para PHP.
Al hacer desarrollo web en PHP, recomendamos encarecidamente usar Composer para la gestión de paquetes. Este inicio rápido se basa en Composer a los efectos de instalar la biblioteca auxiliar para PHP. (Si decides no usar Composer, puedes encontrar instrucciones de la instalación manual de PHP de Twilio en la página de la biblioteca auxiliar para PHP).
Instala PHP
Si usas un equipo Mac o *nix, es posible que ya tengas instalado PHP. En el terminal, ejecuta:
php --version
Si PHP no está instalado, sigue las instrucciones de instalación de PHP.
Si usas un equipo Windows, sigue el tutorial oficial de PHP para instalarlo.
Si bien muchas versiones de PHP 7.x funcionarán para este inicio rápido, presta atención a las versiones de PHP compatibles. Al hacer desarrollo web, siempre actualiza la versión de PHP a una que reciba actualizaciones de seguridad.
Instala Composer para la gestión de paquetes
Composer es el administrador de paquetes clásico de facto para el desarrollo web en PHP. Para este tutorial, se requiere Composer. Si no deseas instalar Composer, prueba nuestro inicio rápido de Voice para PHP sin Composer.
Instala la biblioteca auxiliar de Twilio para PHP
Ahora necesitamos instalar la biblioteca auxiliar de Twilio para PHP.
Primero, ve al directorio en el que completarás este inicio rápido y, luego, elige uno de los siguientes métodos para instalar la biblioteca auxiliar.
Desde un terminal, puedes ejecutar el siguiente comando:
composer requiere twilio o sdk
O en su lugar, puedes crear un archivo llamado composer.json
. En este archivo, agrega:
{
"require": {
"twilio/sdk": "^5.0"
}
}
A continuación, ejecuta:
composer install
Composer tomará la última versión 5.x de la biblioteca auxiliar de Twilio para PHP.
Si no deseas usar Composer, prueba este inicio rápido de Voice para PHP.
Realiza una llamada telefónica saliente con PHP
Ahora que tenemos PHP y la biblioteca auxiliar para PHP instalados, podemos hacer una llamada telefónica saliente mediante una sola solicitud de API. Crea un nuevo archivo llamado make_call.php
y escribe o pega este ejemplo de código.
Cuando ejecutes el código, se iniciará una llamada telefónica entre los dos números pasados como argumentos. Hemos agregado dos variables para mostrar los números "From" (De) y "To" (A) y se asignarán de la siguiente manera:
- (From)/
twilio_number
: el número de teléfono de Twilio que compraste - (To)/
to_number
: el número al que se va a llamar (¿quizás tu teléfono celular?)
Dentro del vector, el argumento url
apunta a elementos en TwiML. TwiML es un lenguaje que Twilio utiliza internamente para iniciar acciones o responder a estas, como una secuencia de una llamada de voz. Este TwiML en particular hace que Twilio lea un mensaje con conversión de texto a voz y, luego, reproduzca MP3 para el número "To"/to_number
.
Antes de poder ejecutar este código, necesitas intercambiar un par de valores específicos de la cuenta.
Reemplaza las credenciales de los marcadores de posición por las tuyas
Sustituye los valores de los marcadores de posición account_sid
y auth_token
con las credenciales de tu cuenta de Twilio.
Para encontrarlas, visita https://www.twilio.com/console e inicia sesión. En esta página, encontrarás tu Account SID
(SID de cuenta) y Auth Token
(Token de autenticación) únicos. Para visualizar el Auth Token
, haz clic en el ícono de ojo:
Abre make_call.php
y reemplaza los valores de account_sid
y auth_token
con tus valores únicos.
Nota: Es más fácil codificar de forma fija tus credenciales para este inicio rápido, pero debes usar variables de entorno para mantenerlas en secreto en la producción. Para obtener más información, fíjate encómo establecer variables de entorno y, para obtener un ejemplo de lectura, revisa los comentarios del código. Este repositorio es también una excelente referencia para variables de entorno en PHP.
Sustituye el número de teléfono twilio_number
Anteriormente, adquiriste o encontraste un número de teléfono con voz habilitada. Pega el número en la variable twilio_number
con el formato E.164:
[+][código de país][número de teléfono con el código de área]
Por ejemplo, +18005551212
.
Sustituye el número de teléfono to_number
Nuevamente, con el uso del formato E.164, sustituye el número de teléfono que recibirá la llamada saliente. Debes utilizar un número de teléfono personal aquí para recibir la llamada y escucharla después de ejecutar el código.
Si utilizas una cuenta de prueba de Twilio, solo puedes hacer llamadas salientes a los números de teléfono que hayas verificado con Twilio. Los números de teléfono se pueden comprobar a través de los ID de agente de llamada verificados de la consola de Twilio. Para conocer las limitaciones completas de la cuenta de prueba, revisa nuestra guía sobre cómo trabajar con tu cuenta de prueba gratuita de Twilio.
Guarda el guion e invócalo para probar una llamada saliente. Para OSX y *NIX, esto debería ser así:
php make_call.php
Si reemplazaste todo correctamente, pronto escucharás un mensaje genial y una nueva canción. De lo contrario, no te des por vencido y sigue las indicaciones de la consola.
Recibe y responde llamadas de voz entrantes con PHP
Cuando alguien llama a tu número de teléfono de Twilio, Twilio envía una solicitud de HTTP a tu servidor pidiéndole instrucciones sobre cómo manejar la llamada. Para este inicio rápido, responderemos al remitente y le agradeceremos por su llamada telefónica utilizando las capacidades de texto a voz de Twilio.
Una vez más, usaremos la biblioteca de Twilio para PHP en este paso. Usaremos el servidor web de desarrollo integrado de PHP junto con ngrok para indicarle a Twilio cómo manejar la llamada.
Crea un nuevo archivo (answer_call.php
) en el mismo directorio que make_call.php
. A continuación, copia y pega o escribe el siguiente código.
(Nota: Si no utilizas el mismo directorio que empleaste cuando hicimos nuestra primera llamada, sigue el paso anterior de instalación de la biblioteca auxiliar para PHP)
Guarda answer_call.php
y, a continuación, inicia un servidor de desarrollo de PHP local con:
php -S localhost:8000
En una pestaña del navegador, abre la dirección URL http://localhost:8000/answer_call.php.
Si todo salió bien, ahora deberías ver XML en el navegador con el mensaje que nos gustaría que se leyera a las llamadas entrantes. Ese es todo el código que necesitas. Solo quedan unos pasos más antes de que todo esté listo.
A continuación, expongamos este punto final a Twilio.
Permite que Twilio hable con tu aplicación de PHP
Antes de que podamos indicarle a Twilio qué hacer en respuesta a una llamada entrante, primero necesitas exponer tu servidor al público. Cuando ejecutas tu servidor de desarrollo local, hay probabilidades muy altas de que solo sea accesible desde tu red local. Pero no te preocupes: te mostraremos una forma sencilla de probar tu servidor.
Muchos productos y servicios de Twilio utilizan webhooks para comunicarse con tu aplicación. Por ejemplo, cuando Twilio recibe una llamada entrante, llega a una URL específica que proporcionas para buscar instrucciones sobre cómo manejar la respuesta. El pequeño fragmento de código en answer_call.php
es un ejemplo de una instrucción que puedes utilizar para "hablarle" al agente de llamada. Sin embargo, cuando ejecutes el servidor, solo se expondrá a ti localmente, no al público en general. Tenemos que encontrar una forma de solucionar esto.
Aunque hay muchas formas de hacer público este código (por ejemplo, implementándolo en un host), recomendamos una herramienta llamada ngrok. Al iniciar ngrok, este proporciona una URL única en el dominio ngrok.io y reenvía las solicitudes entrantes a tu entorno de desarrollo local.
La arquitectura tiene este aspecto:
Si aún no usas ngrok, visita la página de descarga e instálalo según tu sistema operativo.
Si trabajas con Mac o Linux, ya estarás listo después de descomprimirlo. Si usas Windows, sigue nuestra guía sobre cómo instalar y configurar ngrok en Windows. Para obtener más información sobre ngrok (incluidos algunos consejos y trucos excelentes), revisa esta publicación del blog de ngrok.
Una vez que hayas descargado e instalado ngrok, abre una nueva pestaña o ventana de terminal (con el servidor de desarrollo en ejecución) e inícialo con este comando:
./ngrok http 8000
Deberías ver un resultado similar a este:
Copia la dirección URL pública de este resultado, pégala en el navegador y agrega answer_call.php
. Deberías ver el mismo XML que visualizaste anteriormente, excepto que ahora puedes acceder a él desde cualquier lugar en el que tengas acceso a Internet.
Ahora que es público, indícale a Twilio dónde encontrar el servidor.
Configura la URL de tu webhook
Ahora que el servidor es de acceso público, necesitas configurar tu número de teléfono de Twilio para acceder a la URL de tu webhook cuando ingresen llamadas nuevas.
- Visita la página de números de la consola.
- Haz clic en el número de teléfono con voz habilitada.
- Busca la sección "Voice & Fax" (Voz y fax). Asegúrate de que la opción "Accept Incoming" (Aceptar llamadas entrantes) esté establecida en "Voice Calls" (Llamadas de voz). La opción predeterminada "Configure With" (Configurar con) es la que necesitarás: "Webhooks/TwiML...".
- En la sección "A Call Comes In" (Entra una llamada), selecciona "Webhook" y pega la URL que deseas utilizar añadiendo
/answer_call.php
:
Guarda los cambios y estarás listo.
Prueba tu aplicación
Si tu servidor de desarrollo local aún está en ejecución y ngrok sigue activo, estás listo para la parte divertida: las pruebas.
Realiza una llamada telefónica a tu número de teléfono de Twilio. Verás y oirás una serie de cosas que suceden de forma consecutiva:
- Verás una solicitud de HTTP en la consola de ngrok.
- El servidor de desarrollo imprimirá algunos mensajes en la consola.
- Oirás el mensaje una vez que se conecte la llamada.
¡Y listo! Llamadas salientes y entrantes con PHP.
¿Dónde ir a continuación?
Ahora ya conoces los conceptos básicos de realizar y responder llamadas telefónicas con PHP.
Esta app de PHP solo utilizó el verbo <Say> (Decir) en TwiML para leer un mensaje al agente de llamada mediante la conversión de texto a voz. Con diferentes términos en TwiML, puedes crear otras construcciones y flujos de llamada eficaces. Prueba algunos, como <Record> (Grabar), <Gather> (Recopilar) y <Conference> (Conferencia).
Consulta estas páginas para obtener más información:
- Recopila las entradas del usuario a través del teclado (tonos DTMF) en PHP
- Cómo grabar llamadas telefónicas entrantes y salientes de Twilio Voice mediante PHP
- Crea llamadas de conferencia mediante PHP
- Consulta la documentación de referencia de la API sobre voz programable de Twilio
- Obtén información sobre cómo modificar llamadas en curso con PHP
- Utiliza Twilio Client para integrar llamadas VoIP de alta calidad a una app web o móvil.
- Recupera información sobre llamadas en curso y finalizadas desde tu cuenta de Twilio con el uso de PHP.
- Consulta nuestro tutorial de aplicación de muestra completa sobre cómo transferir llamadas de un agente de soporte a otro con PHP y Laravel.
¡Nos emociona ver lo que construirás!
¿Necesitas ayuda?
Todos la necesitamos a veces; la programación es difícil. Obtén ayuda ahora de nuestro equipo de soporte, o recurre a la sabiduría de la multitud visitando Stack Overflow Collective de Twilio o navegando por la etiqueta de Twilio en Stack Overflow.