TwiML™ Voice: <Conference>

O substantivo <Conference> do verbo <Dial> permite que você se conecte a uma sala de conferência . Tal como o substantivo <Number> permite a conexão a outro número de telefone, o substantivo <Conference> permite que você se conecte a uma sala de conferência nomeada e fale com os outros autores da chamada também conectados à sala. A conferência é comumente usada como um contêiner para chamadas ao implementar espera, transferência e interrupção.

A Twilio oferece um sistema de conferência globalmente distribuído e de baixa latência que hospeda suas conferências na região mais próxima da maioria dos participantes e tem uma capacidade máxima de 250 participantes. Ela tem um preço por participante por minuto, além do preço padrão por minuto de voz. Saiba mais sobre preços para conferências.

Recursos personalizáveis

Você decide o nome da sala e ela é atribuída à sua conta. Isso significa que qualquer autor da chamada que entrar em room1234 por meio de sua conta terminará na mesma sala de conferência, mas os autores da chamada que se conectam por meio de contas diferentes não.

Por padrão, as salas de conferência da Twilio permitem uma série de recursos úteis que podem ser ativados ou desativados com base nas suas necessidades específicas:

• As conferências não começam até que pelo menos dois participantes estejam presentes.
• Enquanto espera, a música de fundo personalizável é reproduzida.
• Quando os participantes entram e saem, sons de notificação são reproduzidos para informar os outros participantes.
• Os eventos podem ser configurados para alertar seu aplicativo sobre alterações de estado em uma conferência
• Receba um webhook quando um participante fala ou para de falar

Você pode configurar ou desativar cada um desses recursos com base em suas necessidades específicas.

Atributos do substantivo

O substantivo <Conference> dá suporte aos seguintes atributos que modificam seu comportamento:

muted

O atributo muted permite especificar se um participante pode falar na conferência. Se este atributo for definido como true, o participante só poderá ouvir as pessoas na conferência. O padrão deste atributo é false.

Para alterar o atributo muted (silenciado) de um participante da conferência durante uma chamada, use a API do participante da conferência.

beep

O atributo beep permite especificar se um bipe de notificação será reproduzido na conferência quando um participante entrar ou sair da conferência. O padrão é true.

startConferenceOnEnter

Este atributo informa a uma conferência para iniciar quando este participante entrar na conferência, se ela ainda não tiver sido iniciada. Ele é true por padrão. Se definido como false e o participante entrar em uma conferência que não começou, ele é silenciado e ouve a música de fundo até que um participante se junte onde startConferenceOnEnter seja true. Isso é útil para implementar conferências moderadas.

endConferenceOnExit

Se um participante tiver esse atributo definido como true e sair, a conferência será encerrada e todos os outros participantes serão abandonados. O padrão é false. Isso é útil para a implementar conferências moderadas que conectam duas chamadas e permitem que uma das partes da chamada continue executando o TwiML se a outra desligar.

participantLabel

Um rótulo exclusivo para o participante que será adicionado à conferência como resultado da execução do TwiML. O rótulo fornecido pode ser usado posteriormente para ler ou atualizar os atributos do participante usando a API REST da Twilio. O participantLabel deve ser exclusivo para cada um dos participantes da conferência, com um limite máximo de 128 caracteres.

jitterBufferSize

O atributo jitterBufferSize permite definir o comportamento de buffer de jitter para um participante da conferência. A conferência Twilio usa um buffer de jitter para suavizar irregularidades nos tempos de chegada dos pacotes de mídia ao misturar áudio para participantes da conferência. Esse buffer resulta em menos artefatos de áudio, mas introduz um atraso fixo para o áudio de cada participante.

Definir o valor de jitterBufferSize para small cria um buffer de 20 ms que resulta em uma latência média de aproximadamente 150 ms a 200 ms em um fluxo com jitter máximo de aproximadamente 20 ms.

Definir o valor para medium cria um buffer de 40 ms que resulta em uma latência média de aproximadamente 200 ms a 360 ms em um fluxo com jitter máximo de aproximadamente 20 ms.

O comportamento padrão de buffer de jitter large cria um buffer de 60 ms que resulta em uma latência média entre aproximadamente 300 ms e 1.000 ms em um fluxo com jitter máximo de aproximadamente 20 ms.

Picos de jitter extremamente altos podem resultar em uma latência máxima que excede a latência média em até 50%.

A definição off desativa completamente o buffer. Os pacotes com jitter relativamente baixo (<=20 ms) serão completamente descartados, mas a Twilio não adicionará latência extra durante a combinação.

