TwiML™ Voice: <Gather>

Puedes utilizar el verbo <Gather> de TwiML para recopilar dígitos o transcribir voz durante una llamada.

El siguiente ejemplo muestra el uso más básico de <Gather> de TwiML:

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

Siempre puedes enviar TwiML simple de Twilio, o aprovechar las bibliotecas auxiliares para añadir TwiML a tus aplicaciones web:

Cuando Twilio ejecuta este TwiML, se detendrá hasta cinco segundos para esperar a que el agente de llamada ingrese dígitos en su teclado. A continuación, pueden ocurrir distintas cosas:

• El agente de llamada introduce dígitos seguidos de un símbolo # o se producen cinco segundos de silencio. Twilio enviará esos dígitos en una solicitud POST a la URL que aloja tu TwiML.
• El agente de llamada no introduce ningún dígito y pasan cinco segundos. Twilio pasará al siguiente verbo TwiML en el documento; puesto que no hay más verbos aquí, Twilio terminará la llamada.

Atributos de <Gather>

<Gather> admite los siguientes atributos que cambian su comportamiento:

Utiliza uno o más de estos atributos en un verbo <Gather> como en este ejemplo:

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

El atributo action toma una dirección URL absoluta o relativa como valor. Cuando el agente de llamada termina de ingresar dígitos (o se alcanza el tiempo de espera), Twilio hará una solicitud HTTP a esta URL. Esta solicitud incluirá los datos del usuario y los parámetros de solicitud estándar de Twilio.

Si no proporciona un parámetro action, Twilio utilizará POST a la URL que aloja el documento TwiML activo.

Twilio puede enviar algunos parámetros adicionales con su solicitud después de finalice <Gather>:

Si obtienes dígitos del agente de llamada, Twilio incluirá el parámetro Digits que contiene los números que el agente de llamada ingresó.

Si especifica voz como entrada con input="speech", Twilio incluirá SpeechResult y Confidence:

• SpeechResult contiene el resultado transcrito de la voz del agente de llamada.
• Confidence contiene una puntuación de confianza entre 0,0 y 1,0. Una puntuación de confianza más alta significa una mayor probabilidad de que la transcripción sea precisa.

Nota: El código no debe esperar confidence como campo obligatorio, ya que no se garantiza que sea preciso, o incluso establecido, en ninguno de los resultados.

Después de que <Gather> termine y Twilio envíe su solicitud a tu action URL (URL de acción), la llamada actual continuará usando el TwiML que envíes de vuelta desde esa URL. Debido a esto, no se puede acceder a los verbos TwiML que se produzcan después de <Gather>.

Sin embargo, si el agente de llamada no introduce ningún dígito o voz, el flujo de llamadas continuará en el documento TwiML original.

Imagina que tienes el siguiente TwiML alojado en 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>

Situación 1: si el agente de llamada:

• no pulsa el teclado ni dice nada durante cinco segundos; o
• ingresa '#' (el valor predeterminado definishOnKey) antes de introducir cualquier otro dígito

entonces escucharán, "We didn't receive any input. Goodbye!" (No hemos recibido ninguna entrada. ¡Adiós!)

Situación 2: si el agente de llamada:

• introduce un dígito mientras la llamada está diciendo "Please enter your account number..." (Introduce tu número de cuenta...)

entonces el verbo <Say> dejará de hablar y esperará la acción del usuario.

Situación 3: si el agente de llamada:

• introduce 12345 y, a continuación, pulsa #, o
• deja pasar cinco segundos

