TwiML™ Voice: <Record>
El verbo <Record> graba la voz del agente de llamada y te devuelve la URL de un archivo que contiene la grabación de audio. De forma opcional, puedes generar transcripciones de texto de llamadas grabadas mediante el establecimiento del atributo transcribe del verbo <Record> en true.
Implicaciones legales de grabar llamadas
Si decides grabar llamadas de voz o videollamadas, deberás cumplir ciertas leyes y normativas, incluidas las relativas a la obtención del consentimiento para grabar (como la Ley de Invasión de la Privacidad de California y leyes similares en otras jurisdicciones). Puedes encontrar información adicional sobre las implicaciones legales de grabar llamadas aquí.
Aviso: Twilio te recomienda que consultes con tu asesor legal para asegurarte de que estás cumpliendo con todas las leyes aplicables en relación con las comunicaciones que grabes o almacenes usando Twilio.
Atributos del verbo
El verbo <Record> admite los siguientes atributos que modifican su comportamiento:
Nombre de atributo | Valores permitidos | Valor predeterminado
:------------- | :-------------- | :------------
action | URL relativa o absoluta | URL del documento actual
method | GET, POST | POST
timeout | Número entero positivo | 5
finishOnKey | Cualquier digito, #, * | 1234567890*#
maxLength | Número entero mayor que 1 | 3600 (1 hora)
playBeep | true, false | true
trim | trim-silence, do-not-trim | trim-silence
recordingStatusCallback| URL relativa o absoluta | Ninguno
recordingStatusCallbackMethod | GET, POST | POST
recordingStatusCallbackEvent | in-progress, completed, absent | completed
transcribe | true, false | false
transcribeCallback | URL relativa o absoluta | Ninguno
Usa uno o más de estos atributos en un verbo <Record>, de la siguiente forma:
action
El atributo action toma como valor una URL relativa o absoluta. Cuando la grabación haya terminado, Twilio hará una solicitud GET o POST a esta URL incluidos los parámetros que se indican a continuación. Si no se proporciona action, <Record> solicitará la URL del documento actual.
Después de hacer esta solicitud, Twilio continuará con la llamada actual usando el TwiML recibido en tu respuesta. Ten en cuenta que por defecto Twilio volverá a solicitar la URL del documento actual. Esto puede llevar a un comportamiento de bucle no deseado si no tienes cuidado. Cualquier verbo de TwiML que ocurra después de un <Record> es inalcanzable.
Por defecto, Twilio guarda las grabaciones silenciosas. Si no necesitas conservar grabaciones silenciosas, comunícate con Asistencia Técnica de Twilio.
Cuando se modifica una llamada en vivo para redirigir a un verbo <Record>, se debe proporcionar una URL de acción. Si no se proporciona una dirección URL de acción, se producirá un error 11100.
If you started or updated a call with a twiml parameter, the action URLs for <Record>, <Gather>, and <Pay> must be absolute.
The Call Resource API Docs have language-specific examples of creating and updating Calls with TwiML:
- See "Create a Call resource with TwiML" under Create a Call Resource to see examples of creating a call with a
twimlparameter. - See "Update a Call resource with TwiML" under Update a Call Resource to see examples of updating a call with a
twimlparameter.
Parámetros de solicitud
Twilio transferirá los siguientes parámetros además de los parámetros estándar de solicitud de TwiML Voice con
su solicitud a la URL de action:
| Parámetro | Descripción |
|---|---|
| RecordingUrl | La URL del audio grabado. Puede que el archivo de grabación no sea aún accesible cuando se envíe la devolución de llamada action. Utiliza recordingStatusCallback para obtener una notificación confiable cuando la grabación esté disponible para el acceso. |
| RecordingDuration | Duración del audio grabado (en segundos). Para obtener una duración de grabación final precisa después de recortar el silencio, utiliza recordingStatusCallback. |
| Digits | La tecla (si la hay) pulsada para finalizar la grabación o hangup si el agente de llamada cuelga. |
Una solicitud a RecordingUrl devolverá una grabación en formato de audio WAV binario de forma predeterminada. Para solicitar la grabación en formato MP3, agrega ".mp3" al valor RecordingUrl.
method
El atributo method toma el valor de GET o POST. Esto le dice a Twilio si debe solicitar la URL de action mediante la HTTP GET o POST. Este atributo se modela a partir del atributo method del formulario HTML. POST es el valor predeterminado.
timeout
El atributo timeout le dice a Twilio que finalice la grabación después de que hayan pasado varios segundos de silencio. Para desactivar esta función, establece timeout en 0. El valor predeterminado es 5 segundos.
finishOnKey
El atributo finishOnKey te permite elegir un conjunto de dígitos que, una vez introducidos, terminan la grabación. Por ejemplo, si pones finishOnKey en # y el agente de llamada presiona la tecla #, Twilio parará de inmediato la grabación y enviará RecordingUrl, RecordingDuration y # como parámetros en una solicitud a la URL de action. Los valores permitidos son los dígitos de 0 a 9, # y *. El valor predeterminado es 1234567890*#, es decir, cualquier tecla finalizará la grabación. A diferencia de <Gather>, puedes especificar más de un carácter como valor de finishOnKey.
En algunos casos, cuando se utiliza el atributo finishOnKey, es posible que no se grabe la última parte del audio (aproximadamente un segundo antes de pulsar la tecla).
maxLength
El atributo maxLength te permite establecer la duración máxima de la grabación en segundos. Si ajustas maxLength a 30, la grabación finalizará de forma automática después de que hayan transcurrido 30 segundos de tiempo grabado. Los valores predeterminados son 3600 segundos (una hora) para una grabación normal y 120 segundos (dos minutos) en una grabación transcrita. Las llamadas de Twilio Client usando <Record> están limitadas a 600 segundos (diez minutos).
playBeep
El atributo playBeep te permite alternar si reproducir un sonido antes del inicio de una grabación. Si ajustas el valor a false, no se reproducirá ningún sonido de pitido.
trim
El atributo trim te permite especificar si deseas recortar el silencio inicial y final de tus archivos de audio. El valor predeterminado es trim-silence, que elimina cualquier silencio al principio y al final de la grabación. Esto puede provocar que la duración de la grabación sea ligeramente inferior a la duración de la llamada.
recordingStatusCallback
El atributo recordingStatusCallback toma una dirección URL relativa o absoluta como argumento. Si se brinda una URL de recordingStatusCallback, Twilio hará una solicitud GET o POST a la URL especificada cuando se pueda acceder a la grabación.
Parámetros de solicitud
Twilio transferirá los siguientes parámetros con tu solicitud a la URL de recordingStatusCallback:
| Parámetro | Descripción |
|---|---|
| AccountSid | El identificador único de la cuenta responsable de esta grabación. |
| CallSid | Un identificador único de la llamada asociada a la grabación. |
| RecordingSid | El identificador único de la grabación. |
| RecordingUrl | La URL del audio grabado. |
| RecordingStatus | Estado de la grabación. Estos son los valores posibles: completed, failed. |
| RecordingDuration | Duración de la grabación, en segundos. |
| RecordingChannels | El número de canales en el archivo de grabación final como un número entero. Solo se admite un canal para el verbo <Record>. |
| RecordingSource | El método de inicio utilizado a fin de crear esta grabación. RecordVerb es devuelto para grabaciones iniciadas mediante el verbo <Record>. |
recordingStatusCallbackMethod
Este atributo indica qué método HTTP se debe utilizar cuando se solicita recordingStatusCallback. El valor predeterminado es POST.
recordingStatusCallbackEvent
recordingStatusCallbackEvent te permite especificar qué cambios de estado de grabación deben generar un webhook para la URL especificada en el atributo recordingStatusCallback. Estos son los valores disponibles:
in-progress: la grabación ha comenzado.completed: la grabación está completa y disponible.absent: la grabación está ausente e inaccesible.
Para especificar más de un valor, sepáralos con un espacio. El valor predeterminado es completed.
transcribe
El atributo transcribe le dice a Twilio que deseas una representación de texto del audio de la grabación. Twilio transferirá esta grabación a nuestro motor de conversión de voz a texto e intentará convertir el audio en texto legible. La opción transcribe no está habilitada de forma predeterminada. Si no deseas realizar la transcripción, solo no incluyas el atributo transcribe.
Notas
- La transcripción es una función pagada. Si incluyes un atributo
transcribeotranscribeCallbacken tu verboRecord, se te cobrará a tu cuenta. Consulta la página de precios para conocer nuestros precios de transcripción. - La transcripción solo se admite en inglés estadounidense.
Además, en la actualidad, la transcripción está limitada a grabaciones iniciadas mediante el verbo <Record> de TwiML con una duración superior a 2 segundos e inferior a 120 segundos. Si solicitas una transcripción para una grabación fuera de estos límites de duración, Twilio escribirá una advertencia en tu registro de depuración en lugar de transcribir la grabación.
transcribeCallback
El atributo transcribeCallback se utiliza junto con el atributo transcribe. Te permite especificar una URL a la que Twilio hará una solicitud POST asincrónica cuando la transcripción esté completa. No se trata de una solicitud para TwiML y la respuesta no cambiará el flujo de llamadas, pero la solicitud contendrá los parámetros de solicitud estándar de TwiML, así como los parámetros específicos de transcripción.
Si se especifica transcribeCallback, entonces no es necesario especificar transcribe=true; está implícito. Si especificas transcribe=true sin una transcribeCallback, la transcripción completada se almacenará para que la recuperes más tarde (consulta la sección de API REST de Transcripciones), pero Twilio no notificará tu aplicación de forma asincrónica.
Twilio no solicitará la URL de transcribeCallback si la grabación de voz está ausente o falta.
El atributo de URL transcribeCallback se considera que no es PII.
Parámetros de solicitud
Twilio pasará los siguientes parámetros con su solicitud a la URL transcribeCallback:
| Parámetro | Descripción |
|---|---|
| TranscriptionSid | El ID único de 34 caracteres de la transcripción. |
| TranscriptionText | El texto de la transcripción. |
| TranscriptionStatus | El estado del intento de transcripción: ya sea completed o failed. |
| TranscriptionUrl | La URL del recurso API REST de la transcripción. |
| RecordingSid | El ID único de 34 caracteres de la grabación a partir de la cual se generó la transcripción. |
| RecordingUrl | La URL del recurso de grabación de origen de la transcripción. |
| CallSid | Un identificador único para esta llamada, generado por Twilio. |
| AccountSid | El ID de tu cuenta de Twilio. Tiene 34 caracteres y siempre comienza con las letras AC. |
| From | El número de teléfono o identificador de cliente de la persona que inició la llamada. El formato de los números de teléfono tiene un signo de + y el código del país; por ejemplo,+16175551212 (formato [E.164][e164]). Los identificadores de cliente comienzan con el esquema URI client:; por ejemplo, en el caso de una llamada desde un cliente llamado tommy, el parámetro From será client:tommy. |
| To | El número de teléfono o identificador de cliente de la persona a la que se llama. El formato de los números de teléfono tiene un signo de + y el código del país; por ejemplo,+16175551212 (formato [E.164][e164]). Los identificadores de cliente comienzan con el esquema URI client:; por ejemplo, en el caso de una llamada a un cliente llamado joey, el parámetro To será client:joey. |
| CallStatus | Estado descriptivo de la llamada. El valor es uno de estos: queued, ringing, in-progress, completed, busy, failed o no-answer. Consulta la sección CallStatusa fin de obtener más información. |
| ApiVersion | La versión de la API de Twilio utilizada para manejar esta llamada. En el caso de las llamadas entrantes, esto está determinado por la versión de la API establecida en el número al que se llama. En el caso de las llamadas salientes, se trata de la versión de la API utilizada por la solicitud API REST de la llamada saliente. |
| Direction | Una cadena que describe la dirección de la llamada: inbound para llamadas entrantes, outbound-api en llamadas iniciadas mediante la API REST o outbound-dial en llamadas iniciadas por un verbo <Dial>. |
| ForwardedFrom | Este parámetro se establece solo cuando Twilio recibe una llamada desviada, pero su valor depende del operador móvil del agente de llamada, incluida la información cuando se reenvía. No todos los operadores móviles admiten la transferencia de esta información. |
Reglas de anidamiento
No puedes anidar ningún verbo dentro de <Record> y no puedes anidar <Record> en ningún otro verbo.
Consulta también
- El recurso de grabación de la API REST de Twilio
- El recurso de transcripción de API REST de Twilio
Ejemplos
Ejemplo 1: grabación Simple
Twilio ejecutará el verbo <Record>, lo que hará que el agente de llamada escuche un pitido y comience la grabación. Si el agente de llamada permanece en silencio durante más de cinco segundos, pulsa la tecla # o se llega al tiempo de grabación de maxlength, Twilio hará una solicitud HTTP de POST a la URL predeterminada de action (es decir, la URL actual del documento) con los parámetros RecordingUrl y RecordingDuration.
Ejemplo 2: grabar un mensaje de buzón de voz
En este ejemplo, se muestra un mensaje de buzón de voz simple. Se le pide al agente de llamada que deje un mensaje cuando suena el pitido. El verbo <Record> emite un pitido y comienza a grabar hasta 20 segundos de audio.
- Si el agente de llamada habla menos de 20 segundos y, luego, está en silencio durante 5 segundos, Twilio hace una solicitud GET a la URL de
action. El verbo<Say>nunca se alcanza. - Si la persona que llama habla durante los 20 segundos completos, Twilio hace una solicitud GET a la URL de
action. El verbo<Say>nunca se alcanza.
Ejemplo 3: transcribir una grabación
Twilio grabará al agente de llamada. Una vez finalizada la grabación, Twilio transcribirá la grabación y hará una solicitud HTTP de POST a la URL de transcribeCallback con un parámetro que contiene una transcripción de la grabación.
Consejos y usos avanzados
- Twilio recortará el silencio inicial y final de tus archivos de audio. Esto puede hacer que la duración de los archivos sea ligeramente menor que el tiempo que pasa el agente de llamada grabándolos.
¿Necesitas ayuda?
Todos la necesitamos a veces; la programación es difícil. Obtén ayuda ahora de nuestro equipo de soporte, o recurre a la sabiduría de la multitud visitando Stack Overflow Collective de Twilio o navegando por la etiqueta de Twilio en Stack Overflow.