O valor de buffer é uma configuração no nível do participante: o valor do participante A não se aplica ao participante B.

waitUrl

O atributo waitUrl permite especificar um URL para a música que é reproduzida antes do início da conferência. O URL pode ser MP3, WAV ou um documento do TwiML que usa <Play> ou <Say> para conteúdo. O padrão é uma seleção de música de fundo licenciada pelo Creative Commons, mas você pode substituí‐la por suas próprias músicas e mensagens. Se o waitUrl responder com TwiML, a Twilio só processará os verbos <Play>, <Say> e <Redirect>. Os verbos <Record>, <Dial> e <Gather> não são permitidos. Se desejar que nada seja reproduzido enquanto espera que a conferência inicie, especifique a string vazia (defina waitUrl para '').

Se nenhum waitUrl for especificado, a Twilio utilizará a sua própria música de espera Twimlet que lê um bucket S3 da AWS público para arquivos de áudio. O padrão para waitUrl é: http://twimlets.com/holdmusic?Bucket=com.twilio.music.classical

Observe que, se a solicitação para o waitUrl falhar, a conferência não será totalmente estabelecida. Para evitar que a chamada seja desconectada, você pode adicionar mais TwiML após a primeira <Dial> <Conference> ou fornecer de forma programática o comportamento de fallback através do callback de ação.

Este URL aponta para bucket S3 com.twilio.music.classic contendo uma seleção de músicas clássicas do Creative Commons. Aqui está uma lista de buckets S3 que reunimos com outros gêneros de música para você escolher:

waitMethod

Este atributo indica qual método HTTP usar ao solicitar o waitUrl. O padrão é 'POST'. Certifique‐se de usar 'GET' se estiver solicitando diretamente arquivos de áudio estáticos, como WAV ou MP3, para que a Twilio possa armazenar os arquivos em cache corretamente.

maxParticipants

Este atributo indica o número máximo de participantes que você deseja permitir dentro de uma sala de conferência nomeada. O número máximo de participantes é 250.

record

O atributo record permite gravar uma <Conference> inteira. Quando definido como record-from-start, a gravação começa quando os dois primeiros participantes são conectados. A música de espera nunca é gravada. Se for fornecido um URL recordingStatusCallback, a Twilio fará uma solicitação ao URL especificado com os detalhes da gravação quando a gravação estiver disponível para acesso.

region

O atributo region especifica a região onde a Twilio deve combinar a conferência. Especificar um valor para a região substitui a lógica de seleção de região automática da Twilio e só deve ser usado se você tiver certeza de que entende onde suas conferências devem ser combinadas. A Twilio define o parâmetro de região do primeiro participante que especifica o parâmetro e ignora o parâmetro dos participantes subsequentes.

trim

O atributo trim permite especificar se você deseja cortar o silêncio inicial e final dos seus arquivos de áudio. O padrão de trim é trim-silence, que remove qualquer silêncio no início ou no final da gravação. Isso pode fazer com que a duração da gravação seja ligeiramente inferior à duração da chamada.

coach

O coach aceita um SID de chamada de uma chamada que está atualmente conectada a uma conferência em andamento. Especificar um SID de chamada que não existe ou que não está mais conectado à conferência resultará em falha na chamada para o URL de ação e na exibição de um erro 13240.

statusCallbackEvent

O atributo statusCallbackEvent permite especificar quais alterações de estado da conferência devem gerar um webhook para o URL especificado no atributo statusCallback. Os valores disponíveis são start, end, join, leave, mute, hold, modify, speaker e announcement. Para especificar vários valores, separe‐os com um espaço. Os eventos são definidos pelo primeiro participante a entrar na conferência. Os statusCallbackEvents subsequentes serão ignorados. Se você especificar eventos de conferência, poderá ver um log dos eventos disparados para uma determinada conferência em logs de conferência no console.

statusCallback

O atributo statusCallback toma um URL como argumento. Os eventos de conferência especificados no parâmetro statusCallbackEvent serão enviados para este URL.

Os parâmetros contidos nas solicitações de eventos são detalhados abaixo.

statusCallbackMethod

O método HTTP que a Twilio deve usar ao solicitar o URL acima. O padrão é POST

Parâmetros da solicitação

A Twilio passará os seguintes parâmetros com sua solicitação para o URL statusCallback. Para eventos de anúncio dos participantes, a Twilio passará parâmetros de solicitação adicionais relacionados aos participantes se o participante que está sendo anunciado ainda estiver presente na conferência.

recordingStatusCallback

O atributo recordingStatusCallback usa um URL relativo ou absoluto como um argumento.

