You are viewing the Spanish (Mexico) site, but your language preference is set to English. Switch to English site →

Menu

Expand
Calificar esta página:

TwiML™ para Programmable Voice

¿Qué es TwiML?

TwiML (el Twilio Markup Language) se trata de un conjunto de instrucciones que puedes utilizar para decirle a Twilio lo que debe hacer cuando recibe una llamada entrante, un SMS o un fax.

Cómo funciona TwiML

Cuando alguien hace una llamada a uno de tus números de Twilio, Twilio busca la URL asociada a ese número de teléfono y le envía una solicitud. Luego, Twilio lee las instrucciones TwiML alojadas en esa URL a fin de determinar qué hacer: ya sea grabar la llamada, reproducir un mensaje para el agente de llamada o pedirle que oprima dígitos en su teclado.

En esencia, TwiML es un documento XML con etiquetas especiales definidas por Twilio para ayudarte a crear tu aplicación de Programmable Voice.

¿No haces llamadas telefónicas? TwiML potencia más que solo Programmable Voice de Twilio: consulta la documentación sobre cómo usar TwiML con SMS programable y Fax programable.

Lo siguiente dirá "Hello, world!" (Hola, mundo) cuando alguien marque un número de Twilio configurado con este TwiML:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Say>Hello, world!</Say>
</Response>

