TwiML™ Voice: <Dial>
Durante una llamada activa, puedes utilizar el verbo <Dial> de TwiML para conectar al agente de llamada actual con otra persona.
En el siguiente ejemplo, se muestra el uso más básico de <Dial>:
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Dial>415-123-4567</Dial>
</Response>Si la parte en 415-123-4567 contesta la llamada, ambas partes pueden comunicarse hasta que uno cuelgue.
El verbo <Dial> terminará la nueva llamada si sucede esto:
- La persona a la que se llama no responde.
- Twilio recibe una señal de ocupado.
- El número no existe.
<Dial> no puede iniciar una llamada directo desde Twilio, solo marcará el número de un nuevo interlocutor desde una llamada activa en curso. Para iniciar una nueva llamada saliente desde Twilio, debes realizar una solicitud API al punto final de llamada.
Para obtener una guía paso a paso sobre cómo hacer tu primera llamada saliente con Twilio, prueba uno de nuestros inicios rápidos que muestran cómo hacer una llamada usando las bibliotecas auxiliares de Twilio.
Twilio hará solicitud de GET o POST a la action URL (URL de acción) (si se proporciona) cuando finalice la llamada de <Dial>. El flujo de llamadas continuará y utilizará el TwiML que envíes en respuesta a esa solicitud.
Si no proporcionas una action URL en tu <Dial> y el agente de llamada original aún está en línea, Twilio continuará procesando el documento TwiML original.
Con este código, Twilio conectará la llamada original con una nueva persona marcando 415-123-4567. A continuación, pueden ocurrir varias cosas:
- Si alguien contesta, Twilio conecta al agente de llamada con la persona llamada.
- Si el agente de llamada inicial cuelga, la sesión Twilio finaliza y
<Say>no se ejecuta. - Si la línea está ocupada, si no hay respuesta o si la persona a la que se llama cuelga,
<Dial>se cierra y el agente de llamada inicial oye el texto de<Say>(“Goodbye” [Adiós]) antes de que finalice el flujo de llamada.
Atributos de <Dial>
<Dial> admite los siguientes atributos que cambian su comportamiento:
| Atributo | Valores permitidos | Valor predeterminado |
|---|---|---|
| action | URL relativa o absoluta | Ninguno |
| answerOnBridge | true, false |
false |
| callerId | Un número de teléfono válido o identificador de cliente si estás marcando un <Client>. |
CallerID del agente de llamada |
| callReason | Cadena (máximo 50 caracteres) | Ninguno |
| hangupOnStar | true, false |
false |
| method | GET, POST |
POST |
| record | do-not-record, record-from-answer, record-from-ringing, record-from-answer-dual, record-from-ringing-dual. En términos de compatibilidad con versiones anteriores, true es un alias de record-from-answer y false es un alias de do-not-record. |
do-not-record |
| recordingStatusCallback | URL relativa o absoluta | Ninguno |
| recordingStatusCallbackMethod | GET, POST |
POST. Este atributo indica qué método HTTP Twilio debe utilizar cuando se solicite 'recordingStatusCallback'. |
| recordingStatusCallbackEvent | in-progress, completed, absent |
completed |
| recordingTrack | inbound, outbound, both |
both |
| referUrl | URL relativa o absoluta | Ninguno |
| referMethod | GET, POST |
POST |
| ringTone | ISO 3166-1 alpha-2 country code | Vuelve de forma predeterminada al tono del operador móvil |
| timeLimit | Número entero positivo (segundos) | 14 400 segundos (4 horas) |
| timeout | Número entero positivo (segundos) | 30 segundos |
| trim | trim-silence, do-not-trim |
do-not-trim |
Usa uno o más de estos atributos en un verbo <Dial> de esta manera:
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Dial timeout="10" record="true">415-123-4567</Dial>
</Response>
action
El atributo action acepta una dirección URL como argumento. Esta URL le indica a Twilio dónde realizar una solicitud de POST o GET después de que finalice la llamada marcada.
La solicitud de Twilio a esta URL incluirá los siguientes parámetros:
| Parámetro | Descripción |
|---|---|
| DialCallStatus | El resultado del intento de <Dial>. Consulta la sección de DialCallStatus a continuación para obtener más información. |
| DialCallSid | El SID de llamada del nuevo tramo de llamada. Este parámetro no se envía después de marcar una conferencia. |
| DialCallDuration | Duración en segundos de la llamada marcada. Este parámetro no se envía después de marcar una conferencia o si una llamada secundaria se redirige a una nueva URL de TwiML antes de desconectarse. |
| DialBridged | Indicador booleano que indica si la llamada marcada se ha conectado o no al destino marcado. |
| RecordingUrl | La URL del audio grabado. Este parámetro se incluye solo si la grabación está ajustada en <Dial> y no incluye grabaciones iniciadas de otras maneras. Es posible que el archivo de grabación aún no esté accesible cuando se envíe la devolución de llamada de acción. Utiliza recordingStatusCallback a fin de obtener una notificación confiable cuando la grabación esté disponible para el acceso. |
Si utilizas <Dial> en un <Queue>, Twilio pasará los parámetros adicionales a tu action URL (URL de acción). Lee la documentación de <Queue> detallada para obtener más información.
Si especificas una action URL para utilizar<Dial>, Twilio continuará la llamada inicial después de que la persona a la que se ha llamado cuelgue.
No se podrá alcanzar ningún verbo TwiML que se incluya después de<Dial>, ya que tu respuesta a Twilio toma el control total de la llamada inicial. Si deseas realizar más acciones en esa llamada inicial, debes responder a la solicitud de Twilio con instrucciones TwiML sobre cómo manejar la llamada.
Si no proporcionas una action URL, <Dial> terminará y Twilio pasará al siguiente verbo TwiML en el documento. Si no hay más verbos, Twilio terminará la llamada telefónica. Ten en cuenta que esto es diferente del comportamiento de <Record> y <Gather>.
DialCallStatus
Si especificas una action URL, Twilio siempre pasará el estado del intento de <Dial>.
Estos son los valores posibles de DialCallStatus:
| Valor | Descripción |
|---|---|
| completed | La parte que se llamó contestó la llamada y se conectó con el agente de llamada. |
| answered | Cuando se llama a una conferencia, la persona que se llamó contestó la llamada y se conectó con el agente de llamada. |
| busy | Twilio ha recibido una señal de ocupado cuando se intenta conectarse a la persona a la que se llama. |
| no-answer | La persona a la que se llama no ha contestado la llamada antes de que transcurra el tiempo de espera. |
| failed | Twilio no ha podido dirigir al número de teléfono dado. Esto se debe a menudo cuando se marca un número de teléfono con el formato correcto, pero inexistente. |
| canceled | La llamada se canceló mediante la API REST antes de ser contestada. |
Volver a la lista de atributos
answerOnBridge
Si <Dial> es el primer verbo TwiML en tu documento TwiML, answerOnBridge="true"hará que la llamada entrante suene hasta que el número marcado responda.
Si tu llamada entrante es una llamada SIP, Twilio enviará un 180 o un 183 a tu servidor SIP una vez que se conecte a Twilio. Esperará hasta que la llamada <Dial> se conecte para devolver un 200.
callerId
Cuando utilizas <Dial> en tu respuesta a la solicitud de llamada entrante de Twilio, el interlocutor marcado ve el número del agente de llamada entrante como ID de agente de llamada.
Por ejemplo:
- Alguien con un ID de agente de llamada de
1-415-123-4567llama a tu número de Twilio. - Le dices a Twilio que ejecute un verbo
<Dial>para1-858-987-6543que maneje la llamada entrante. - La persona a la que se llama (
1-858-987-6543) verá1-415-123-4567como el ID del agente de llamada en la llamada entrante.
Cuando se utiliza el sustantivo <Number> y se especifica un callerId en tu <Dial>, puedes establecer un ID de llamada diferente al predeterminado. Puedes cambiar el número de teléfono que ve la persona a la que se llama por uno de estos:
- El número
To(A) oFrom(De) proporcionado en la solicitud TwiML de Twilio a tu app. - Cualquier número de teléfono entrante que hayas comprado en Twilio.
- Cualquier número de teléfono que hayas verificado con Twilio.
En el caso de una llamada SIP entrante, callerId no puede ser el número To o From, ya que existe el riesgo de falsificación del ID del agente de llamada. Solo puede ser un número de Twilio o un número de teléfono verificado con Twilio.
Si estás marcando a un <Client>, también puedes establecer un identificador de cliente válido como atributo callerId. Por ejemplo, si has configurado un cliente para las llamadas entrantes y estás marcando ese cliente, puedes establecer el atributo callerId en client:joey.
Si vas a marcar un punto final de <Sip>, introduce cualquier cadena alfanumérica como callerId. De forma opcional, incluye los siguientes caracteres: +, -, _ y ., pero sin espacios en blanco.
En el siguiente ejemplo, utilizamos <Dial> para llamar a un número de teléfono desde un dispositivo Twilio Client:
Volver a la lista de atributos
hangupOnStar
El atributo hangupOnStar permite al agente de llamada inicial colgar a la persona a la que se llama pulsando la tecla ‘*’ del teléfono.
Cuando dos partes están conectadas mediante <Dial>, Twilio bloquea la ejecución de otros verbos hasta que el agente de llamada o la persona llamada cuelga. La función hangupOnStar permite que el agente de llamada inicial cuelgue a la persona a la que llamó sin tener que colgar el teléfono (lo que terminaría la sesión de procesamiento de TwiML).
Cuando el agente de llamada pulsa ‘*’, Twilio colgará a la persona a la que se llama. Si se proporcionó una action URL (URL de acción), Twilio envía un DialCallStatus a esa URL y procesa la respuesta. Cuando se llama a una conferencia, el estado de DialCallStatus será answered. Todos los demás tipos de llamada tendrán un estado de completed en DialCallStatus.
Si no se ha proporcionado un action, Twilio continúa con el siguiente verbo en el documento TwiML actual.
method
El atributo method acepta GET o POST. Esto le dice a Twilio si debe solicitar la action URL mediante HTTP GET o POST, con POST como valor predeterminado.
En el siguiente ejemplo, hemos proporcionado una action URL y hemos especificado GET como method:
Este código usará <Dial> para conectar al agente de llamada inicial al número de teléfono415-123-4567.
Cuando finalice la llamada <Dial>, Twilio enviará una solicitud GET a nuestra action URL. Esta solicitud incluirá el parámetro DialCallStatus que indica el estado de esa llamada <Dial>.
Nuestra aplicación web alojada en esta action URL ahora puede mirar el DialCallStatus y enviar una respuesta a Twilio diciéndole lo que debe hacer a continuación.
En este ejemplo, el verbo <Say> nunca se ejecutará, ya que el código en /handleDialCallStatus toma el control total de la llamada.
Volver a la lista de atributos
record
El atributo record te permite registrar ambos tramos de una llamada dentro del verbo <Dial> asociado. Las grabaciones están disponibles en dos opciones: monocanal o doble canal.
En las grabaciones monocanal, ambos tramos de la llamada se mezclan en un único canal dentro de un archivo de grabación.
Estas son las opciones de record en monocanal:
record-from-answer, que iniciará la grabación en cuanto se responda a la llamada.record-from-ringing, que iniciará la grabación cuando comience el timbre (antes de que el destinatario conteste la llamada).
Con las grabaciones de doble canal, ambos tramos utilizan canales independientes dentro de un único archivo de grabación.
Estas son las opciones de record en doble canal:
record-from-answer-dual, que iniciará la grabación en cuanto se responda a la llamada.record-from-ringing-dual, que iniciará la grabación cuando comience el timbre (antes de que el destinatario conteste la llamada).
La llamada principal siempre estará en el primer canal y la llamada secundaria siempre estará en el segundo canal de una grabación de doble canal.
Si se utiliza una opción de grabación de doble canal para un <Dial> con un <Conference> anidado, el archivo de grabación resultante tendrá dos canales. El tramo principal (agente de llamada entrante) se representa en el primer canal. El segundo canal incluye el audio que proviene de la conferencia.
recordingStatusCallback
El atributo recordingStatusCallback toma una dirección URL relativa o absoluta como argumento. Si has solicitado una grabación en este <Dial>, esta URL le dice a Twilio dónde realizar la solicitud GET o POST cuando se pueda acceder a la grabación.
Twilio pasará los siguientes parámetros con su solicitud a tu URL de recordingStatusCallback:
| Parámetro | Descripción |
|---|---|
| AccountSid | El identificador único de la cuenta responsable de esta grabación. |
| CallSid | Identificador exclusivo de la llamada asociada a la grabación. Esto siempre se referirá al tramo principal de una llamada de dos tramos. |
| RecordingSid | Identificador exclusivo de la grabación. |
| RecordingUrl | La URL del audio grabado. |
| RecordingStatus | Estado de la grabación. Estos son los valores posibles: in-progress, completed, absent. |
| RecordingDuration | Duración de la grabación, en segundos. |
| RecordingChannels | La cantidad de canales en el archivo de grabación final como un número entero. Los valores posibles son 1, 2. |
| RecordingStartTime | La marca de tiempo del inicio de la grabación. |
| RecordingSource | El método de inicio utilizado para crear esta grabación. Para grabaciones iniciadas cuando la grabación está ajustada en <Dial>, se devuelve DialVerb. |
Volver a la lista de atributos
recordingStatusCallbackEvent
recordingStatusCallbackEvent te permite especificar qué cambios de estado de grabación deben generar un webhook para la URL especificada en el atributo recordingStatusCallback. Estos son los valores disponibles:
in-progress: la grabación ha comenzado.completed: la grabación está completa y disponible.absent:: la grabación está ausente y no se puede acceder a ella.
Para especificar más de un valor, sepáralos con un espacio. El valor predeterminado es: completed.
Para pausar, reanudar o detener grabaciones, consulta los documentos de la API de grabación.
En el ejemplo siguiente, se especifica que queremos que cada participante de la llamada <Dial> se represente en su propio canal de la grabación final y que la grabación comience cuando la llamada comience a sonar.
Volver a la lista de atributos
recordingTrack
El atributo recordingTrack te permite seleccionar si las pistas de audio inbound, outbound o both de la llamada deben grabarse. La pista entrante representa el audio recibido por Twilio, y la pista saliente representa el audio que Twilio genera en la llamada. El valor predeterminado es both y grabará el audio que se recibe y genera por Twilio.
Cuando se graba la pista de audio inbound o outbound, el archivo de grabación resultante siempre será monocanal. Cuando el audio se graba con both, el archivo resultante puede estar en canales separados (doble) o mezclado (mono).
Volver a la lista de atributos
referUrl
Para utilizar la función de Twilio REFER de SIP entrante, debes activar las "Enhanced Programmable SIP Features" (Funciones SIP programables mejoradas) en los ajustes de Voice de la consola.
Si la persona a la que se llama envía una solicitud REFER de SIP, se enviará una solicitud de Twilio a tu referUrl. Tu aplicación debe responder cómo manejar la transferencia. Más información sobre REFER de SIP entrante a Twilio.
Los siguientes parámetros se añaden a la solicitud de webhook de Twilio Voice estándar:
| Parámetro | Descripción |
|---|---|
| ReferTransferTarget | El número de teléfono o punto final de SIP en el que se va a transferir. |
Volver a la lista de atributos
referMethod
El atributo referMethod acepta GET o POST. Esto le dice a Twilio si debe solicitar la action URL mediante HTTP GET o POST, con POST como valor predeterminado.
Volver a la lista de atributos
ringTone
Ringtone (Tono de llamada) te permite anular el tono de llamada que Twilio reproducirá al agente de llamada mientras ejecuta un <Dial>.
Si no se especifica, Twilio reproducirá el tono o pasará el tono desde el operador móvil (si está provisto). Esto funciona de forma automática, pero puede haber casos en los que se desee una anulación.
Estos son los valores aceptados: at, au, bg, br, be, ch, cl, cn, cz, de, dk, ee, es, fi, fr, gr, hu, il, in, it, lt, jp, mx, my, nl, no, nz, ph, pl, pt, ru, se, sg, th, uk, us, us-old, tw, ve, za.
Nota: Si estás marcando un punto final de <Sip>, ringTone solo funcionará como se espera si has activado las funciones SIP programables mejorados en Twilio.
timeLimit
El atributo timeLimit establece la duración máxima de <Dial> en segundos.
Por ejemplo, cuando se establece un límite de tiempo de 120 segundos, <Dial> colgará de forma automática la llamada de la persona a la que se llama pasados dos minutos.
El límite de tiempo predeterminado para las llamadas es de 4 horas, que también es la duración máxima de una llamada, a menos que actives la función "24-Hour Maximum Call Duration" (Duración máxima de llamada de 24 horas) en General Settings (Configuración general) de Programmable Voice, en cuyo caso la duración máxima será de 24 horas.
timeout
Si se especifica un timeout, se establecerá el límite en segundos que <Dial> esperará a que la persona a la que se ha llamado responda a la llamada. Esto le dice a Twilio cuánto tiempo debe dejar sonar la llamada antes de rendirse y establecer el DialCallStatus como no-answer.
El valor predeterminado de timeout es de 30 segundos, el valor mínimo permitido es de cinco segundos y el valor máximo es de 600 segundos.
Twilio siempre añade un búfer de tiempo de espera de 5 segundos a tu <Dial>, por lo que si introduces un valor de tiempo de espera de 10 segundos, verás un tiempo de espera real más cercano a los 15 segundos.
Volver a la lista de atributos
trim
Si se establece el atributo trim atributo en trim-silence, se recortará el silencio inicial y final de los archivos de audio.
Recortar un archivo puede causar que la duración de la grabación sea ligeramente inferior a la duración de la llamada. El valor predeterminado del atributo trim es do-not-trim.
callReason
Motivo de la llamada saliente. Utilízalo para especificar el propósito de la llamada que se presenta en el teléfono de la persona a la que se llama. (Versión beta de Branded Calls [llamadas con marca])
Para obtener más información, visita la página Llamadas con marca.
Sustantivos <Dial>
Siempre puedes optar por anidar texto sin formato (una cadena que representa un número de teléfono válido) en <Dial> para indicar a Twilio un número de teléfono al que llamar:
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Dial>415-123-4567</Dial>
</Response>También puedes optar por anidar lossustantivos dentro de tu<Dial> para crear conexiones a otros tipos de dispositivos, llamadas de conferencia y colas de llamadas.
El sustantivo de un verbo de TwiML describe los números de teléfono, los puntos finales y los recursos API en los que deseas realizar una acción. Los sustantivos de TwiML son cualquier cosa sobre la que actúe el verbo (<Dial>, en este caso).
A continuación, se muestran los sustantivos que puedes utilizar con <Dial>. Cada uno es un elemento XML anidado:
| Sustantivo | Descripción |
|---|---|
| <Client> |
Describe una conexión de Twilio Client. La marcación simultánea también es posible con varios sustantivos Lee la documentación detallada de <Client> para obtener información detallada y el uso. |
| <Conference> |
Describe una conferencia que permite que dos o más participantes hablen. Conecta al interlocutor activo a una llamada de conferencia. Consulta la documentación detallada de <Conference> para ver un tutorial que muestra cómo utilizar la funcionalidad de conferencia de Twilio. |
| <Number> |
Describe un número de teléfono con atributos más complejos. Este sustantivo te permite utilizar Lee la documentación detallada de <Number> para obtener más información y el uso. |
| <Sim> |
Describe una conexión SIM de red inalámbrica programable. Consulta la documentación detallada de <Sim> para obtener más información. |
| <Sip> |
Describe una conexión SIP. Consulta la documentación detallada de <Sip> para obtener más información. |
| <Queue> |
Identifica una cola a la que debe conectarse esta llamada. Te permite conectar la llamada actual a la llamada en espera al frente de una cola determinada. Lee la documentación de <Queue> para obtener un tutorial detallado sobre cómo utilizar la funcionalidad de colas de Twilio. |
Anida uno de estos sustantivos dentro de un verbo <Dial> de esta forma:
De forma funcional, el ejemplo anterior se comporta igual como nuestro ejemplo básico en el que anidamos un número de teléfono de texto sin formato en nuestro <Dial>. Vamos a llevar este anidado del sustantivo TwiML un paso más allá.
En el ejemplo siguiente, especificaremos que queremos una grabación de doble canal para un <Dial> con un <Conference> anidado.
Este código reenviará al agente de llamada activo a una conferencia llamada myteamroom. Una grabación de doble canal de la llamada comenzará cuando comience el timbre. Después de que la llamada termine y la grabación esté lista, Twilio enviará la información de la grabación a example.com:
Usar Twimlets
Twimlets son URL alojadas por Twilio que proporcionan pequeños bits de funcionalidad usados de forma común.
- El twimlet Forward reenviará todas las llamadas de un número de Twilio a otro número de tu elección.
- El twimlet Simulring hará sonar varios números al mismo tiempo y conectará al agente de llamada a la primera persona que conteste.
- Para marcar números uno por uno hasta que uno sea contestado, usa el twimlet Find me.
¿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.
