You are viewing the Portuguese (Brazil) site, but your language preference is set to English. Switch to English site →

Menu

Expand
Classifique esta página:

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 motivos de conformidade, não use dados pessoais (também conhecidos como informação pessoalmente identificável), como números de telefone, endereços de e-mail, nome de uma pessoa ou qualquer outra informação confidencial ao nomear as conferências

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:

Nome do atributo Valores permitidos Valor padrão
muted true, false false
beep true, false, onEnter, onExit true
startConferenceOnEnter true, false true
endConferenceOnExit true, false false
participantLabel um rótulo para o participante da conferência nenhum
jitterBufferSize small, medium, large, off large
waitUrl URL do TwiML, string vazia música padrão de espera da Twilio
waitMethod GET ou POST POST
maxParticipants número inteiro positivo <= 250 250
record do-not-record ou record-from-start do-not-record
region us1, ie1, de1, sg1, br1, au1, jp1 nenhum
trim trim-silence ou do-not-trim trim-silence
coach um SID da chamada nenhum
statusCallbackEvent start, end, join, leave, mute, hold, modify, speaker, announcement nenhum
statusCallback URL relativo ou absoluto nenhum
statusCallbackMethod GET, POST POST
recordingStatusCallback URL relativo ou absoluto nenhum
recordingStatusCallbackMethod GET, POST POST
recordingStatusCallbackEvent in-progress, completed, absent completed
eventCallbackUrl URL relativo ou absoluto nenhum

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.

Valor Comportamento
true Padrão. Reproduz um bipe quando um participante entra e sai.
false Desativa os bipes para quando os participantes entram e saem.
onEnter Reproduz um bipe apenas quando o participante entra. O bipe não será reproduzido quando o participante sair.
onExit Não reproduz um bipe quando um participante se junta; reproduz um bipe apenas quando o participante sai.

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.

Se um participante com o mesmo rótulo já existir na conferência, a notificação de erro 16025 será relatada e visível no Console da Twilio. A chamada não será adicionada à conferência. Em vez disso, ela continuará para o próximo verbo do TwiML.

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 trimtrim-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.

Evento Descrição
start A conferência começou e o áudio está sendo combinado entre todos os participantes. Isto ocorre quando há pelo menos dois participantes na conferência e pelo menos um dos participantes tem startConferenceOnEnter="true" definido.
end O último participante deixou a conferência ou um participante com endConferenceOnExit="true" definido saiu da conferência.
join Um participante entrou na conferência.
leave Um participante saiu da conferência.
mute Um participante teve o som ativado ou desativado
hold Um participante foi mantido em espera.
modify Pelo menos um dos atributos de um participante foi modificado: BeepOnExit, EndConferenceOnExit, Coaching, WaitUrl
speaker Um participante começou ou parou de falar.
announcement Um anúncio de participante ou da conferência foi encerrado ou falhou. Atualmente, o evento announcement-fail só será enviado se houver um erro interno da Twilio. Estamos trabalhando para adicionar mais falhas ao evento announcement-fail para permitir que os desenvolvedores depurem o problema.

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.

O URL statusCallback é definido pelo primeiro participante a entrar na conferência. Configurações subsequentes do statusCallback serão ignoradas.

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.

