TwiML™ Voice: <Enqueue>
O verbo <Enqueue> enfileira a chamada atual em uma fila de chamadas. As chamadas em fila aguardam com a música em espera
até que a chamada seja retirada da fila por outro autor da chamada por meio do verbo <Dial> ou transferida para fora da fila através
da API REST ou do verbo <Leave>.
O verbo <Enqueue> cria uma fila sob demanda caso a fila ainda não exista. O tamanho padrão máximo da fila é 100. Ele pode ser modificado usando a
API REST.
Atributos do verbo
O verbo <Enqueue> é compatível com seguintes atributos que modificam seu comportamento:
| Nome do atributo | Valores permitidos | Valor padrão |
|---|---|---|
| action | URL relativo ou absoluto | nenhum |
| method | GET, POST | POST |
| waitUrl | URL relativo ou absoluto | playlist de música clássica padrão |
| waitUrlMethod | GET, POST | POST |
| workflowSid | SID do fluxo de trabalho TaskRouter | nenhum |
action
O atributo "action" usa o URL absoluto ou relativo como um valor.
Uma solicitação é feita para esse URL quando a chamada sai da fila, descrevendo o motivo da remoção da fila e os detalhes
sobre o tempo gasto na fila, conforme descritos abaixo. No caso em que uma chamada é retirada da fila devido
a uma solicitação da API REST ou ao verbo <Leave>, o URL de ação é solicitado imediatamente. Caso uma chamada seja
retirada da fila por meio do verbo <Dial>, o URL de ação é acionado uma vez quando as partes conectadas se desconectam.
Se nenhum "action" for fornecido, a Twilio passará para o próximo verbo do documento, se houver.
Parâmetros da solicitação
A Twilio passará os seguintes parâmetros além dos parâmetros da solicitação padrão do TwiML Voice com sua solicitação para o URL de 'action':
| Parâmetro | Descrição |
|---|---|
| QueueResult | O resultado final da chamada enfileirada. Consulte os valores do resultado da fila abaixo para obter detalhes. |
| QueueSid | O SID da fila. Disponível apenas se a chamada tiver sido colocada na fila. |
| QueueTime | O tempo que a chamada permaneceu na fila. Disponível apenas se a chamada tiver sido colocada na fila. |
Valores do QueueResult
Os valores a seguir representam o resultado de uma tentativa de colocar um autor da chamada na fila.
| Valor | Descrição |
|---|---|
| bridged | A chamada foi retirada da fila e encaminhada para o desenfileirador. |
| bridging-in-process | A Twilio foi instruída a conectar a parte enfileirada. |
| error | O TwiML continha um erro, seja no próprio verbo <Enqueue> ou no TwiML recuperado de um waitUrl. Verifique o App Monitor (monitoramento de app). |
| hangup | O autor da chamada em fila desligou antes de se conectar a uma chamada desenfileirada. |
| leave | O autor da chamada em fila saiu da fila através do verbo <Leave>. |
| redirected | Enquanto na fila, a chamada foi redirecionada para fora da fila, normalmente por uma solicitação da API REST. |
| redirected-from-bridged | A sessão enfileirada e depois conectada com êxito foi transferida. |
| queue-full | A fila de destino estava cheia, portanto, a tentativa de enfileiramento foi rejeitada. |
| system-error | O sistema da Twilio não funcionou corretamente durante o processo de enfileiramento. Isso pode acontecer se o autor da chamada desligar antes de ser completamente colocado na fila. |
method
O atributo "method" usa o valor "GET" ou "POST". Isso informa à Twilio se deve solicitar o URL de "action" via HTTP GET ou POST. Este atributo é modelado no atributo “method” do formulário HTML. “POST” é o valor padrão.
waitUrl
O atributo "waitUrl" especifica um URL apontando para um documento do TwiML contendo verbos do TwiML que serão executados enquanto o autor da chamada estiver aguardando na fila.
Depois que o fluxo waitUrl do TwiML ficar sem verbos para executar, a Twilio solicitará novamente o waitUrl e começará novamente, basicamente
mantendo a música de espera em loop indefinidamente. O verbo <Redirect> pode ser usado para vários fluxos de documentos, mas o fluxo sempre retornará ao waitUrl
quando não houver mais TwiML para executar.
Os seguintes verbos são compatíveis com o documento waitUrl do TwiML:
| Verbo | Descrição |
|---|---|
| <Play> | Reproduz um arquivo para o autor da chamada. |
| <Say> | Diz algo ao autor da chamada usando a conversão de texto para fala da Twilio. |
| <Pause> | Pausa por uma duração especificada. |
| <Hangup> | Desliga a chamada e, assim, deixa a fila e encerra a chamada. |
| <Redirect> | Redireciona para outro documento do TwiML. |
| <Leave> | Faz com que a chamada atual saia da fila, mas não desliga a chamada. A execução continua com o próximo verbo depois do verbo "<Enqueue>". |
| <Gather> | Coleta os dígitos que o autor da chamada insere no teclado de seu telefone. OBSERVAÇÃO: apenas o tipo de entrada DTMF é compatível no "<Gather>" retornado em um "waitUrl" de um "<Enqueue>"; o tipo de entrada de fala não funcionará. |
Parâmetros da solicitação
A Twilio passará os seguintes parâmetros além dos parâmetros da solicitação padrão do TwiML Voice com sua solicitação para o URL de "waitUrl":
| Parâmetro | Descrição |
|---|---|
| QueuePosition | A posição atual na fila para a chamada enfileirada. |
| QueueSid | O SID da fila em que o autor da chamada está. |
| QueueTime | O tempo, em segundos, em que o autor da chamada esteve na fila. |
| AvgQueueTime | Uma média, em segundos, de quanto tempo os autores da chamada atuais enfileirados passaram na fila. |
| CurrentQueueSize | O número atual de chamadas enfileiradas nesta fila. |
waitUrlMethod
O atributo "waitUrlMethod" usa o valor "GET" ou "POST". Isso informa à Twilio se deve solicitar o "waitUrl" via HTTP GET ou POST. Este atributo é modelado no atributo "method" do formulário HTML. “POST” é o valor padrão.
workflowSid
O atributo "workflowSid" instrui a Twilio a criar uma nova tarefa do TaskRouter para representar essa chamada e especifica o ID do fluxo de trabalho desejado para manipulá-la.
Se "workflowSid" for especificado, não é necessário especificar um nome para a fila para posicionar a chamada. Quando um trabalhador é identificado para lidar com a chamada, ela pode ser retirada da fila e conectada usando a instrução de atribuição de desenfileiramento.
Substantivos
O "noun" de um verbo TwiML é o conteúdo aninhado do verbo que não é o próprio verbo; é a informação sobre a qual o verbo age. Estes são os substantivos para <Enqueue>:
| Substantivo | Descrição |
|---|---|
| plain text | O nome de uma fila específica. |
| Task | Os atributos a serem definidos para a tarefa recém‐criada, formatada como JSON |
Se a fila nomeada ainda não tiver sido criada, ela será criada sob demanda. O nome da fila não pode ter mais de 64 caracteres.
Você pode encontrar mais informações e exemplos sobre como usar Task na página integração do TwiML TaskRouter.
Exemplos
Exemplo 1: Enfileiramento simples
Este documento do TwiML diz à Twilio para buscar o documento wait-music.xml do TwiML e executá‐lo enquanto o autor da chamada estiver na fila:
O documento wait-music.xml do TwiML reproduz uma música de espera agradável:
Dicas e usos avançados
- Você pode usar os parâmetros na solicitação "waitUrl" para retornar
<Say>ao autor da chamada sobre qual é sua posição na fila e por quanto tempo ele pode ter que esperar.
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.
