Twilio es un proveedor internacional de telecomunicaciones. Permite que el bot llame a los clientes y los conecte con sus empleados en más de 100 países donde Twilio ofrece números de teléfono, incluidos México, Brasil, Turquía, España, Alemania, Francia, los Emiratos Árabes Unidos, Tailandia, Malasia y muchos otros.

Lo que obtienes después de conectar Twilio:

  • llamar a un cliente con un clic directamente desde la tarjeta de conversación;
  • llamadas automatizadas basadas en escenarios: el bot llama al cliente y lee un mensaje de texto en voz alta;
  • llamadas grupales: el bot llama al cliente y lo conecta con el primer empleado disponible;
  • grabación de todas las llamadas, con un enlace de grabación almacenado en las variables del pedido;
  • eventos de llamada (llamando, respondida, completada) directamente en la conversación: puedes usarlos para crear escenarios.

Paso 1. Crea una cuenta y compra un número

  1. Regístrate en twilio.com y completa el proceso de verificación.
  2. En la consola de Twilio, abre Phone Numbers → Buy a number y selecciona un número en el país que necesites. Asegúrate de que Voice esté habilitado: algunos números solo admiten SMS y no se pueden usar para llamadas.

Paso 2. Copia tus credenciales de acceso

En la página principal de la consola de Twilio, en Account Info, encontrarás dos valores:

Elemento Cómo se ve
Account SID ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Auth Token oculto; haz clic en Show para revelarlo

⚠️ Copia el Auth Token exactamente como aparece, sin espacios adicionales antes o después. Lo usamos para verificar la autenticidad de cada solicitud de Twilio. Un solo carácter invisible adicional puede hacer que las llamadas funcionen pero los eventos de llamada no aparezcan en la conversación.

El Auth Token proporciona acceso completo a tu cuenta de Twilio y a los fondos que contiene. No lo envíes por mensajeros ni lo publiques en ningún lugar.

Paso 3. Conecta Twilio en tu cuenta

Abre Project → Integrations → Telephony → Twilio y completa los tres campos:

Campo Qué ingresar
Account SID del Paso 2
Auth Token del Paso 2
Twilio Number el número que compraste, en formato internacional: +14155550100

El número debe ingresarse en formato E.164: +, código de país y número de teléfono, sin espacios, paréntesis ni guiones.

Después de guardar, aparecerá una URL de devolución de llamada en la página. Cópiala. Luego abre la configuración de tu número comprado en la consola de Twilio y, en Voice & Fax, configura:

  • A call comes in → Webhook → pega la URL copiada y selecciona HTTP POST.

Sin esta configuración, las llamadas salientes funcionarán, pero las llamadas entrantes y los eventos de llamada en la conversación no.

Para desconectar la integración, borra el campo Account SID y guarda la configuración.

Paso 4. Agrega los números de teléfono de los empleados

Twilio llama a los empleados a números de teléfono normales: aquí no hay extensiones internas.

Abre la pestaña Team, selecciona un empleado y completa el campo Twilio Phone Number con su número de teléfono completo en el mismo formato:

+905551112233

Sin este número, el botón de llamada en la tarjeta del cliente no funcionará para ese empleado.

Llamar desde la tarjeta del cliente

Aparecerá un botón de llamada junto al número de teléfono del cliente en la tarjeta de conversación. Al hacer clic, se inicia la siguiente secuencia:

  1. Twilio llama al empleado: el empleado ve tu número de Twilio como identificador de llamada.
  2. El empleado responde la llamada.
  3. Solo entonces Twilio llama al cliente y conecta a las dos partes.

El orden es intencional: el cliente no tiene que escuchar el tono de llamada mientras el empleado llega a su teléfono. Si el empleado no responde, el cliente no es llamado en absoluto.

Llamadas desde escenarios de bot

Hay cuatro métodos disponibles en la calculadora.

twilio_employee_call(client_phone, employee_phone, caller_id)

Conecta a un empleado con un cliente. Funciona igual que el botón de llamada en la tarjeta del cliente: primero se llama al empleado y luego al cliente.

twilio_employee_call(client_phone, "+905551112233")

El tercer argumento es opcional. Especifica el número de teléfono que el cliente verá como identificador de llamada. Por defecto, se usa tu número de Twilio.

twilio_group_call(client_phone, employee_phones, caller_id)

Llama al cliente y, una vez que el cliente responde, llama simultáneamente a todos los empleados de la lista especificada. La llamada se conecta con el primer empleado que responda.

twilio_group_call(client.phone, "+905551112233,+905554445566,+905557778899")

⚠️ El orden está invertido aquí. A diferencia del método anterior, el cliente responde primero y puede escuchar varios segundos de silencio mientras Twilio llama a los empleados. Esta es una limitación de Twilio: llamar a un grupo simultáneamente y conectar a la primera persona que responda solo funciona así. Si es importante que el cliente no tenga que esperar, usa twilio_employee_call.

twilio_play_message(client_phone, text, voice, language)

Llama al cliente y lee el texto especificado usando voz sintetizada. Esto es útil para recordatorios de citas, confirmaciones de pedidos y notificaciones de entrega.

twilio_play_message(client.phone, "¡Hola! Este es un recordatorio de su cita mañana a las 3:00 PM.", "alice", "es-ES")

