TwiML™ Voice: <Refer>
Durante una llamada SIP programable, el verbo <Refer> de TwiML instruye a Twilio para iniciar una SIP Refer (es decir, transferencias) hacia una infraestructura SIP y maneja cualquier mensaje NOTIFY. También puedes invocar el verbo utilizando la API REST.
El verbo <Refer> se puede invocar tanto en llamadas SIP entrantes como salientes. Por ejemplo, en una llamada SIP entrante a un dominio SIP de Twilio, es posible que desees transferir al agente de llamada a tu infraestructura SIP interna o heredada. Cuando se inicia el verbo <Refer>, Twilio instruye a tu dispositivo SIP para que inicie una nueva llamada al sistema externo y reemplace el tramo de Twilio con esa nueva llamada.
Puedes iniciar un <Refer> en cualquier momento de la duración de una llamada. Por ejemplo, con una llamada SIP saliente creada por el sustantivo <Sip> o la API REST de Twilio a un dominio SIP, se puede utilizar en cualquier punto para transferir al agente de llamada de vuelta a tu infraestructura SIP interna o heredada. Cuando se inicia el verbo <Refer>, Twilio instruye a tu dispositivo SIP para que inicie una nueva llamada al sistema externo y reemplace el tramo de Twilio con esa nueva llamada.
<Refer> solo es compatible en los tramos de llamada SIP porque el método REFER es una función específica de SIP. Los tipos de tramos que no son SIP, como las llamadas PSTN y Twilio Client, no son compatibles y producirán un error. Para obtener más información sobre lo que constituye un tramo de llamada SIP, consulta Comprender los tramos de llamada a continuación.
El ejemplo siguiente muestra un <Refer> establecido en un tramo de llamada entrante:
Una vez iniciado, el verbo <Refer> generará un mensaje REFER de SIP con el URI de SIP de destino especificado mediante el sustantivo <Sip>. Si el punto final SIP acepta la solicitud de REFER, Twilio detectará los mensajes de NOTIFY de SIP desde el punto final para monitorear el estado de la nueva llamada iniciada en respuesta a REFER. Twilio informará de estos a tu aplicación como parámetros a la URL de acción, si se especifica.
En el ejemplo siguiente, se muestra el uso más básico de <Refer>.
Atributos de <Refer>:
| Nombre del atributo | Valores permitidos | Valor predeterminado |
| action | URL relativa o absoluta | Ninguno |
| method | GET, POST |
POST |
action
El atributo action acepta una dirección URL como argumento. Esta URL le dice a Twilio dónde hacer una solicitud POST o GET después de que el verbo <Refer> termine de ejecutarse.
La solicitud de Twilio a esta URL puede incluir los siguientes parámetros adicionales:
| Parámetro | Descripción |
|
|
Similar al parámetro CallStatus, proporciona a la aplicación nuestra comprensión (basada en mensajes de NOTIFY de SIP) del estado de la nueva llamada creada en respuesta a REFER. Si la REFER falla o el punto final no envía ninguna solicitud NOTIFY, este parámetro se omitirá. |
|
|
El código de respuesta SIP recibido en respuesta a la solicitud REFER que Twilio envía al punto final de SIP. |
|
|
Este es el último código de respuesta SIP recibido en el tramo referido, según se determina examinando los mensajes NOTIFY de SIP. Por ejemplo, si el punto final de SIP inició una nueva llamada, pero recibió una respuesta 404 de SIP debido a que no se encontró el destino, este parámetro se establecería en "404". Si la REFER falla o el punto final no envía ninguna solicitud NOTIFY, este parámetro se omitirá. |
Ten en cuenta que aquí solo se muestran los parámetros específicos de <Refer>. Twilio también enviará los parámetros estándar de TwiML Voice en la solicitud.
Para ilustrar mejor cómo funcionan los parámetros de <Refer>, hemos proporcionado algunos ejemplos de situaciones:
- Twilio emite un REFER y el punto final de SIP inicia con éxito una nueva llamada al destino de transferencia:
- ReferCallStatus: "in-progress"
- ReferSipResponseCode: "202"
- NotifySipResponseCode: "200"
- Twilio emite un REFER y el punto final de SIP inicia una nueva llamada al destino de transferencia. Sin embargo, la nueva llamada falla con un error:
- ReferCallStatus: "busy" (o "failed", según el valor de NotifySipResponseCode)
- ReferSipResponseCode: "202"
- NotifySipResponseCode: "486"
- Twilio emite un REFER, pero el punto final de SIP responde al REFER con un error:
- ReferCallStatus: "failed"
- ReferSipResponseCode: "405"
- El agente de llamada cuelga antes de que la transacción de
<Refer>se haya completado:- ReferCallStatus: "canceled"
- ReferSipResponseCode: "202"
- NotifySipResponseCode: "180"
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.
Comprender los tramos de llamada
Debido a que <Refer> es una función específica de SIP, solo se puede utilizar en los tramos de llamada SIP. En la situación típica de IVR, solo habrá un tramo de llamada hacia o desde Twilio, como una llamada entrante a un número de teléfono Twilio o dominio de SIP, o una llamada saliente iniciada por la API REST de Twilio. En estos casos, siempre que la llamada sea entre Twilio y un dispositivo SIP, se puede utilizar <Refer>. Por lo tanto, las llamadas con las SID CAaaaa y CAbbbb son tramos de llamada SIP en los que se permite el verbo <Refer>.
En una situación de llamada conectada, como cuando se usa el verbo <Dial>, puede haber dos tramos con Twilio como se muestra en la siguiente situación:
En el flujo de llamadas anterior, la llamada con la SID CAdddd es un tramo de llamada SIP en el que se permite el verbo <Refer>. Invocar <Refer> en CAcccc produciría un error.
Transferir contexto mediante encabezados SIP
Cuando se utiliza <Refer> para transferir a un agente de llamada entre sistemas internos independientes, es posible que desees transmitir información contextual sobre la llamada. Por ejemplo, si estás creando una IVR en Twilio que recoge el número de cuenta de un cliente y el motivo de la llamada antes de transferir la llamada a un call center, es probable que desees pasar la información de cuenta capturada por la IVR al sistema del call center. Esta información contextual se transfiere a menudo en encabezados SIP.
Twilio te permite especificar cualquier URI de SIP válido dentro del sustantivo <Sip> que se utilizará como destino de REFER. Se puede utilizar el mecanismo SIP estándar para especificar encabezados en un URI de SIP, suponiendo que el punto final o el dispositivo respete los encabezados del URI de destino cuando se sigue el REFER.
Cualquier encabezado SIP permitido se puede transferir en el URI, siempre que el punto final o el dispositivo soporte el estampado del encabezado.
Monitorear el estado de las llamadas remitidas mediante la URL de acción
Cuando los puntos finales de SIP reciben una solicitud de REFER, inician una nueva llamada al URI de SIP de destino especificado en la solicitud. La transferencia, por lo general, no se completa hasta que la nueva llamada se establece por completo. La mayoría de los puntos finales de SIP proporcionan información sobre el progreso de la nueva llamada al transmisor mediante el mecanismo de NOTIFY de SIP. Si la transferencia falla, el punto final SIP, por lo general, reanudará la llamada original con la app de Twilio.
El verbo <Refer> se suscribirá de forma automática a los mensajes NOTIFY de SIP del punto final y los detectará. El verbo esperará un mensaje NOTIFY final que indique que la llamada se ha realizado con éxito o no y, a continuación, continuará la llamada invocando la URL de acción especificada. Si se omite el parámetro de acción, Twilio invocará el siguiente verbo en tu documento TwiML. Si no hay más verbos que procesar, la llamada Twilio finalizará.
En función de los parámetros transferidos a la URL de acción, puedes reanudar la gestión de la llamada en consecuencia si la transferencia falla (por ejemplo, si ReferCallStatus no es "in-progress").
El verbo <Refer> volverá una vez que se produzca una de las siguientes circunstancias:
- Twilio recibe un mensaje NOTIFY de SIP que indica que la nueva llamada ha recibido una respuesta 200 OK o fallida.
- El punto final SIP finaliza o agota el tiempo de espera de la suscripción a NOTIFY.
- Se cuelga la llamada a Twilio.
¿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.
