Realizar llamadas
Con la API REST de Twilio, puedes realizar llamadas salientes a teléfonos, puntos finales habilitados para SIP y conexiones de Twilio Client.
¿Buscas los documentos de referencia de la API? Consulta la referencia de API completa para llamadas.
En esta guía, exploraremos cómo puedes utilizar la API de Programmable Voice de Twilio para realizar estas acciones:
Iniciar una llamada saliente con Twilio
Para realizar una llamada saliente, una llamada telefónica desde un número de teléfono de Twilio a un número externo, debes realizar una solicitud HTTP POST al recurso de llamada de tu cuenta:
/2010-04-01/Accounts/{AccountSid}/CallsLas llamadas iniciadas a través de la API REST están limitadas a una por segundo. Puedes poner en cola tantas llamadas como desees tan rápido como desees, pero cada llamada sale de la cola a una velocidad de una por segundo.
Tu solicitud POST a la API debe incluir los parámetros From y To a fin de que Twilio sepa dónde dirigir la llamada saliente y qué usar como ID de llamada.
Especificar el destinatario de la llamada
El parámetro To (obligatorio) es el número de teléfono, la dirección SIP o el identificador de cliente al que estás llamando.
Los números de teléfono deben tener el formato con un “+” y el código del país; por ejemplo, +16175551212 (formato E.164).
Si realizas llamadas desde una cuenta de prueba, el número de teléfono To se debe verificar con Twilio. Para verificar tu número de teléfono, agrégalo a tus identificadores de agentes de llamadas verificados en la consola.
Las direcciones SIP deben tener el formato sip:name@example.com (sip:nombre@ejemplo.com). Por ejemplo, para marcar la dirección SIP de Pat en la empresa de ejemplo, el parámetro To debe ser sip:pat@example.com.
Los identificadores de cliente deben comenzar con el esquema client:URI. Por ejemplo, para llamar a un cliente denominado joey, el parámetro To debe ser client:joey.
Especificar el ID del agente de llamada
Twilio utiliza el parámetro From (obligatorio) para establecer un número de teléfono o identificador de cliente como ID de agente de llamada para la llamada saliente.
Si utilizaste un número de teléfono para el valor To en tu solicitud POST, el valor From que especifiques también debe ser un número de teléfono. Al igual que con el parámetro To (Para), el formato de los números de teléfono debe tener un “+” y el código del país; por ejemplo, +16175551212 (formato E.164).
Cualquier número de teléfono que especifiques aquí debe ser un número de teléfono de Twilio (puedes comprar un número a través de la consola) o un identificador de agente de llamada saliente verificado para tu cuenta.
Si utilizas un identificador de cliente como valor de From, el identificador debe comenzar con el esquema client:URI. Por ejemplo, para establecer un cliente denominado charlie como tu ID de agente de llamada, el parámetro From debe ser client:charlie.
Indicar a Twilio qué hacer durante la llamada
Cuando inicias una llamada saliente con la API REST de Twilio, Twilio necesita acceder a tus instrucciones para saber cómo gestionar la llamada. Para ello, realiza una solicitud HTTP sincrónica a una de estas opciones:
- una URL que aloja un conjunto de instrucciones TwiML (podría ser un documento XML o una aplicación web); o
- el conjunto de URL y la configuración que creaste como una aplicación en la consola de Twilio.
Especifica un parámetro de URL
Si especificas un parámetro de URL en tu solicitud, Twilio realizará su solicitud HTTP a esta URL para recuperar TwiML a fin de gestionar la llamada. Esta solicitud de Twilio es idéntica a la solicitud que Twilio envía al recibir una llamada entrante.
Las URL deben contener un nombre de host válido y no se permiten guiones bajos.
Los siguientes ejemplos muestran cómo crear una llamada saliente a un número de teléfono, un punto final de Twilio Client y una dirección SIP con la API REST.
En los tres ejemplos, Twilio realizará un POST en http://demo.twilio.com/docs/voice.xml para obtener TwiML a fin de gestionar la llamada.
Especificar un parámetro ApplicationSid
Si en su lugar especificas un parámetro ApplicationSid en tu solicitud POST, Twilio usará todas las URL y otra información de configuración de esa aplicación para gestionar la llamada saliente.
El uso de ApplicationSid en tu solicitud hará que Twilio ignore los siguientes parámetros, incluso si los incluyes en tu POST: Url, Method, FallbackUrl, FallbackMethod, StatusCallback y StatusCallbackMethod. Twilio espera que el código de tu aplicación gestione toda esta información.
Puedes crear y configurar aplicaciones en la sección TwiML Apps (Aplicaciones de TwiML) de la consola. Puesto que una aplicación contiene toda la información necesaria para gestionar una llamada telefónica, tiene sentido utilizar aplicaciones para gestionar llamadas salientes con flujos de llamadas complicados.
Cuando tu llamada saliente se conecta, Twilio realizará una solicitud al conjunto VoiceUrl en tu aplicación. Esta solicitud es idéntica a la solicitud que Twilio habría enviado al parámetro URL, tal como se mencionó anteriormente.
Gestionar la llamada saliente
Al realizar un POST al punto final de la lista de llamadas de la API REST, se recomienda que le indiques a Twilio que tome acciones específicas en tu llamada saliente mediante el envío de parámetros adicionales en tu solicitud. Estos pueden incluir (pero no se limitan a) esperar una cierta cantidad de tiempo para una respuesta, marcar una extensión o grabar una llamada.
Para obtener la lista completa de parámetros que puedes pasar en tu solicitud POST, consulta la documentación detallada de la referencia de API para crear un recurso de llamada.
Por ejemplo, si deseas realizar una llamada saliente y enviar dígitos para marcar una extensión, debes agregar el parámetro opcional SendDigits a tu solicitud.
Para indicar a Twilio que grabe una llamada saliente, incluye el parámetro opcional Record y establece su valor en true:
Con este código, Twilio conectará la llamada saliente y la grabará. Pero ¿cómo puedes acceder a esa grabación y demás información sobre la llamada?
Supervisar los eventos de llamadas salientes
En el código anterior, establecimos Record=true, pero no le dimos instrucciones a Twilio sobre qué hacer con esa grabación, o cualquier otra información sobre la llamada, una vez que la llamada termine. Aquí es donde se hace presente el parámetro StatusCallback.
Fin de llamada: configuración de StatusCallback
Después de que finalice una llamada saliente, Twilio hará una solicitud HTTP asíncrona a la URL de StatusCallback especificada en tu solicitud POST. Si no proporcionas una URL para este parámetro, Twilio simplemente finalizará la llamada sin enviarte información.
Cualquier URL de StatusCallback que establezcas debe contener un nombre de host válido. No se permiten caracteres de subrayado.
Vamos a actualizar la solicitud POST a fin de realizar una llamada saliente; para ello, especifica una URL de StatusCallback esta vez para indicarle a Twilio a dónde enviar datos después de que la llamada termine.
Ten en cuenta que puedes especificar un StatusCallbackMethod para que le indique a Twilio qué tipo de solicitud HTTP debe hacer a tu URL de StatusCallback. Se trata de un parámetro opcional que, de forma predeterminada, es POST.
Cuando finalice la llamada mostrada anteriormente, Twilio enviará todos los mismos parámetros que utiliza cuando alguien realiza una llamada a uno de tus números de teléfono de Twilio. Consulta la lista completa de parámetros que Twilio siempre envía con esta solicitud.
Obtener eventos de estado de llamada durante una llamada
El parámetro opcional StatusCallbackEvent te permite especificar en qué eventos de progreso de llamada actuará Twilio. Puedes utilizar este parámetro para indicar a Twilio que envíe información a la URL de StatusCallback especificada cuando una llamada tiene un estado initiated (iniciada), ringing (llamando), answered (contestada) o completed (completada):
| Evento | Descripción |
|---|---|
| initiated | El evento initiated se activa cuando Twilio quita tu llamada de la cola y comienza a realizar la llamada. |
| ringing | El evento ringing se activa cuando la llamada comienza a sonar. |
| answered | El evento answered se activa cuando alguien contesta la llamada. |
| completed | The completed event is fired when the call ends, regardless of the termination status: busy, canceled, completed, failed, or no-answer. This means that when the call has finished execution, one of those termination statuses will be returned. If no StatusCallbackEvent is specified, completed will fire by default. |
Con el siguiente código, Twilio realizará POST en la información sobre la llamada saliente cuando la llamada se quite de la cola y comience a marcar.
Si dejas afuera StatusCallbackEvent de tu solicitud, pero especificas una URL de StatusCallback, Twilio dejará de manera predeterminada el evento en completed y enviará datos a tu URL después de que la llamada termine.
Especificar RecordingStatusCallback
Si solicitas una grabación de una llamada saliente mediante la especificación de Record=true, puedes establecer una URL de RecordingStatusCallback para que Twilio haga una solicitud GET o POST a tu URL cuando la grabación esté disponible.
Twilio enviará información a la URL especificada de RecordingStatusCallback, como CallSid, RecordingStatusy RecordingUrl (la URL en la que puedes acceder a la grabación).
Consulta la lista completa de parámetros que Twilio pasará con su solicitud a tu URL de RecordingStatusCallback.
Para pausar, reanudar o detener grabaciones mediante programación, consulta los documentos sobre la API de grabación. O explora nuestras guías para grabar llamadas telefónicas usando las bibliotecas auxiliares de Twilio.
Así como una llamada saliente tiene una serie de eventos de estado, también lo hace la grabación que Twilio crea para ti.
Al configurar RecordingStatusCallbackEvent, puedes especificar qué cambios de estado de grabación deben activar una solicitud a tu URL de RecordingStatusCallback. Los valores RecordingStatusCallbackEvent se establecen de manera predeterminada en completed, pero los valores posibles soncompleted, absent, in-progress. Para especificar más de un valor, sepáralos con un espacio.
Gestionar los posibles resultados de las llamadas
Después de que Twilio complete tu llamada saliente, hará una solicitud sincrónica a la URL que especificaste en tu solicitud POST. En esta solicitud, Twilio envía todos sus parámetros de solicitud estándar.
A partir de aquí, depende de ti lo que suceda a continuación. Se recomienda activar otro evento, como enviar un SMS al número de teléfono To al que acabas de llamar con un mensaje de seguimiento, o intentar realizar la llamada de nuevo si CallStatus devuelve failed.
For step-by-step instructions on making outbound calls and receiving inbound calls, check out our Programmable Voice quickstart in one of our six supported helper library languages: C#/.NET, Java, Node.js, PHP, Python, Ruby, or Go. You can also add voice capabilities to your web application with the JavaScript browser client, or leverage Twilio's mobile client SDKs for your Android or iOS applications.
También puedes explorar todos nuestros tutoriales de Programmable Voice para obtener información sobre cómo modificar llamadas en curso mediante programación, grabar llamadas telefónicas, crear llamadas de conferencia y mucho má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.