La voz alice es universal y admite los principales idiomas, incluidos tr-TR, es-ES, es-MX, pt-BR, de-DE, fr-FR, en-US, ru-RU y ar-XA.

Especifica siempre el idioma explícitamente; de lo contrario, Twilio puede leer el texto con pronunciación en inglés.

No incluyas contraseñas, códigos de verificación u otra información sensible en el mensaje: la llamada puede ser respondida por el buzón de voz.

Devuelve un enlace a la grabación de la llamada. Rara vez se necesita porque el enlace normalmente aparece automáticamente (ver la siguiente sección). Puede ser útil si no se recibió el enlace de grabación y es necesario solicitarlo nuevamente.

twilio_get_record_link()

Si no se proporciona ningún argumento, se usa la llamada más reciente del cliente.

Variables y eventos

Después de cada llamada, el bot almacena las siguientes variables en el pedido del cliente:

Variable Qué contiene
twilio_call_id Identificador de la llamada de Twilio
twilio_call_disposition Resultado de la llamada: completed, busy, no-answer, failed, canceled
twilio_call_duration Duración de la llamada en segundos
twilio_record_link Enlace a la grabación
twilio_record_id Identificador de la grabación de Twilio

Los eventos en el formato twilio_call_event <status> se envían a la conversación. Puedes usarlos como condiciones en tus escenarios:

Evento Cuándo se envía
twilio_call_event initiated la llamada ha sido creada
twilio_call_event ringing el teléfono está sonando
twilio_call_event answered la llamada ha sido respondida
twilio_call_event completed la llamada ha terminado
twilio_call_event busy / no-answer / failed / canceled la llamada no se pudo completar
twilio_call_event recording la grabación de la llamada está lista

⚠️ Espera el evento recording antes de usar el enlace de grabación, no el evento completed. Twilio procesa el archivo de grabación después de que la llamada ya ha terminado. En el momento en que se recibe el evento completed, la variable twilio_record_link aún está vacía. Por lo tanto, un escenario que envía la grabación a un gerente o CRM debe activarse con el evento recording.

Un escenario típico de "no se pudo contactar al cliente — envíale un mensaje" funciona así: condición para twilio_call_event no-answer o busy → enviar un mensaje al cliente.

Grabaciones de llamadas

La grabación está habilitada por defecto para todas las llamadas que involucran a un empleado. Se graban ambos lados de la conversación desde el momento en que se responde la llamada. Los archivos se almacenan en tu cuenta de Twilio y Twilio los factura.

⚠️ La URL twilio_record_link apunta directamente a Twilio y está protegida por las credenciales de tu cuenta. No puedes simplemente abrirla en un navegador ni enviarla a un cliente: se mostrará un error de acceso. Para descargar la grabación, abre la consola de Twilio y ve a Monitor → Logs → Calls, luego busca la llamada usando su twilio_call_id.

⚖️ La grabación de llamadas está regulada por la ley. En muchos países, incluidos Alemania, Francia, España y en muchos estados de EE. UU., puede ser necesario el consentimiento de ambas partes y, en algunos casos, se debe reproducir un aviso hablado al comienzo de la llamada. Como propietario de la cuenta de Twilio, eres responsable de cumplir con los requisitos aplicables. Si estas reglas te aplican, comienza la llamada con un aviso de grabación o deshabilita la grabación en la configuración de tu número de Twilio.

Solución de problemas

La llamada no se crea y se devuelve un error de autenticación

El Account SID o el Auth Token son incorrectos. Cópialos nuevamente desde la consola de Twilio. Las causas más comunes son un espacio adicional o copiar accidentalmente el Test Token en lugar del Auth Token principal.

Las llamadas funcionan, pero no hay eventos ni grabaciones en la conversación

La URL de devolución de llamada no se ha configurado en la configuración del número de Twilio (ver Paso 3), o está configurada con el método HTTP incorrecto. El método debe ser HTTP POST.

Otra causa común es que el Auth Token se cambió en Twilio pero el token antiguo aún está configurado en tu cuenta. En este caso, las firmas de solicitud ya no coinciden, por lo que todas las devoluciones de llamada se rechazan.

Error 21606 o "From number not valid"

El número ingresado en el campo Twilio Number no fue comprado bajo tu cuenta de Twilio o no admite llamadas de voz.

Abre Phone Numbers → Manage → Active numbers y asegúrate de que el número esté listado y tenga capacidad de Voice.

Error 21215 — Geo Permissions

Por defecto, Twilio bloquea llamadas a muchos países como medida de prevención de fraude.

Abre Voice → Settings → Geo Permissions y habilita los destinos que necesites.

Un cliente llama, pero se crea una tarjeta de conversación para el número del empleado

La devolución de llamada está configurada con la URL incorrecta. Copia la URL de devolución de llamada nuevamente desde la página de integración, asegurándote de copiar toda la URL, incluido todo lo que está después del signo de interrogación.

Cuenta de prueba: Twilio reproduce un mensaje de voz antes de la llamada

Este es el comportamiento estándar de las cuentas de prueba de Twilio. Las cuentas de prueba también solo pueden llamar a números de teléfono verificados.

Agrega fondos a tu cuenta y actualiza a una cuenta completa de Twilio.