TwiML™ Voice: <Number>
<Number>es un sustantivo para el verbo TwiML <Dial> y especifica un número de teléfono que marcar. Gracias a los atributos del sustantivo, puedes especificar comportamientos particulares que Twilio debe aplicar cuando marca el número.
Puedes usar hasta diez sustantivos <Number> dentro de un verbo <Dial> para llamarlos de forma simultánea a todos a la vez. La primera llamada que se va a responder se conecta a la llamada actual y el resto se cuelga. Para cada sustantivo <Number> puedes especificar en qué eventos de progreso de llamada deseas recibir webhooks.
Atributos del sustantivo
El sustantivo <Number> admite los siguientes atributos que modifican su comportamiento:
| Nombre de atributo | Valores permitidos | Valor predeterminado |
|---|---|---|
| sendDigits | Cualquier dígito | Ninguno |
| url | URL relativa o absoluta | Ninguno |
| method | GET, POST |
POST |
| byoc | Enlace SID de BYOC | Ninguno |
| statusCallbackEvent | initiated, ringing, answered, completed |
completed |
| statusCallback | Cualquier URL | Ninguno |
| statusCallbackMethod | GET, POST |
POST |
El formato de los números de teléfono debe tener el signo de + y el código de país, por ejemplo: +16175551212 (formato E.164). Twilio también aceptará números de Estados Unidos sin formato, por ejemplo, (415) 555-1212 o 415-555-1212.
sendDigits
El atributo sendDigits le dice a Twilio que reproduzca tonos DTMF cuando se conteste la llamada. Esto resulta útil cuando se marca un número de teléfono y una extensión. Twilio marcará el número y, cuando el sistema automático lo conteste, enviará los tonos DTMF para conectarse a la extensión.
url
El atributo url permite especificar una URL que devolverá una respuesta en TwiML que se ejecutará en el extremo de la parte a la que se llama, después de que responda, pero antes de que las partes se conecten.
Puedes usar este TwiML para usar <Play> de forma privada o usar <Say> a fin de decir información a la parte llamada. También puedes dar la oportunidad de rechazar la llamada usando <Gather> y <Hangup>. El atributo url no soporta ningún otro verbo TwiML.
Si se utiliza el atributo answerOnBridge en <Dial>, el agente de llamada actual seguirá escuchando el sonido de llamada mientras el documento TwiML se ejecuta en el otro extremo. Los documentos TwiML ejecutados de esta manera no pueden contener el verbo <Dial>.
method
El atributo method te permite especificar qué método HTTP debe utilizar Twilio cuando solicita la URL en el atributo url. El valor predeterminado es POST.
byoc
El atributo byoc te permite especificar qué cliente configurado Enlace BYOC Twilio debe utilizar para enrutar la llamada a la PSTN. El valor por defecto es "none" (ninguno), en cuyo caso la llamada se enrutará mediante Twilio Super Network.
statusCallbackEvent
Cuando se llama a un número usando <Dial>, se inicia una llamada saliente. La llamada pasa del estado initiated (iniciada) al estado ringing (sonando) cuando el teléfono empieza a sonar. Pasa al estado answered (contestada) cuando la llamada se responde y, finalmente, al estado completed (completada) cuando la llamada finaliza.
Con statusCallbackEvent, puedes suscribirte para recibir webhooks de los diferentes eventos de progreso de llamada en una llamada dada: initiated, ringing, answered, o completed. Las URL no relativas deben contener un nombre de host válido (no se permiten caracteres de subrayado).
El atributo statusCallbackEvent permite especificar en qué eventos Twilio se debe activar un webhook. Para especificar varios eventos, sepáralos con un espacio: initiated ringing answered completed. Si se proporciona statusCallback y no se especifican eventos de devolución de llamada de estado, el evento completed se enviará por defecto.
A diferencia de crear una llamada saliente mediante la API, las llamadas salientes creadas usando <Dial> se inician de inmediato y nunca se ponen en cola. A continuación, se muestra una línea de tiempo de los posibles eventos de llamada que pueden ser devueltos y los diferentes estados de llamada que puede experimentar un tramo de <Dial>:
| Evento | Descripción |
|---|---|
| initiated | El evento initiated se activa cuando Twilio comienza a marcar la llamada. |
| ringing | El evento ringing se activa cuando la llamada empieza a sonar. |
| answered | El evento answered se activa cuando se contesta la llamada |
| completed | El evento completed se activa cuando se completa la llamada, independiente del estado de terminación: busy (ocupada), canceled (cancelada), completed (completada), failed (fallida), o no-answer (sin respuesta). Si no se especifica ningún StatusCallbackEvent, completed se activará de forma predeterminada. |
statusCallback
El atributo statusCallback te permite especificar una URL a la que Twilio enviará peticiones de webhook en cada evento especificado en el atributo statusCallbackEvent.
statusCallbackMethod
El atributo statusCallbackMethod permite especificar qué método HTTP debe utilizar Twilio cuando solicita la URL en el atributo statusCallback. El valor predeterminado es POST.
Parámetros HTTP de devolución de llamada del estado
Los parámetros que Twilio pasa a tu aplicación en su solicitud asincrónica a la URL StatusCallback incluyen todos los parámetros pasados en una petición sincrónica para recuperar TwiML cuando Twilio recibe una llamada a uno de tus números Twilio. La lista completa de parámetros y descripciones de cada uno de ellos se encuentra en la documentación Solicitud de TwiML Voice.
Cuando se activan los eventos de progreso de llamada, la solicitud de devolución de llamada de estado también pasa estos parámetros adicionales:
| Parámetro | Descripción |
|---|---|
| CallSid | Un identificador único para esta llamada, generado por Twilio. Puedes utilizar CallSid para modificar la llamada secundaria Utilizando POST en Calls/{CallSid} con una nueva URL de TwiML. |
| ParentCallSid | Un identificador único para la llamada principal. |
| CallStatus | Estado descriptivo de la llamada. El valor es uno de los siguientes: queued, initiated, ringing, in-progress, busy, failed o no-answer. Consulta la sección de CallStatus para obtener más información. |
| CallDuration | Duración en segundos de la llamada que acaba de finalizar. Solo presente en el evento completed. |
| RecordingUrl | La URL del audio grabado en la llamada telefónica. Este parámetro se incluye solo si se establece la grabación en <Dial>y no incluye grabaciones iniciadas de otras maneras. RecordingUrl solo está presente en el evento completed. |
| RecordingSid | El ID único de la [Grabación][grabaciones] de esta llamada. RecordingSid solo está presente en el evento completed. |
| RecordingDuration | Duración del audio grabado (en segundos). RecordingDuration solo está presente en el evento completed. Para obtener una duración de grabación final precisa después de recortar el silencio, utilice recordingStatusCallback. |
| Timestamp | La marca de tiempo cuando se activó el evento, dada como UTC en formato RFC 2822. |
| CallbackSource | Una cadena que describe el origen del webhook. Esto se proporciona para ayudar a desambiguar por qué se hizo el webhook. En las devoluciones de llamada de estado, este valor siempre es call-progress-events. |
| SequenceNumber | El orden en el que se desencadenaron los eventos, a partir de 0. Aunque los eventos se activan en orden, se realizan como solicitudes HTTP independientes y no hay garantía de que lleguen en el mismo orden. |
Ejemplos
Ejemplo 1: usando sendDigits
En este caso, queremos marcar la extensión 1928 al 415-123-4567. Usamos un sustantivo <Number> para describir el número de teléfono y darle el atributo
sendDigits. Queremos esperar antes de enviar la extensión, así que agregamos unos cuantos caracteres w iniciales. Cada w le dice a Twilio que espere medio segundo en lugar de reproducir un dígito. Esto te permite ajustar la sincronización de cuando los dígitos comienzan a reproducirse para adaptarse al sistema telefónico que estás marcando.
Ejemplo 2: marcación simultánea
En este caso, usamos varias etiquetas <Number> para marcar tres números de teléfono al mismo tiempo. La primera de estas llamadas que se conteste se conectará con el agente de llamada actual, mientras que el resto de los intentos de conexión se cancelarán.
Ejemplo 3: eventos de progreso de llamada
En este caso, queremos recibir un webhook para cada evento de progreso de llamada cuando marcamos un número usando <Dial>.
Ejemplo 4: marcado múltiple con eventos de progreso de llamada
En este caso, queremos recibir un webhook para cada evento de progreso de llamada en cada número cuando marcamos varios números usando <Dial>.
Ejemplo 5: ejecutar TwiML antes de que las partes estén conectadas
En este caso, queremos conectar dos partes usando <Dial>, pero también queremos que las instrucciones TwiML se envíen a la parte a la que estamos llamando antes de que se conecten a la llamada. Si configuramos el atributo url, podemos especificar una URL que devolverá una respuesta TwiML para que se ejecute en el extremo de la parte a la que se llama Este TwiML se ejecutará después de que respondan, pero antes de que las partes estén conectadas.
Consejos y usos avanzados
- Puede especificar hasta diez números dentro de un verbo
<Dial>para marcar de forma simultánea. - La marcación simultánea es útil cuando hay varios teléfonos (o varias personas) que deseas llamar cuando recibes una llamada entrante. Ten en cuenta que la primera llamada que se conecta cancelará el resto de intentos. Si marcas un sistema telefónico de oficina o un teléfono celular en modo avión, puede que responda después de un solo timbre, lo que evita que los otros números de teléfono suenen el tiempo suficiente para que un ser humano responda. Por lo tanto, debes tener cuidado de utilizar la marcación simultánea solo en situaciones en las que conozcas el comportamiento de las partes a las que se llama.
¿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.
