TwiML™ Voice: <Conference>

El sustantivo <Conference> del verbo <Dial> te permite conectarte a una sala de conferencia . De forma muy similar como el sustantivo <Number> te permite conectarse a otro número de teléfono , el sustantivo <Conference> te permite conectarte a una sala de conferencias nombrada y hablar con los otros agentes de llamada que también se han conectado a esa sala. La conferencia se utiliza por lo usual como contenedor de llamadas cuando se implementa la espera, transferencia e intrusión.

Twilio ofrece un sistema de conferencias de baja latencia y distribución global que aloja tus conferencias en la región más cercana a la mayoría de tus participantes y tiene una capacidad máxima de 250 participantes. Tiene un precio por participante por minuto, además del precio por minuto de voz estándar. Obtén más información sobre precios de conferencias.

Funciones personalizables

El nombre de la sala depende de ti y lleva el nombre de tu cuenta. Esto significa que cualquier agente de llamada que se une a room1234 mediante tu cuenta terminará en la misma sala de conferencias, pero las personas que se conecten mediante cuentas diferentes no lo harían.

De forma predeterminada, las salas de conferencias Twilio habilitan una serie de funciones útiles que se pueden activar o desactivar en función de tus necesidades particulares:

* Las conferencias no comenzarán hasta que al menos dos participantes se unan. Mientras se espera, se reproduce música de fondo personalizable. * Cuando los participantes se unen y se van, se reproducen sonidos de notificación para informar a los demás participantes. * Los eventos se pueden configurar para alertar a tu aplicación de los cambios de estado en una conferencia. * Recibir un webhook cuando un participante habla o deja de hablar.

Puedes configurar o desactivar cada una de estas funciones según tus necesidades particulares.

Atributos del sustantivo

El sustantivo <Conference> admite los siguientes atributos que modifican su comportamiento:

muted

El atributo muted te deja especificar si un participante puede hablar en la conferencia. Si este atributo se establece en true, el participante solo podrá escuchar a personas en la conferencia. Este atributo de forma predeterminada es false.

Para cambiar el atributo de silenciado de un participante de conferencia durante una llamada, utiliza API de participante de conferencia.

beep

El atributo beep te permite especificar si se reproducirá un pitido de notificación en la conferencia cuando un participante se una o salga de la conferencia. De forma predeterminada es true.

startConferenceOnEnter

Este atributo indica a una conferencia que se inicie cuando este participante se una a la conferencia, si aún no se ha iniciado. Esto es true de forma predeterminada. Si es false y el participante se une a una conferencia que no ha comenzado, se silencian y oyen música de fondo hasta que un participante se une en que startConferenceOnEnter es true. Esto es útil para implementar conferencias moderadas.

endConferenceOnExit

Si un participante tiene este atributo establecido en true, cuando ese participante se vaya, la conferencia finalizará y el resto de los participantes se retirarán. De forma predeterminada es false. Esto es útil para implementar conferencias moderadas que unen dos llamadas y permiten que cualquiera de los tramos de la llamada continúe ejecutando TwiML si el otro cuelga.

participantLabel

Una etiqueta única para el participante que se añadirá a la conferencia como resultado de la ejecución de TwiML. La etiqueta que se proporciona aquí puede utilizarse después para leer o actualizar los atributos de los participantes mediante la API REST de Twilio. El participantLabel debe ser único para todos los participantes de la conferencia y hay un límite máximo de 128 caracteres.

jitterBufferSize

El atributo jitterBufferSize te permite establecer el comportamiento del buffer de fluctuación para un participante de conferencia. La conferencia de Twilio utiliza un búfer de fluctuación para suavizar las irregularidades en los tiempos de llegada de los paquetes de medios al mezclar audio de los participantes de la conferencia. Este búfer produce menos artefactos de audio, pero introduce un retraso fijo para el audio de cada participante.

Si se establece el valor de jitterBufferSize en small se creará un búfer de 20 ms que dará como resultado una latencia promedio de ~150 ms a ~200 ms en un flujo con una fluctuación máxima de ~20 ms.

Si se establece el valor en medium, se creará un búfer de 40 ms que dará como resultado una latencia promedio de ~200 ms a ~360 ms en un flujo con una fluctuación máxima de ~20 ms.

El ajuste large, que es el comportamiento predeterminado del búfer de fluctuación, creará un búfer de 60 ms que da como resultado una latencia promedio de ~300 ms a ~1000 ms en un flujo con una fluctuación máxima de ~20 ms.

Los picos de fluctuación extremadamente alta pueden dar como resultado que la latencia máxima supere la latencia promedio hasta en un 50 %.

El ajuste off desactiva por completo el buffer y los paquetes con fluctuación relativamente baja ( <=20 ms) serán descartados por completo, pero Twilio no añadirá latencia adicional al mezclar.