Siempre puedes devolver TwiML sin procesar desde el idioma que desees, o aprovechar las bibliotecas de auxiliares de Twilio para crear de forma automática un TwiML válido tuyo. En el siguiente código de muestra, cambia a tu lenguaje de programación web preferido para ver cómo se ve el TwiML anterior utilizando la biblioteca auxiliar.

        
        
        

        Consulta nuestro breve tutorial sobre cómo responder a llamadas telefónicas entrantes, disponible en nuestros seis idiomas compatibles de la biblioteca auxiliar. También puedes aprovechar los contenedores de TwiML de Twilio, nuestra solución sin servidores que te permite escribir un TwiML que Twilio alojará para ti, de manera que puedas crear con rapidez prototipos de una solución sin tener que hacer girar un servidor web.

        Las llamadas salientes (llamadas desde un número Twilio a un número externo) se controlan utilizando TwiML de la misma manera. Cuando inicias una llamada saliente con la API de Twilio, Twilio le solicita a tu TwiML que aprenda a manejar la llamada.

        Twilio ejecuta solo un documento de TwiML al agente de llamada a la vez, pero muchos documentos TwiML se pueden enlazar para crear aplicaciones de voz complejas e interactivas.

        Elementos de TwiML

        En el lenguaje de TwiML, los elementos XML se dividen en tres grupos: el elemento <Response> raíz, los verbos y los sustantivos.

        Los elementos de TwiML (verbos y sustantivos) tienen nombres que distinguen entre mayúsculas y minúsculas. Por ejemplo, si utilizas <say> en vez de <Say>, se producirá un error. Los nombres de atributo también distinguen entre mayúsculas y minúsculas y camelCased.

        Puedes utilizar los comentarios de XML de forma libre; el intérprete los ignora.

        El elemento de <Response>

        En cualquier respuesta TwiML a una solicitud de Twilio, debes anidar todos los elementos de verbo dentro de <Response>, el elemento raíz del marcado XML de Twilio:

        <?xml version="1.0" encoding="UTF-8"?>
        <Response>
            <Say>
              This message must be nested in a Response element
              in order for Twilio to say it to your caller.
            </Say>
        </Response>

        Cualquier otra estructura se considera no válida.

        Verbos de TwiML para Programmable Voice

        Los verbos de TwiML le dicen a Twilio qué acciones tomar en una llamada dada. Debido a esto, la mayoría de los elementos de un documento TwiML son verbos TwiML. Los nombres de los verbos distinguen entre mayúsculas y minúsculas, al igual que los nombres de sus atributos.

        Puedes usar diferentes combinaciones de verbos de TwiML para crear todo tipo de aplicaciones interactivas de voz. Estos son los verbos TwiML principales para Programmable Voice:

        • <Say>: leer el texto al agente de llamada
        • <Play>: reproducir un archivo de audio para el agente de llamada
        • <Dial>: agregar otro interlocutor a la llamada
        • <Record>: grabar la voz del agente de llamada
        • <Gather>: recolectar los dígitos que el agente de llamada escribe en su teclado

        Los siguientes verbos se pueden utilizar para controlar el flujo de la llamada:

        • <Hangup>: colgar la llamada
        • <Enqueue>: agregar al agente de llamada a una cola de agentes de llamada
        • <Leave>: quitar a un agente de llamada de una cola de agentes de llamada
        • <Pause>: esperar antes de ejecutar más instrucciones
        • <Redirect>: redirigir el flujo de llamadas a un documento TwiML diferente
        • <Refer>: Twilio inicia la REFER SIP hacia la infraestructura de comunicación IP
        • <Reject>: rechazar una llamada entrante sin ser facturada

        Los siguientes sustantivos proporcionan capacidades avanzadas:

        Hay ciertas situaciones en las que el intérprete de TwiML puede no llegar a los verbos de un documento de TwiML porque el flujo de control ha pasado a un documento diferente. Esto suele ocurrir cuando se define el atributo action de un verbo.

        Por ejemplo, si un verbo <Say> va antes de un <Redirect> y, después, sigue otro <Say>, el segundo <Say> no es accesible porque <Redirect> transfiere el control total de una llamada al TwiML en una dirección URL diferente.

        Sustantivos TwiML

        Un sustantivo de TwiML describe los números de teléfono y los recursos API sobre los que deseas realizar una acción. En la práctica, un sustantivo TwiML es cualquier cosa anidada dentro de un verbo que no es en sí mismo un verbo; es aquello sobre lo que el verbo actúa.

        Los sustantivos de TwiML suelen ser solo texto. Pero a veces, como en el caso de <Dial> con sus sustantivos de <Number> y <Conference>, hay elementos XML anidados que son sustantivos.

        Solicitud de Twilio a tu aplicación

        Cuando alguien hace una llamada entrante a uno de tus números de teléfono de Twilio, Twilio necesita solicitar TwiML desde tu aplicación a fin de obtener instrucciones para manejar la llamada.

        Si deseas configurar tu número de teléfono de Twilio para que apunte a la URL de tu aplicación, visita la sección de números de teléfono de la consola. Selecciona tu número de teléfono y, a continuación, desplázate a la sección 'Voice & Fax' (Voz y fax) para establecer un webhook, contenedor de TwiML o Twilio Function a fin de que Twilio envíe esa solicitud HTTP cuando llegue una llamada:

        Configure webhook on phone number for voice

        Twilio hace su solicitud mediante HTTP, ya sea como GET o POST, al igual que solicitando una página web en tu navegador o enviando un formulario.

        Twilio no puede almacenar POST en caché. Si deseas que Twilio almacene en caché las páginas TwiML estáticas, entonces haz que Twilio haga peticiones a tu aplicación usando GET.

        Cuando se incluyen parámetros y valores en su solicitud, Twilio envía datos a tu aplicación sobre los que puedes actuar antes de responder.

        Parámetros de solicitud

        Twilio siempre envía los siguientes parámetros cuando envía una solicitud a tu aplicación para recuperar instrucciones sobre cómo manejar una llamada.

        Se enviarán como parámetros POST o como parámetros de consulta de URL, dependiendo del método HTTP que hayas configurado.

        Parámetro Descripción
        CallSid Un identificador único para esta llamada, generado por Twilio.
        AccountSid Tu ID de cuenta Twilio. Tiene 34 caracteres y siempre comienza con las letras AC.
        De

        Número de teléfono o identificador de cliente de la persona que inició la llamada.

        El formato de los números de teléfono tiene el signo de '+' y el código de país, por ejemplo +16175551212 (formato E.164). Los identificadores de cliente comienzan con el esquema de URI client:; por ejemplo, en una llamada desde un cliente llamado 'charlie' el parámetro From será client:charlie.

        To (Para)

        Número de teléfono o identificador de cliente de la persona a la que se llama.

        El formato de los números de teléfono tiene el signo de '+' y el código de país, por ejemplo +16175551212 (formato E.164). Los identificadores de cliente comienzan con el esquema URI client:; por ejemplo, en una llamada a un cliente llamado 'joey', el parámetro To seráclient:joey.

        CallStatus

        Un estado descriptivo de la llamada.

        El valor es uno de estos: queued, ringing, in-progress, completed, busy, failed o no-answer. Consulta la sección CallStatus que aparece a continuación para obtener más información.

        ApiVersion

        La versión de la API de Twilio usada para manejar esta llamada.

        En el caso de las llamadas entrantes, esto está determinado por la versión de la API establecida en el número al que se llama. Para las llamadas salientes, esta es la versión utilizada por la solicitud de API REST de la llamada saliente.

        Direction

        Una cadena que describe la dirección de la llamada:

        inbound para llamadas entrantes.

        outbound-api para llamadas iniciadas mediante la API REST.

        outbound-dial para llamadas iniciadas por un verbo <Dial>.

        ForwardedFrom

        Este parámetro se establece solo cuando Twilio recibe una llamada transferida, pero su valor depende del operador móvil del agente de llamada, incluida la información cuando se transfiere.

        No todos los operadores móviles admiten la transferencia de esta información.

        CallerName Este parámetro se establece cuando el IncomingPhoneNumber que recibió la llamada establece su valor de VoiceCallerIdLookup entrue(USD 0,01 por búsqueda).
        ParentCallSid

        Identificador único para la llamada que creó este tramo.

        Este parámetro no se transfiere si este es el primer tramo de una llamada.

        CallToken

        Una cadena de token necesaria para invocar una llamada desviada.

        X-Home-Region

        Una cadena que describe la región de origen de Twilio en la que se procesó el webhook.

        Twilio también intenta buscar datos geográficos basados en los números de teléfono To (A) y From (De). Si están disponibles, Twilio enviará los siguientes parámetros con su solicitud:

        Parámetro Descripción
        FromCity La ciudad del agente de llamada
        FromState Estado o provincia del agente de llamada
        FromZip Código postal del agente de llamada
        FromCountry País del agente de llamada
        ToCity La ciudad de la persona a la que se llama
        ToState Estado o provincia de la persona a la que se llama
        ToZip El código postal de la persona a la que se llama
        ToCountry País de la persona a la que se llama

        Twilio proporcionará los parámetros antes mencionados cuando haga una solicitud a tu aplicación para recuperar instrucciones sobre cómo manejar una llamada. Esto puede ocurrir cuando una llamada entrante llega a tu número de Twilio, o después de que un verbo TwiML haya terminado y hayas proporcionado una action URL (URL de acción) en la que Twilio puede recuperar el siguiente conjunto de instrucciones. Dependiendo de lo que ocurre en una llamada, también se pueden enviar otras variables.

        Por ejemplo, cuando Twilio reciba un SIP, enviará parámetros adicionales a tu aplicación web: Encontrará la lista de parámetros enviados con SIP en "Interacción de SIP y TwiML".

        Hay algunos casos en los que Twilio enviará una solicitud que no contiene todos los parámetros anteriores. Por ejemplo, si has proporcionado una URL de statusCallback en un sustantivo de TwiML como <VirtualAgent> o <Pay>, la solicitud de Twilio a tu aplicación no contendrá todos los parámetros listados antes, ya que podrían no ser todos relevantes para la devolución de llamada de estado en particular. En esos casos, puedes encontrar los parámetros esperados en la documentación específica del verbo de TwiML.

        Valores de CallStatus

        A continuación, se muestran los valores posibles para el parámetro CallStatus. Estos valores también se aplican al parámetro DialCallStatus, que se envía con solicitudes HTTP a una URL de acción de <Dial>.

        Estado Descripción
        queued La llamada está lista y esperando en línea antes de salir.
        ringing La llamada está sonando en la actualidad.
        in-progress La llamada se contestó y está en curso de forma activa.
        completed La llamada se contestó y ha finalizado con normalidad.
        busy El agente de llamada ha recibido una señal de ocupado.
        failed No se pudo completar la llamada como se marcó, lo más probable porque el número de teléfono no existía.
        no-answer La llamada finalizó sin ser contestada.
        canceled La llamada se canceló mediante la API REST mientras estaba en cola o sonando.

        Finalización de la llamada: solicitudes de devolución de llamada

        Después de recibir una llamada, solicitar TwiML desde tu app, procesarlo y, por último, finalizar la llamada, Twilio hará una solicitud HTTP asincrónica a la URL StatusCallback configurada para el número de Twilio que se llamó.

        Debes proporcionar de forma explícita esta URL a la aplicación en el parámetro StatusCallback de cada mensaje para el que desees realizar las devoluciones de llamada de estado. El TwiML sin procesar para esto tiene el siguiente aspecto:

        <?xml version="1.0" encoding="UTF-8"?>
        <Response>
            <Dial>
                <Number
                 statusCallbackEvent="initiated ringing answered completed"
                 statusCallback="https://myapp.com/calls/events"
                 statusCallbackMethod="POST">
                    +12316851234
                </Number>
            </Dial>
        </Response>
        

        El siguiente código de muestra demuestra cómo establecer la dirección URL de StatusCallback con TwiML simple o utilizando la biblioteca auxiliar que elijas:

              
              
              

              Cuando se proporciona una URL de StatusCallback para tu número de Twilio y se captura esta solicitud, puedes determinar cuándo finaliza una llamada y recibir información sobre ella. Ten en cuenta que las URL no relativas deben contener un nombre de host válido, no se permiten guiones bajos.

              Parámetros de solicitud StatusCallback

              Cuando Twilio envía parámetros a tu aplicación en una solicitud asincrónica a la URL de StatusCallback, incluyen los mismos parámetros transferidos en una solicitud TwiML sincrónica.

              La solicitud de devolución de llamada de estado también transfiere estos parámetros adicionales:

              Parámetro Descripción
              CallDuration La duración en segundos de la llamada que acaba de finalizar.
              RecordingUrl La URL del audio grabado de la llamada telefónica. Este parámetro solo se incluye si Record=true se establece en la solicitud de la API REST y no incluye las grabaciones de<Dial> o <Record>.
              RecordingSid ID exclusivo de la grabación de esta llamada.
              RecordingDuration La duración del audio grabado (en segundos).

              Formatos de datos

              Números de teléfono

              Todos los números de teléfono en solicitudes de Twilio están en formato E.164 si es posible. Por ejemplo, (231) 685-1234 vendría como “+12316851234”. Sin embargo, en ocasiones hay casos en los que Twilio no puede normalizar un ID de llamada entrante a E.164. En estas situaciones, Twilio informará sobre la cadena de ID de llamada sin procesar.

              Fechas y horas

              Todas las fechas y horas en las solicitudes de Twilio son GMT en formato RFC 2822. Por ejemplo, a las 6:13 p. m. PDT del 19 de agosto del 2010 sería 'Fri, 20 Aug 2010 01:13:42 +0000'

              Twilio es un cliente HTTP de buen comportamiento

              Twilio se comporta igual que un navegador web cuando realiza solicitudes HTTP a URL:

              • Cookies: Twilio acepta cookies HTTP y las incluirá en cada solicitud, al igual que un navegador web normal.
              • Redirecciones: Twilio sigue las redirecciones HTTP (códigos de estado HTTP 301, 307, etc.), igual que un navegador web normal. Twilio admite un máximo de 10 redirecciones antes de que la solicitud falle con el código de error 11215.
              • Almacenamiento en caché: Twilio almacenará en caché los archivos cuando los encabezados HTTP lo permitan (a través de ETag y los encabezados modificados por última vez) y cuando el método HTTP sea GET, como un navegador web normal.

              Twilio entiende los tipos MIME

              Twilio hace lo correcto cuando tu aplicación responde con diferentes tipos MIME:

              Tipo de MIME Comportamiento
              text/xml, application/xml, text/html Twilio interpreta el documento devuelto como un conjunto de instrucciones XML (al que nos gusta llamar TwiML). Esta es la respuesta más utilizada.
              Varios tipos de audio Twilio reproduce el archivo de audio al agente de llamada y, a continuación, cuelga. Consulta la documentación de <Play> para conocer los tipos MIME soportados.
              text/plain Twilio lee el contenido del texto en voz alta para el agente de llamada y, luego, cuelga.

              Responder a Twilio

              En tu respuesta a la solicitud de Twilio a tu URL configurada, puedes decirle a Twilio qué hacer en una llamada.

              Cómo funciona el intérprete de TwiML

              Cuando tu aplicación responde a una solicitud Twilio con XML, Twilio ejecuta tu documento mediante el intérprete TwiML. Para que las cosas sean sencillas, el intérprete TwiML solo entiende unos pocos elementos XML con nombres especiales que forman TwiML: <Response>, verbosy sustantivos.

              El intérprete comienza en la parte superior de tu documento TwiML y ejecuta instrucciones (verbos) en orden descendente.

              El siguiente fragmento de código lee "Hello World" (Hola a todos) al agente de llamada antes de reproducir Cowbell.mp3 para dicho agente y, luego, cuelga.

              <?xml version="1.0" encoding="UTF-8"?>
              <Response> 
                  <Say>Hello, World!</Say>
                  <Play>https://api.twilio.com/Cowbell.mp3</Play>
              </Response>
              

              Al igual que con todos los TwiML, puedes utilizar las bibliotecas auxiliares para ayudarte a reproducir música a un agente de llamada. Incluye el atributo loop para decirle a Twilio que reproduzca en bucle esta grabación diez veces (o hasta que el agente de llamada cuelgue):

                    
                    
                    

                    Devoluciones de llamadas de estado en tu respuesta

                    Las devoluciones de llamada de estado no controlan el flujo de llamadas, por lo que no es necesario devolver TwiML. Si respondes, utiliza el código de estado 204 No Content o 200 OK con Content-Type: Text/xml y una <Response/> vacía en el cuerpo. Si no se responde de forma correcta, se producirán advertencias en el depurador.

                    ¿Qué sigue?

                    Profundiza para aprender más acerca de los distintos verbos TwiML que utilizarás con Programmable Voice de Twilio, como utilizar <Dial> a fin de conectar una llamada o <Gather> en reconocimiento de voz y recoger las pulsaciones de teclas del usuario. Encontrarás todos los documentos de referencia en profundidad vinculados arriba.

                    También puedes explorar cómo generar TwiML con las bibliotecas auxiliares de Twilio, que te permiten generar TwiML en tu idioma favorito.

                    Para un tutorial guiado, consulta nuestras guías de inicio rápido que te mostrarán cómo realizar y recibir llamadas telefónicas con Twilio en C#/.NET, Java, Node.js, PHP, Python o Ruby.

                    Calificar esta página:

                    ¿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.

                          
                          
                          

                          Gracias por tus comentarios.

                          Selecciona los motivos de tus comentarios. La información adicional que nos brindas nos ayuda a mejorar nuestra documentación:

                          Enviando tus comentarios…
                          🎉 Gracias por tus comentarios.
                          Se produjo un error. Inténtalo de nuevo.

                          Gracias por tus comentarios.

                          ¡Recomiéndanos y gana USD 10 en 3 pasos sencillos!

                          Paso 1

                          Obtén un enlace

                          Obtén un enlace gratuito de referencia personal aquí

                          Paso 2

                          Regala USD 10

                          Tu usuario se registra y actualiza mediante el enlace

                          Paso 3

                          Obtén USD 10

                          1250 SMS gratuitos
                          O 1000 minutos gratuitos de voz
                          O 12 000 chats
                          O más