Parâmetro Examplo Enviado em
ConferenceSid CFe08c870b500f6e44a9ad184defd1f391 Enviado em: All
FriendlyName MyConf Enviado em: All
AccountSid AC25e16e9a716a4a8617a7c83f58e30482 Enviado em: All
SequenceNumber 1 Enviado em: All
Timestamp Qui., 1 de junho de 2017 20:48:32 +0000 Enviado em: All
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 em: join leave start end mute hold modify speaker announcement
CallSid CA25e16e9a716a4a1786a7c83f58e30482 Enviado em: join leave mute hold modify speaker announcement (para anúncios do participante)
Muted true, false Enviado em: join leave mute hold modify speaker announcement (para anúncios do participante)
Hold true, false Enviado em: join leave mute hold modify speaker announcement (para anúncios do participante)
Coaching true, false Sent on: join leave mute hold modify speaker announcement (para anúncios do participante)
EndConferenceOnExit true, false Enviado em: join leave mute hold modify speaker announcement (para anúncios do participante)
StartConferenceOnEnter true, false Enviado em: join leave mute hold modify speaker announcement (para anúncios do participante)
CallSidEndingConference O SID da chamada do participante que encerrou a conferência (se aplicável) Enviado em: end
ParticipantLabelEndingConference Rótulo do participante que encerrou a conferência (se aplicável) Enviado em: 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 em: end
Reason Uma mensagem indicando por que a conferência terminou Enviado em: end
ReasonAnnouncementFailed Uma mensagem indicando por que o anúncio falhou Enviado em: announcement
AnnounceUrl O URL usado para o anúncio Enviado em: announcement
EventName* conference-record-end Enviado em: conference-record-end
RecordingUrl* https://api.twilio.com/2010-04-01/Accounts/AC123/Recordings/RE234 Enviado em: conference-record-end
Duration* 6 Enviado em: conference-record-end
RecordingFileSize* 90786 Enviado em: conference-record-end

Todos parâmetros conference-record-end acima foram descontinuados em favor de recordingStatusCallback, que é a abordagem preferida para receber informações relacionadas à gravação. Fornecer um recordingStatusCallback resultará em nenhum callback de conference-record-end.

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:

Parâmetro Descrição
AccountSid O identificador exclusivo da conta responsável pela gravação.
ConferenceSid Um identificador exclusivo para a conferência associada à gravação.
RecordingSid O identificador exclusivo da gravação.
RecordingUrl O URL do áudio gravado.
RecordingStatus O status da gravação. Os valores possíveis são: in-progress, completed,absent.
RecordingDuration A duração da gravação, em segundos
RecordingChannels O número de canais no arquivo de gravação final como um número inteiro. Apenas o canal 1 é compatível para gravações da conferências.
RecordingStartTime O carimbo de data/hora de quando a gravação foi iniciada.
RecordingSource O método de início usado para criar a gravação. Conference é retornado para as gravações da conferência.

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:

Parâmetro Descrição
in-progress A gravação foi iniciada
completed A gravação foi concluída e está disponível para acesso
absent a gravação está ausente e inacessível

Para pausar ou retomar as gravações da conferência, consulte os documentos da API de gravação.

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.

Loading Code Sample...
        
        
        

        A Simple Conference

        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:

        Loading Code Sample...
              
              
              

              A Moderated Conference

              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:

              Loading Code Sample...
                    
                    
                    

                    A Moderated Conference (begin on enter)

                    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.

                    Loading Code Sample...
                          
                          
                          

                          Join an Evented Conference

                          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.

                          Loading Code Sample...
                                
                                
                                

                                Join a Conference Muted

                                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.

                                Loading Code Sample...
                                      
                                      
                                      

                                      Bridging Calls

                                      Loading Code Sample...
                                            
                                            
                                            

                                            Call on Hold

                                            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:

                                            Loading Code Sample...
                                                  
                                                  
                                                  

                                                  Call on Hold (end on exit)

                                                  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.

                                                  Loading Code Sample...
                                                        
                                                        
                                                        

                                                        Combining with Dial attributes

                                                        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.

                                                        Loading Code Sample...
                                                              
                                                              
                                                              

                                                              Recording a Conference

                                                              Classifique esta página:

                                                              Precisa de ajuda?

                                                              Às vezes, todos nós precisamos; a programação é difícil. Receba ajuda agora da nossa equipe de suporte, ou confie na sabedoria da multidão navegando pelo Stack Overflow Collective da Twilio ou buscando a tag Twilio no Stack Overflow.

                                                              Loading Code Sample...
                                                                    
                                                                    
                                                                    

                                                                    Obrigado pelo seu feedback!

                                                                    Selecione o(s) motivo(s) para seu feedback. As informações adicionais que você fornece nos ajudam a melhorar nossa documentação:

                                                                    Enviando seu feedback...
                                                                    🎉 Obrigado pelo seu feedback!
                                                                    Algo deu errado. Tente novamente.

                                                                    Obrigado pelo seu feedback!

                                                                    thanks-feedback-gif