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.
Por motivos de cumplimiento, no utilices datos personales (también conocidos como información personal identificable), como números de teléfono, direcciones de correo electrónico, el nombre de una persona o cualquier otra información confidencial cuando les asignes un nombre a las conferencias
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:
Nombre de atributo | Valores permitidos | Valor predeterminado |
---|---|---|
muted | true, false | false |
beep | true, false, onEnter, onExit | true |
startConferenceOnEnter | true, false | true |
endConferenceOnExit | true, false | false |
participantLabel | Una etiqueta para el participante de la conferencia | Ninguno |
jitterBufferSize | small, medium, large, off | large |
waitUrl | URL de TwiML, cadena vacía | Música de espera de Twilio predeterminada |
waitMethod | GET o POST | POST |
maxParticipants | Número entero positivo <= 250 | 250 |
record | do-not-record o record-from-start | do-not-record |
region | us1, ie1, de1, sg1, br1, au1, jp1 | Ninguno |
trim | trim-silence o do-not-trim | trim-silence |
coach | Un SID de llamada | Ninguno |
statusCallbackEvent | start, end, join, leave, mute, hold, modify, speaker, announcement | Ninguno |
statusCallback | URL relativa o absoluta | Ninguno |
statusCallbackMethod | GET, POST | POST |
recordingStatusCallback | URL relativa o absoluta | Ninguno |
recordingStatusCallbackMethod | GET, POST | POST |
recordingStatusCallbackEvent | in-progress, completed, absent | completed |
eventCallbackUrl | URL relativa o absoluta | Ninguno |
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
.
Valor | Comportamiento |
---|---|
true | Valor predeterminado. Reproduce un pitido cuando un participante se une y cuando un participante se va. |
false | Desactiva los pitidos para cuando los participantes se unen y salen. |
onEnter | solo reproduce un pitido cuando se une un participante. El pitido no se reproducirá cuando el participante salga. |
onExit | No reproducirá un pitido cuando un participante se una; solo reproducirá un pitido cuando el participante salga. |
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.
Si ya existe un participante con la misma etiqueta en la conferencia, se informará de la notificación de error 16025 y se podrá ver en la consola de Twilio. La llamada no se agregará a la conferencia y en su lugar continuará con el siguiente verbo TwiML.
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.
Evento | Descripción |
---|---|
start | La conferencia ha comenzado y el audio se mezcla entre todos los participantes. Esto ocurre cuando hay al menos dos participantes en la conferencia, y al menos uno de los participantes tiene startConferenceOnEnter="true" . |
end | El último participante ha abandonado la conferencia o un participante con endConferenceOnExit="true" abandona la conferencia. |
join | Un participante se ha unido a la conferencia. |
leave | Un participante ha abandonado la conferencia. |
mute | Un participante se ha silenciado o quitado el silencio. |
hold | Un participante se puesto en espera o ya no está en espera. |
modify | Se ha modificado al menos uno de los atributos de un participante: BeepOnExit , EndConferenceOnExit , Coaching , WaitUrl |
speaker | Un participante ha comenzado o dejado de hablar. |
announcement | Un participante o conferencia ha finalizado o ha fallado. En la actualidad, el evento announcement-fail solo se enviará si hay un error interno de Twilio. Estamos trabajando a fin de agregar más fallas al evento advertisement-fail para permitir a los desarrolladores puedan depurar el problema. |
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.
La URL de statusCallback
la establece el primer participante que se una a la conferencia; el ajuste posterior de statusCallback
se ignorará.
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.
Parámetro | Ejemplo | Enviado en |
---|---|---|
ConferenceSid | CFe08c870b500f6e44a9ad184defd1f391 | Enviado en: Todos |
FriendlyName | MyConf | Enviado en: Todos |
AccountSid | AC25e16e9a716a4a8617a7c83f58e30482 | Enviado en: Todos |
SequenceNumber | 1 | Enviado en: Todos |
Timestamp | Thu, 1 Jun 2017 20:48:32 +0000 | Enviado en: Todos |
StatusCallbackEvent | conference-end conference-start participant-leave participant-join participant-mute participant-unmute participant-hold participant-unhold participant-modify participant-speech-start participant-speech-stop announcement-end announcement-fail |
Enviado en: join, leave, start, end, mute, hold, modify, speaker, announcement |
CallSid | CA25e16e9a716a4a1786a7c83f58e30482 | Enviado en: join, leave, mute, hold, modify, speaker, announcement (en anuncios de participantes) |
Muted | true, false | Enviado en: join, leave, mute, hold, modify, speaker, announcement (en anuncios de participantes) |
Hold | true, false | Enviado en: join, leave, mute, hold, modify, speaker, announcement (en anuncios de participantes) |
Coaching | true, false | Enviado en: join, leave, mute, hold, modify, speaker, announcement (en anuncios de participantes) |
EndConferenceOnExit | true, false | Enviado en: join, leave, mute, hold, modify, speaker, announcement (en anuncios de participantes) |
StartConferenceOnEnter | true, false | Enviado en: join, leave, mute, hold, modify, speaker, announcement (en anuncios de participantes) |
CallSidEndingConference | SID de llamada del participante que termino la conferencia (si corresponde) | Enviado en: end |
ParticipantLabelEndingConference | Etiqueta del participante que termino la conferencia (si corresponde) | Enviado en: end |
ReasonConferenceEnded | conference-ended-via-api last-participant-kicked last-participant-left participant-with-end-conference-on-exit-kicked participant-with-end-conference-on-exit-left |
Enviado en: end |
Reason | Un mensaje que indica por qué termino la conferencia | Enviado en: end |
ReasonAnnouncementFailed | Un mensaje que indica por qué fallo el anuncio | Enviado en: announcement |
AnnounceUrl | La URL utilizada para el anuncio | Enviado en: announcement |
EventName* | conference-record-end | Enviado en: conference-record-end |
RecordingUrl* | https://api.twilio.com/2010-04-01/Accounts/AC123/Recordings/RE234 | Enviado en: conference-record-end |
Duration* | 6 | Enviado en: conference-record-end |
RecordingFileSize* | 90786 | Enviado en: conference-record-end |
Todos los parámetros conference-record-end
anteriores han sido obsoletos a favor de recordingStatusCallback
, que es el enfoque preferido para recibir información relacionada con la grabación. Si se proporciona un recordingStatusCallback
, no se producirán devoluciones de llamada de conference-record-end
.
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
:
Parámetro | Descripción |
---|---|
AccountSid | El identificador único de la cuenta responsable de esta grabación. |
ConferenceSid | Identificador exclusivo de la conferencia asociada a la grabación. |
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 | La 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. Solo se admite el canal 1 para las grabaciones de conferencia. |
RecordingStartTime | La marca de hora de inicio de la grabación. |
RecordingSource | El método de inicio utilizado para crear esta grabación. Conference se devuelve para grabaciones de conferencia. |
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:
Parámetro | Descripción |
---|---|
in-progress | Se ha iniciado la grabación |
completed | La grabación se ha completado y se puede acceder a ella |
absent | La grabación está ausente y no se puede acceder a ella |
Para pausar o reanudar grabaciones de conferencia, consulta la documentación de la API de grabación.
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.
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.
¿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.