El valor del búfer es un ajuste a nivel de participante, el valor para el participante A no se aplica al participante B.

waitUrl

El atributo waitUrl permite especificar una URL de la música que se reproduce antes de que se inicie la conferencia. La URL puede ser un MP3, un WAV o un documento TwiML que utilice <Play> o <Say> para el contenido. De forma predeterminada, se muestra una selección de música de fondo con licencia de Creative Commons, pero puedes sustituirla por tu propia música y mensajes. Si el waitUrl responde con TwiML, Twilio solo procesará los verbos <Play>, <Say> y <Redirect>. Los verbos <Record> , <Dial>, y <Gather> no están permitidos. Si no deseas que se reproduzca nada mientras esperas que comience la conferencia, especifica la cadena vacía (establece waitUrl en '').

Si no se especifica waitUrl, Twilio usará su propio holdmusic Twimlet que lee un AWS S3 Bucket público para archivos de audio. El waitUrl predeterminado es: http://twimlets.com/holdmusic?Bucket=com.twilio.music.classical

Ten en cuenta que si la solicitud a tu waitUrl falla, la conferencia no se establecerá por completo. Para evitar que la llamada se desconecte, puedes añadir un TwiML adicional después del <Dial> <Conference> inicial, o bien proporcionar mediante programación el comportamiento de respaldo mediante la acción de devolución de llamada.

Esta URL apunta a S3 bucket com.twilio.music.classical, que contiene una buena selección de música clásica de Creative Commons. Aquí hay una lista de S3 buckets que hemos reunido con otros géneros musicales para que elijas:

waitMethod

Este atributo indica que método de HTTP usar cuando se solicita waitUrl. El valor predeterminado es 'POST'. Asegúrate de usar 'GET' si estás solicitando archivos de audio estáticos de forma directa como WAV o MP3 para que Twilio almacene de forma correcta los archivos en caché.

maxParticipants

Este atributo indica el número máximo de participantes que deseas permitir en una sala de conferencias designada. El número máximo de participantes es 250.

record

El atributo record te permite grabar una <Conference> entera. Cuando se establece en record-from-start, la grabación comienza cuando los dos primeros participantes son unidos. La música de fondo nunca se graba. Si se da una URL recordingStatusCallback, Twilio hará una solicitud a la URL especificada con detalles de la grabación cuando se pueda acceder a esta última.

region

El atributo region especifica la región donde Twilio debe mezclar la conferencia. La especificación de un valor para la región anula la lógica de selección automática de región de Twilio y solo debe utilizarse si estás seguro de que entiendes dónde deben mezclarse tus conferencias. Twilio ajusta el parámetro de región del primer participante que especifica el parámetro e ignorará el parámetro de los participantes subsiguientes.

trim

El atributo trim te permite especificar si deseas recortar el silencio inicial y final de los archivos de audio. El valor predeterminado de trim es trim-silence, que elimina cualquier silencio al principio o al final de la grabación. Esto puede provocar que la duración de la grabación sea ligeramente inferior a la duración de la llamada.

coach

Coach acepta un SID de llamada de una llamada que está conectada a una conferencia en curso en la actualidad. Si se especifica un SID de llamada que no existe o que ya no está conectado a la conferencia, la llamada fallará a la URL de acción y se generará un error 13240.

statusCallbackEvent

El atributo statusCallbackEvent te permite especificar qué cambios de estado de la conferencia deben generar un webhook para la URL especificada en el atributo statusCallback. Los valores disponibles son start, end, join, leave, mute, hold, modify, speaker y announcement. Para especificar varios valores, sepáralos con un espacio. Los eventos los establece el primer participante que se une a la conferencia; los eventos statusCallbackEvents posteriores se ignorarán. Si especificas eventos de conferencia, puedes ver un registro de los eventos activados en una conferencia determinada en registros de conferencia en la consola.

statusCallback

El atributo statusCallback toma una URL como argumento. Los eventos de conferencia especificados en el parámetro statusCallbackEvent se enviarán a esta URL.

A continuación, se detallan los parámetros contenidos en las solicitudes de eventos.

statusCallbackMethod

El método HTTP que Twilio debe utilizar cuando solicita la URL anterior. El valor predeterminado es POST

Parámetros de solicitud

Twilio transferirá los siguientes parámetros con su solicitud a la URL statusCallback. Para los eventos de anuncio de participantes, Twilio transferirá parámetros de solicitud adicionales relacionados con los participantes si el participante al que se anuncia aún está presente en la conferencia.

recordingStatusCallback

El atributo acordingStatusCallback toma una dirección URL relativa o absoluta como argumento.

