TwiML™ Voice: <Gather>

Você pode usar o verbo <Gather> do TwiML para coletar dígitos ou transcrever a fala durante uma chamada.

O exemplo a seguir mostra o uso mais básico do TwiML <Gather>:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Gather/>
</Response>

Você sempre pode enviar o TwiML simples da Twilio ou aproveitar as bibliotecas auxiliares para adicionar o TwiML a seus aplicativos da web:

Quando a Twilio executar este TwiML, ele pausará por até cinco segundos para aguardar o autor da chamada inserir dígitos no teclado. Algumas coisas podem acontecer em seguida:

• O autor da chamada insere dígitos seguidos por um símbolo # ou 5 segundos de silêncio. A Twilio enviará esses dígitos em uma solicitação POST de volta ao URL que hospeda seu TwiML.
• O autor da chamada não insere nenhum dígito e 5 segundos se passam. A Twilio passará para o próximo verbo TwiML no documento – como não há mais verbos aqui, a Twilio encerrará a chamada.

Atributos do <Gather>

<Gather> oferece suporte aos seguintes atributos que alteram seu comportamento:

Use um ou mais desses atributos em um verbo <Gather> da seguinte forma:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Gather input="speech dtmf" timeout="3" numDigits="1">
        <Say>Please press 1 or say sales for sales.</Say>
    </Gather>
</Response>

action (ação)

O atributo action usa um URL absoluto ou relativo como valor. Quando o autor da chamada terminar de inserir dígitos (ou o tempo limite for atingido), a Twilio fará uma solicitação HTTP para esse URL. Essa solicitação incluirá os dados do usuário e os parâmetros de solicitação padrão da Twilio.

Se você não fornecer um parâmetro action, a Twilio fará uma solicitação POST ao URL que contém o documento do TwiML ativo.

A Twilio pode enviar alguns parâmetros extras com sua solicitação depois que <Gather> terminar:

Se você coletar dígitos do autor da chamada, a Twilio incluirá o parâmetro Digits contendo os números digitados pelo autor da chamada.

Se você especificar fala como uma entrada com input="speech", a Twilio incluirá SpeechResult e Confidence:

• SpeechResult contém o resultado transcrito da fala do autor da chamada.
• Confidence contém uma pontuação de confiança entre 0,0 e 1,0. Uma pontuação de confiança mais alta significa uma maior probabilidade de que a transcrição seja precisa.

Observação: Seu código não deve esperar confidence como um campo obrigatório, pois não é garantido que ele seja preciso, ou mesmo definido, em nenhum dos resultados.

Depois que <Gather> terminar e a Twilio enviar sua solicitação para seu URL action, a chamada atual continuará usando o TwiML que você enviar de volta a partir desse URL. Por isso, qualquer verbo do TwiML que ocorrer depois de <Gather> será inacessível.

No entanto, se o autor da chamada não inserir nenhum dígito ou fala, o fluxo da chamada continuará no documento do TwiML original.

Imagine que você tenha o seguinte TwiML hospedado em http://example.com/complex_gather.xml:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Gather>
        <Say>
            Please enter your account number,
            followed by the pound sign
        </Say>
    </Gather>
    <Say>We didn't receive any input. Goodbye!</Say>
</Response>

Cenário 1: Se o autor da chamada:

• não pressionar o teclado nem dizer nada por cinco segundos ou
• pressionar '#' (o valor finishOnKey padrão) antes de inserir qualquer outro dígito

em seguida, eles ouvirão: "We didn't receive any input. Goodbye!"

Cenário 2: Se o autor da chamada:

• pressionar um dígito enquanto a chamada está falando "Please enter your account number..." (Insira o número de sua conta...)

o verbo <Say> vai parar de falar e aguardará a ação do usuário.

Cenário 3: Se o autor da chamada:

• inserir 12345 e depois pressionar # ou
• permitir a passagem de 5 segundos