Se a gravação de uma conferência foi solicitada através do atributo record e um URL de recordingStatusCallback for fornecido, a Twilio fará uma solicitação GET ou POST para o URL especificado quando a gravação estiver disponível para acesso.

Parâmetros da solicitação

A Twilio passará os seguintes parâmetros com sua solicitação para o URL recordingStatusCallback:

recordingStatusCallbackMethod

Este atributo indica qual método HTTP usar ao solicitar o recordingStatusCallback. O padrão é 'POST'.

recordingStatusCallbackEvent

Este atributo permite especificar quais alterações do status da gravação devem gerar um webhook para o URL especificado no atributo recordingStatusCallback. Os valores disponíveis são in-progress, completed, absent. Para especificar vários valores, separe‐os com um espaço. O padrão é completed.

Veja abaixo os detalhes dos eventos de alteração do status:

eventCallbackUrl

Este parâmetro foi descontinuado em favor de recordingStatusCallback. Fornecer um recordingStatusCallback não resultará em um eventCallback.

O atributo 'eventCallbackUrl' usa um URL como argumento. Quando a conferência é encerrada, a Twilio faz uma solicitação POST para este URL com os parâmetros de evento conference-record-end do statusCallback.

Exemplos

Exemplo 1: Conferência simples

Por padrão, o primeiro autor da chamada a executar este TwiML entraria na sala de conferências chamada Room 1234 e ouviria a música de espera predefinida. Quando o próximo autor da chamada executasse este TwiML, ele entraria na mesma sala de conferência e a conferência começaria. A música de fundo padrão é encerrada, o bipe de notificação é reproduzido e todas as partes podem se comunicar.

Exemplo 2: Conferência moderada

Primeiro, você pode colocar várias pessoas na conferência, especificando que a conferência ainda não deve começar:

Cada pessoa ouvirá a música de espera enquanto aguarda. Quando o "moderador" ou o organizador da conferência ligar, você poderá especificar que a conferência deve começar:

Observe também que como o moderador tem "endConferenceOnExit='true'" definido, quando o moderador desligar, a conferência será encerrada e o <Dial> de cada participante será concluído.

Exemplo 3: Participar de uma conferência com eventos

Este código o colocará em uma conferência onde os eventos serão disparados nas alterações de estado start, end, join, leave, mute e hold do participante e da conferência.

Exemplo 4: Participar de uma conferência silenciado

Este código permite que os participantes entrem na sala de conferência silenciados. Eles podem ouvir o que os participantes com som ativo estão dizendo, mas ninguém consegue ouvi-los. O atributo silenciado pode ser ativado ou desativado em tempo real por meio da API REST.

Exemplo 5: Conectando ligações

Às vezes, você só quer conectar duas chamadas sem nenhum recurso adicional. Com essa configuração mínima de atributos de conferência, nenhuma música de fundo ou bipes são reproduzidos, os participantes podem falar imediatamente à medida que entram e a conferência termina imediatamente se um dos participantes desligar. Isso é útil para casos em que é necessário fazer a conexão entre duas chamadas existentes, como você faria com Discagem.

Exemplo 6: Chamada em espera

Esse código coloca o primeiro autor da chamada em uma sala de espera, onde ele ouvirá música. É como se ele estivesse em espera, aguardando que um agente ou operador o ajude.

Então, quando o operador ou agente estiver pronto para falar com ele, a chamada seria executada:

Esse código juntaria o operador com a pessoa em espera. Como a conferência começa quando eles entram, a maravilhosa música de espera que a primeira pessoa estava ouvindo vai parar e as duas pessoas começarão a falar. Já que "beep='false'", o autor da chamada não ouvirá um som quando o agente atender, o que provavelmente é apropriado para este caso de uso. Quando o operador desliga, o 'endConferenceOnExit’ fará com que a conferência seja encerrada.

Exemplo 7: Combinando com os atributos Discagem

Como conferência é um elemento de Discagem, você pode usar todos os atributos de Discagem junto com conferência (exceto callerId e timeout, que não têm efeito). Você pode definir um timeLimit, após o qual você será removido da conferência. É possível ativar o hangupOnStar, que permite sair de uma conferência pressionando a tecla * (asterisco). Você pode especificar uma ação para que, após sair de uma sala de conferência, a Twilio envie para a ação e seu servidor Web possa responder com o novo TwiML e continuar a chamada.

Exemplo 8: Gravar uma conferência

Este código permite gravar uma conferência inteira começando quando os dois primeiros participantes são conectados e envia um recordingStatusCallback quando a gravação da conferência estiver disponível para acesso.