entonces Twilio enviará los dígitos y los parámetros de solicitud a la URL que aloja este TwiML (http://example.com/complex_gather.xml). Twilio recuperará este mismo TwiML de nuevo y lo ejecutará, haciendo que el agente de llamada se quede atascado en este bucle de <Gather>.

Para evitar este comportamiento, la práctica recomendada es dirigir la action URL (URL de acción) a una nueva URL que aloje algún otro TwiML a fin de controlar la duración de la llamada.

El siguiente código muestra es casi idéntico al TwiML anterior, pero hemos agregado los atributos action y method:

Ahora, cuando el agente de llamada ingrese su entrada, Twilio enviará los dígitos y los parámetros de solicitud a la URL process_gather.php.

Si quisiéramos volver a leer esta entrada al agente de llamada, nuestro código alojado en /process_gather.php podría tener el siguiente aspecto:

<?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>";
?>

Volver a la lista de atributos

finishOnKey

finishOnKey te permite establecer un valor que el agente de llamada puede pulsar para enviar sus dígitos.

Por ejemplo, si estableces finishOnKey en # y el agente de llamada ingresa 1234#, Twilio inmediatamente dejará de esperar más entradas después de pulsar #.

Twilio enviará Digits=1234 a tu action URL (URL de acción) (ten en cuenta que # no está incluido).

Estos son los valores permitidos para este atributo:

• # (este es el valor predeterminado)
• *
• Solo un dígito, de 0 a 9
• Una cadena vacía ('')

Si utilizas una cadena vacía, <Gather> capturará todas las entradas del usuario y ninguna tecla finalizará <Gather>. En este caso, Twilio envía los dígitos del usuario a la action URL solo después de alcanzar el tiempo de espera.

Volver a la lista de atributos

hints

Puedes mejorar el reconocimiento de Twilio de las palabras o frases que esperas de tus agentes de llamada añadiendo hints (sugerencias) a tu <Gather>.

El atributo hints contiene una lista de palabras o frases que Twilio debe esperar durante el reconocimiento.

Puedes proporcionar hasta 500 palabras o frases en esta lista, separando cada entrada con una coma. Las sugerencias pueden tener hasta 100 caracteres cada una, y debes separar cada palabra en una frase con un espacio, por ejemplo:

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

We have also implemented Google's class token list to improve recognition. You can pass a class token directly in the hints.

hints="$OOV_CLASS_ALPHANUMERIC_SEQUENCE"

Volver a la lista de atributos

input

Especifica qué entradas (DTMF o voz) Twilio debe aceptar con el atributo input.

El valor predeterminado de input para <Gather> es dtmf. Puedes establecer input en dtmf, speech o dtmf speech.

Ten en cuenta que el reconocimiento de voz de <Gather> aún no está optimizado para las entradas alfanuméricas (por ejemplo, ABC123), esto podría dar lugar a resultados inexactos y, por lo tanto, no lo recomendamos.

Si estableces dtmf speech para tu entrada, la primera entrada detectada (speech o dtmf) tendrá prioridad. Si speech se detecta primero, finishOnKey se ignorará.

En el ejemplo siguiente, se muestra un <Gather> que especifica la entrada de voz del usuario. Cuando se ejecute este TwiML, el agente de llamada escuchará el aviso <Say>. Twilio recopilará la entrada de voz durante un máximo de 60 segundos.

Una vez que el agente de llamada deja de hablar durante cinco segundos, Twilio publica su voz transcrita en su action URL (URL de acción).

Volver a la lista de atributos

language

El atributo language especifica el idioma que Twilio debe reconocer de tu agente de llamada.

Este valor predeterminado es en-US, pero puedes establecer language en cualquiera de los idiomas admitidos: consulta la lista completa.

Volver a la lista de atributos

method

El atributo method que estableces en <Gather> le dice a Twilio si debe solicitar tu URL de acción mediante HTTP GET o POST.

POSTes el método predeterminado de <Gather>.

Volver a la lista de atributos

numDigits

Puedes establecer el número de dígitos que esperas del agente de llamada incluido numDigits en <Gather>.

Por ejemplo, puede que desees establecer numDigits="5" cuándo le pides al agente de llamada que introduzca su código postal de cinco dígitos. Una vez que el agente de llamada introduzca el último dígito de 94117, Twilio enviará de inmediato los datos a tu action URL.

Volver a la lista de atributos

partialResultCallback

Si proporcionas una URL de partialResultCallback, Twilio hará solicitudes a esta URL en tiempo real al mismo tiempo que reconoce la voz. Estas solicitudes contendrán un parámetro etiquetado como UnstableSpeechResult que contiene transcripciones parciales. Estas transcripciones pueden cambiar a medida que avanza el reconocimiento de voz.

Volver a la lista de atributos

profanityFilter

El profanityFilter especifica si Twilio debe filtrar las profanidades fuera de tu transcripción de voz. Este atributo está en true de forma predeterminada, lo que reemplaza todo menos el carácter inicial de cada palabra vulgar filtrada con asteriscos, por ejemplo, 'm*****'.

Si estableces este atributo en false, Twilio ya no filtrará ninguna palabra grosera en tus transcripciones.

Volver a la lista de atributos

speechTimeout

Cuando recopilas la voz de tu agente de llamada, speechTimeout establece el límite (en segundos) que Twilio esperará antes de detener su reconocimiento de voz. Una vez alcanzado este tiempo de espera, Twilio publicará el speechResult en tu action URL.

Si estableces speechTimeout en auto, Twilio detendrá el reconocimiento de voz cuando haya una pausa en el habla y devolverá los resultados de inmediato.

Volver a la lista de atributos

timeout

timeout te permite establecer el límite (en segundos) que Twilio esperará a que el agente de llamada presione otro dígito o diga otra palabra antes de enviar datos a tu action URL.

Por ejemplo, si timeout es 3, Twilio espera 3 segundos a que el agente de llamada presione otra tecla o diga otra palabra antes de enviar sus datos.

Twilio esperará hasta que todos los verbos anidados se ejecuten antes de que comience el período de timeout (tiempo de espera agotado).

El valor predeterminado de timeout es5.

Volver a la lista de atributos

speechModel

speechModel allows you to select a specific model that is best suited for your use case to improve the accuracy of speech to text. The attribute currently supports default, numbers_and_commands, phone_call, experimental_conversations, and experimental_utterances.

numbers_and_commands and phone_call are best suited for the use cases where you'd expect to receive short queries such as voice commands or voice search. phone_call is best for audio that originated from a PSTN phone call (typically an 8khz sample rate).

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

Experimental models are designed to give access to the latest speech technology and machine learning research, and can provide higher accuracy for speech recognition over other available models. However, some features that are supported by other available models are not yet supported by the experimental models such as confidence scores. The experimental_conversations and experimental_utterances values for speechModel currently only supports a set of languages, they are listed here.

Please explore all options to see which works best for your use case.

Volver a la lista de atributos

enhanced

El atributo enhanced instruye a <Gather> a utilizar un modelo de voz superior que mejorará la precisión de los resultados de transcripción. El modelo de voz premium solo es compatible con phone_call speechModel. Cuesta un 50 % más a USD 0,03 por 15 segundos de <Gather> que el modelo phone_call estándar. El modelo phone_call premium se creó utilizando miles de horas de datos de entrenamiento. Garantiza un 54 % menos de errores cuando se transcriben conversaciones telefónicas en comparación con el modelo de phone_call básico.

El siguiente TwiML indica a <Gather> que utilice el modelo phone_call premium:

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

Lee el Apéndice de idiomas para ver si el modelo mejorado está disponible en tu idioma.

Volver a la lista de atributos

actionOnEmptyResult

actionOnEmptyResult te permite forzar <Gather> a enviar un webhook a la URL de acción incluso cuando no hay entrada DTMF. De forma predeterminada, si se agota el tiempo de espera de <Gather> mientras se espera la entrada DTMF, continuará hasta la siguiente instrucción TwiML.

Por ejemplo, en el siguiente TwiML cuando se agota el tiempo de espera de <Gather>, se ejecuta la instrucción <Say>.

<?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 forzar siempre <Gather> a enviar un webhook a la action URL (URL de acción), utiliza el siguiente 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>

Anidar otros verbos

Puedes anidar los siguientes verbos en <Gather>:

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

<Say>

En el ejemplo siguiente se muestra un <Gather> con un <Say> anidado. Esto leerá un poco de texto al agente de llamada y le permitirá ingresar entradas en cualquier momento mientras se lee el texto:

Gestionar tiempos de espera

Cuando un <Gather> alcanza su tiempo de espera sin ninguna entrada del usuario, el control de llamada pasará al siguiente verbo del documento TwiML original.

Si deseas que Twilio envíe una solicitud a tu action URL, incluso si se agota el tiempo de espera de <Gather>, incluye un<Redirect> después <Gather>, de esta manera:

Con este código, Twilio se moverá al siguiente verbo del documento (<Redirect>) cuando se agote el tiempo de espera de <Gather>. En nuestro ejemplo, instruimos a Twilio para que haga una nueva solicitud GET a /process_gather.php?Digits=TIMEOUT

Solución de problemas

Estos son algunos problemas comunes a los que se enfrentan los usuarios cuando trabajan con <Gather>:

Problema: <Gather> no recibe la entrada del agente de llamada cuando este utiliza un teléfono VoIP.

Solución: Algunos teléfonos VoIP tienen problemas para enviar dígitos de DTMF. Esto suele deberse a que estos teléfonos utilizan protocolos de audio comprimidos que conservan el ancho de banda y que interfieren en la transmisión de la señal del dígito. Consulta la documentación de tu teléfono sobre problemas de DTMF.

Problema: Twilio no envía el parámetro Digits a la URL de <Gather>.

Solución: Asegúrate de que la aplicación no responda a la action URL con una redirección HTTP 3xx. Twilio seguirá esta redirección, pero no reenviará el parámetro Digits.

Si tienes otros problemas con <Gather>, comunícate con nuestro equipo de asistencia técnica para obtener ayuda.