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