a Twilio enviará os dígitos e os parâmetros da solicitação para o URL que hospeda esse TwiML (http://example.com/complex_gather.xml). A Twilio vai buscar esse mesmo TwiML novamente e executá‐lo, deixando o autor da chamada preso nesse loop de <Gather>.

Para evitar esse comportamento, é melhor apontar seu URL action para um novo URL que hospeda algum outro TwiML para lidar com a duração da chamada.

A seguinte amostra de código é quase idêntica à do TwiML acima, mas adicionamos os atributos action method:

Agora, quando o autor da chamada inserir sua entrada, a Twilio enviará os dígitos e os parâmetros de solicitação para o URL process_gather.php.

Se quiséssemos ler novamente essa entrada para o autor da chamada, nosso código hospedado em /process_gather.php poderia ser semelhante a:

<?php
// page located at http://yourserver/process_gather.php
echo "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n";
echo "<Response><Say>You entered ". $_REQUEST['Digits']. "</Say></Response>";
?>

Voltar para a lista de atributos

finishOnKey

finishOnKey permite definir um valor que o autor da chamada pode pressionar para enviar seus dígitos.

Por exemplo, se você definir finishOnKey como # e o autor da chamada digitar 1234#, a Twilio irá parar imediatamente de aguardar mais entradas depois de pressionar #.

A Twilio enviará Digits=1234 para seu URL action (observe que # não está incluído).

Os valores permitidos para esse atributo são:

• # (este é o valor padrão)
• *
• Dígitos únicos 0–9
• Uma string vazia ('')

Se você usar uma string vazia, <Gather> vai capturar todas as entradas do usuário e nenhuma tecla terminará o <Gather>. Nesse caso, a Twilio envia os dígitos do usuário para o URL action somente depois que o tempo limite for atingido.

Voltar para a lista de atributos

hints

Você pode melhorar o reconhecimento de palavras ou frases da Twilio que você espera dos seus autores da chamada adicionando hints em <Gather>.

O atributo hints contém uma lista de palavras ou frases que a Twilio deve esperar durante o reconhecimento.

Você pode fornecer até 500 palavras ou frases nesta lista, separando cada entrada com uma vírgula. Suas dicas podem ter até 100 caracteres cada, e você deve separar cada palavra em uma frase com um espaço, por exemplo:

hints="this is a phrase I expect to hear, keyword, product name, name"

Você também pode passar um token de classe para melhorar o reconhecimento.

hints="$OOV_CLASS_ALPHANUMERIC_SEQUENCE"

Voltar para a lista de atributos

input (entrada)

Especifique quais entradas (DTMF ou fala) a Twilio deve aceitar com o atributo input.

O input padrão para <Gather> é dtmf. Você pode definir input como dtmf, speech ou dtmf speech.

Observe que o reconhecimento de fala do <Gather> ainda não está otimizado para entradas alfanuméricas (por exemplo, ABC123), isso pode levar a resultados imprecisos e, portanto, não recomendamos.

Se você definir dtmf speech para sua entrada, a primeira entrada detectada (speech ou dtmf) terá precedência. Se speech for detectado primeiro, finishOnKey será ignorado.

O exemplo a seguir mostra um <Gather> que especifica a entrada de fala do usuário. Quando este TwiML for executado, o autor da chamada ouvirá o prompt de <Say>. A Twilio coletará a entrada de voz por até 60 segundos.

Assim que o autor da chamada parar de falar por cinco segundos, a Twilio publicará seu discurso transcrito no URL action.

Voltar para a lista de atributos

language (idioma)

O atributo language especifica o idioma que a Twilio deve reconhecer do autor da chamada.

Esse valor tem como padrão en-US, mas você pode configurar seu language para qualquer um dos nossos idiomas compatíveis: veja a lista completa.

Voltar para a lista de atributos

método

O method que você definiu em <Gather> diz à Twilio se deve solicitar o URL de ação via HTTP GET ou POST.

POST é o método padrão do <Gather>.

Voltar para a lista de atributos

numDigits

Você pode definir o número de dígitos esperado do autor da chamada incluindo numDigits em <Gather>.

Por exemplo, você pode querer definir numDigits="5" ao pedir que o autor da chamada insira seu código postal de 5 dígitos. Assim que o autor da chamada inserir o dígito final de 94117, a Twilio enviará imediatamente os dados para o URL action.

Voltar para a lista de atributos

partialResultCallback

Se você fornecer um URL partialResultCallback, a Twilio fará solicitações a esse URL em tempo real, pois reconhece a fala. Essas solicitações conterão um parâmetro rotulado UnstableSpeechResult que contém transcrições parciais. Essas transcrições podem mudar à medida que o reconhecimento de fala progride.

Voltar para a lista de atributos

profanityFilter

O profanityFilter especifica se a Twilio deve filtrar linguagem obscena da sua transcrição da fala. Esse atributo assume como padrão true, que substitui todos os caracteres, exceto o inicial, em cada palavra obscena filtrada por asteriscos, por exemplo, 'f***.'

Se você definir esse atributo como false, a Twilio não filtrará mais nenhuma palavra obscena em suas transcrições.

Voltar para a lista de atributos

speechTimeout

Ao coletar a fala do autor da sua chamada, speechTimeout define o limite (em segundos) que a Twilio aguardará antes de interromper seu reconhecimento de fala. Depois que esse tempo limite for atingido, a Twilio publicará o speechResult em seu URL action.

Se você definir speechTimeout como auto, a Twilio interromperá o reconhecimento de voz quando houver uma pausa na fala e retornará os resultados imediatamente.

Voltar para a lista de atributos

timeout (tempo limite)

timeout permite definir o limite (em segundos) que a Twilio aguardará até que o autor da chamada pressione outro dígito ou diga outra palavra antes de enviar dados para seu URL action.

Por exemplo, se timeout for 3, a Twilio aguarda três segundos para que o autor da chamada pressione outra tecla ou diga outra palavra antes de enviar seus dados.

A Twilio aguardará até que todos os verbos aninhados sejam executados antes de iniciar o período timeout.

O valor de timeout padrão é 5.

Voltar para a lista de atributos

speechModel

speechModel permite selecionar um modelo específico mais adequado para seu caso de uso para melhorar a precisão da fala no texto. O atributo atualmente é compatível com default, numbers_and_commands e phone_call.

numbers_and_commands e phone_call são mais adequados para os casos de uso em que você espera receber consultas curtas, como comandos de voz ou pesquisa por voz. Explore as duas opções para ver qual funciona melhor para seu caso de uso.

<Gather input="speech" enhanced="true"speechModel="phone_call">
    <Say>Please tell us why you're calling.</Say>
</Gather>

Voltar para a lista de atributos

enhanced

O atributo enhanced instrui o <Gather> a usar um modelo de fala premium que vai melhorar a precisão dos resultados de transcrição. O modelo de fala premium só é compatível com phone_call speechModel. Ela custa 50% a mais a US$ 0,03 por 15 s de <Gather> do que o modelo padrão phone_call. O modelo phone_call premium foi criado usando milhares de horas de dados de treinamento. Ele garante 54% menos erros ao transcrever conversas telefônicas quando comparado ao modelo básico phone_call.

O seguinte TwiML instrui <Gather> a usar o modelo premium phone_call:

<Gather input="speech" enhanced="true"speechModel="phone_call">
    <Say>Please tell us why you're calling.</Say>
</Gather>

Leia o Language appendix (Apêndice de idioma) para ver se o modelo aprimorado está disponível para seu idioma.

Voltar para a lista de atributos

actionOnEmptyResult

actionOnEmptyResult permite que você force o <Gather> a enviar um webhook ao url de ação mesmo quando não há entrada DTMF. Por padrão, se o <Gather> atingir o tempo limite enquanto aguarda a entrada DTMF, ele continuará até a próxima instrução do TwiML.

Por exemplo, no seguinte TwiML quando <Gather> atinge o tempo limite, a instrução <Say> é executada.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Gather>
        <Say>
            Please enter your account number,
            followed by the pound sign
        </Say>
    </Gather>
    <Say>We didn't receive any input. Goodbye!</Say>
</Response>

Para sempre forçar o <Gather> o envio de um webhook para o URL action, use o seguinte TwiML,

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Gather actionOnEmptyResult="true" action="/gather-action">
        <Say>
            Please enter your account number,
            followed by the pound sign
        </Say>
    </Gather>
</Response>

Aninhe outros verbos

Você pode aninhar os seguintes verbos dentro de <Gather>:

• <Pause>
• <Play>
• <Say>

<Say>

O exemplo a seguir mostra um <Gather> com um <Say> aninhado. Isso lerá algum texto para o autor da chamada e permitirá que ele insira a entrada a qualquer momento enquanto esse texto é lido para ele:

Gerenciar tempos limites

Quando um <Gather> atinge seu tempo limite sem nenhuma entrada do usuário, o controle de chamadas passa para o próximo verbo no seu documento TwiML original.

Se desejar que a Twilio envie uma solicitação para seu URL action mesmo se <Gather> atingir o tempo limite, inclua um <Redirect> após o <Gather> da seguinte maneira:

Com esse código, a Twilio passará para o próximo verbo no documento (<Redirect>) quando <Gather> atingir o tempo limite. Em nosso exemplo, instruímos a Twilio a fazer uma nova solicitação GET para /process_gather.php?Digits=TIMEOUT

Resolução de problemas

Alguns problemas comuns que os usuários enfrentam ao trabalhar com <Gather>:

Problema: <Gather> não recebe a entrada do autor da chamada quando ele está usando um telefone VoIP.

Solução: Alguns telefones VoIP têm problemas para enviar dígitos DTMF. Isso geralmente ocorre porque esses telefones usam protocolos de áudio com economia de largura de banda compactada que interferem na transmissão do sinal do dígito. Consulte a documentação do seu telefone sobre problemas DTMF.

Problema: A Twilio não envia o parâmetro Digits para seu URL <Gather>.

Solução: Verifique se o aplicativo não está respondendo ao URL action com um redirecionamento HTTP 3xx. A Twilio seguirá esse redirecionamento, mas não enviará novamente o parâmetro Digits.

Caso encontre outros problemas com <Gather>, entre em contato com nossa equipe de suporte para obter assistência.