Si se solicitó una grabación de conferencia mediante el atributo record y se da una URL de concordingStatusCallback, Twilio hará una solicitud GET o POST a la URL especificada cuando se pueda acceder a la grabación.

Parámetros de solicitud

Twilio transferirá los siguientes parámetros con su solicitud a la URL de recordingStatusCallback:

recordingStatusCallbackMethod

Este atributo indica qué método HTTP se debe utilizar cuando se solicita acordingStatusCallback. El valor predeterminado es 'POST'.

recordingStatusCallbackEvent

Este atributo permite especificar qué cambios de estado de grabación deben generar un webhook para la URL especificada en el atributo concordingStatusCallback. Los valores disponibles son in-progress, completed, absent. Para especificar varios valores, sepáralos con un espacio. El valor predeterminado es completed.

Estos son los detalles de los eventos de cambio de estado:

eventCallbackUrl

Este parámetro ha quedado obsoleto en favor de recordingStatusCallback. Si se proporciona una recordingStatusCallback, no se producirá ningún eventCallback.

El atributo 'eventCallbackUrl' toma una dirección URL como argumento. Cuando finalice la conferencia, Twilio hará una solicitud POST a esta URL con los parámetros de evento conference-record-end de statusCallback.

Ejemplos

Ejemplo 1: una conferencia simple

Por defecto, el primer agente de llamada que ejecute este TwiML se uniría a la sala de conferencias llamada Room 1234 y escucharía la música de espera de forma predeterminada. Cuando el siguiente agente de llamada ejecuta este TwiML, se uniría a la misma sala de conferencias y la conferencia comenzaría . La música de fondo predeterminada finaliza, se reproduce el pitido de notificación y todas las partes pueden comunicarse.

Ejemplo 2: una conferencia moderada

En primer lugar, puedes colocar a una cantidad determinada de personas en la conferencia, especificando que la conferencia no debería comenzar todavía:

Cada persona escuchará música en espera mientras espera. Cuando el "moderador" o el organizador de la conferencia llaman, puedes especificar que la conferencia debe comenzar:

También ten en cuenta que como el moderador tiene establecido "endConferenceOnExit='true'", entonces, cuando el moderador cuelgue , la conferencia terminará y el <Dial> de cada participante se completará.

Ejemplo 3: unirse a una conferencia de evento

Este código te pondrá en una conferencia en la que los eventos se activarán en los cambios de estado de inicio, fin, unirse, salir, silenciar y espera del participante y la conferencia.

Ejemplo 4: unirse a una conferencia en silencio

Este código permite a los participantes unirse a la sala de conferencias en silencio. Pueden oír lo que dicen los participantes que no están en silencio, pero nadie puede oírlos. El atributo de silencio se puede activar o desactivar en tiempo real mediante la API REST.

Ejemplo 5: unir llamadas

A veces solo quieres unir dos llamadas sin tanta parafernalia. Con esta configuración mínima de atributos de conferencia, no se reproduce música de fondo ni pitidos, los participantes pueden hablar de inmediato mientras se unen y la conferencia finaliza de inmediato si alguno de los participantes cuelga. Esto resulta útil en casos como unir dos llamadas existentes, de forma similar a como lo haría con Dial.

Ejemplo 6: Llamada en espera

Este código coloca al primer agente de llamada en una sala de espera, en la que escuchará música. Es como si estuvieran en espera, esperando a que un agente u operador los ayude.

A continuación, cuando el operador o agente está listo para hablar con ellos, se ejecutaría su llamada:

Este código uniría al operador con la persona que estaba en espera. Debido a que la conferencia comienza cuando entran, la maravillosa música de fondo que la primera persona escuchó se detendrá y las dos personas comenzarán a hablar. Debido a que "beep='false'", el agente de llamada no escuchará una campana cuando el agente responda, lo que probablemente sea apropiado para este caso de uso. Cuando el operador cuelga, entonces "endConferenceOnExit" hará que la conferencia finalice

Ejemplo 7: combinación con atributos de Dial

Debido a que Conference es un elemento de Dial, puedes seguir utilizando todos los atributos de Dial junto con Conference (con la excepción de callerId y timeout, que no tienen efecto). Puedes establecer un timeLimit, tras el cual se te eliminará de la conferencia. Puedes activar hangupOnStar, lo que te permite salir de una conferencia pulsando la tecla *. Puedes especificar una acción, de modo que después de salir de la sala de conferencias Twilio realices la acción y tu servidor web pueda responder con nuevo TwiML y continuar tu llamada.

Ejemplo 8: grabar de una conferencia

Este código te permite grabar una conferencia completa que se inicia cuando los dos primeros participantes están unidos y enviará una recordingStatusCallback cuando se pueda acceder a la grabación de la conferencia.