Esta guía conecta el WhatsApp y el teléfono de Clínica del Sol a través de Twilio. Para WhatsApp directo con Meta, mirá la guía Conectar Meta. Cómo funciona una llamada una vez conectada —la voz, el saludo, cómo se corta— está en el capítulo Voz.
Los pasos del lado de Twilio siguen la consola de Twilio al momento de escribir esta guía. Lo que dice del lado de la plataforma está verificado contra el código.
Antes de empezar
- Una cuenta de Twilio por tenant, compartida por WhatsApp y voz.
- Un remitente de WhatsApp por tenant. Todas las respuestas salen de ese remitente.
- El agente lo decide la URL, no una opción de la pantalla. Cada número o remitente de Twilio apunta a la URL de un agente; cambiar de agente es cambiar la URL en Twilio.
- El tenant necesita WhatsApp o voz habilitados en sus funcionalidades (capítulo 8).
La configuración está en Integraciones → Twilio, con dos pestañas: WhatsApp y Voz.
1. Credenciales
En la consola de Twilio, en la información de la cuenta, copiá el Account SID (empieza con AC) y el Auth Token.
En la plataforma, Credenciales Twilio → Configurar, cargá los dos y guardá. Al guardar, la plataforma prueba las credenciales contra Twilio: si Twilio las rechaza, no se guardan. Después aparece Validar para volver a probarlas.
Usá el Auth Token principal, no una clave de API (SK…): la plataforma lo necesita para verificar la firma de cada mensaje y llamada que manda Twilio, y no acepta claves de API.
2. WhatsApp
El remitente
Configurar WhatsApp pide el Remitente WhatsApp: el número de WhatsApp habilitado en Twilio, en formato internacional, por ejemplo +5491155550000.
- Para probar, podés usar el Sandbox de WhatsApp de Twilio. El remitente es el número del sandbox, y cada persona que quiera probar tiene que mandarle primero el mensaje
join <código>que indica Twilio. - Para producción, el remitente es el número aprobado en Messaging → Senders → WhatsApp senders.
- No uses un Messaging Service SID (
MG…), aunque el campo lo sugiera: la plataforma envía siempre desde un número, y con un SID el envío falla.
La URL del webhook
La URL que hay que pegar en Twilio es:
{URL de la API}/webhook/whatsapp/{tenant}/{agente}
En la instalación de Synaptic Links, para el agente de turnos de la clínica:
https://ai.synapticlinks.com.ar/api/webhook/whatsapp/clinica-del-sol/turnos-clinica
La URL que muestra la pantalla está incompleta: termina en el tenant y le falta la clave del agente. Copiala y agregale /{clave-del-agente} al final. La clave está en el detalle del agente.
En Twilio, en la configuración del remitente (o del Sandbox), pegala en "When a message comes in", con método POST. Dejá vacío el callback de estado: la plataforma no lo usa.
Probar
Con el remitente guardado, Editar configuración muestra Mensaje de prueba: un número y un texto, para comprobar que la plataforma puede enviar. Para comprobar que recibe, escribile al número desde un teléfono; la conversación aparece en Monitoreo → Sesiones.
Cómo se comporta
- Responde por la API de Twilio, no en la respuesta al webhook: la plataforma le contesta a Twilio enseguida y procesa el mensaje después, así nunca se pasa del tiempo de espera de Twilio.
- Respuestas largas se dividen en mensajes de hasta 1.600 caracteres. Si Twilio responde con error temporal, se reintenta dos veces.
- Imágenes: hasta 3 por mensaje, si el agente acepta imágenes como adjuntos (capítulo 11). Si no, el agente recibe un texto que dice que llegó una imagen.
- Audios: se transcriben y el agente recibe el texto.
- Documentos: no se descargan; el agente recibe un aviso de que llegó un archivo.
- Botones y listas: las preguntas con opciones del workflow se muestran como botones o lista de WhatsApp.
- Una conversación por persona y remitente, que se renueva tras 24 horas sin mensajes (capítulo 6).
Respuesta progresiva
En la configuración de WhatsApp, la sección Respuesta Progresiva tiene Habilitar modo progresivo: en lugar de esperar la respuesta completa, la plataforma manda partes a medida que el agente las genera, con un intervalo y un máximo de mensajes.
Las opciones de la tarjeta WhatsApp en la pestaña Canales de cada agente —mensajes de acuse, avisos mientras usa herramientas, aviso por demora, quitar formato— solo se aplican con el modo progresivo activado. Sin él, la respuesta llega en un solo envío y esas opciones no tienen efecto.
3. Voz
Recibir llamadas
En Twilio, en Phone Numbers, abrí el número y, en la configuración de voz, poné en "A call comes in" un webhook con método POST:
{URL de la API}/webhook/voice/{tenant}/{agente}
La pantalla no muestra esta URL: armala igual que la de WhatsApp. El resto —voz, idioma, saludo, tiempo de inactividad— se configura en la tarjeta Voz de la pestaña Canales del agente (capítulo 14).
Llamadas salientes
En la pestaña Voz de Twilio:
- Activá Habilitar llamadas salientes desde nodos.
- En Números de origen permitidos, elegí los números de tu cuenta desde los que el agente puede llamar. La lista sale de tu cuenta de Twilio.
- Elegí el Origen sugerido para los mapeos de llamada, que tiene que ser uno de los permitidos.
- Guardá. La plataforma genera las herramientas para iniciar, consultar y modificar llamadas, que los workflows usan como cualquier herramienta (capítulo 5).

Cuando no llegan mensajes ni llamadas
| Síntoma | Causa probable | Qué hacer |
|---|---|---|
| Twilio muestra error 404 en el webhook | La URL no tiene la clave del agente | Agregá /{clave-del-agente} al final |
| Twilio muestra error 403 | La firma no coincide: la URL en Twilio no es exactamente la pública, o cambió el Auth Token | Pegá la URL exacta, con https y el mismo host, sin barra final, y revisá que el Auth Token guardado sea el vigente |
| Twilio no muestra error, pero el agente no responde | La clave del agente no existe en el tenant | Revisá la clave en el detalle del agente |
| Llega el mensaje pero la respuesta falla | El remitente es un Messaging Service SID, o está mal escrito | Usá el número en formato +… |
| Con el Sandbox, el mensaje de una persona no llega | Esa persona no se unió al Sandbox | Que mande join <código> primero |
| Una respuesta muchas horas después no se entrega | Pasaron más de 24 horas desde el último mensaje de la persona | Fuera de esa ventana, WhatsApp solo acepta plantillas aprobadas |
| Las llamadas no se atienden | La URL de voz es incorrecta, o el tenant tiene política de privacidad | Revisá la URL; con política de privacidad, la voz por Twilio no está disponible (capítulo 9) |
| Muchas llamadas seguidas fallan | Límite de 10 pedidos por minuto en el webhook de voz | Distribuí las llamadas o pedí un ajuste |
Dónde termina
- La pantalla de WhatsApp muestra una URL incompleta y la de voz no muestra ninguna: hay que armarlas a mano.
- Un remitente de WhatsApp por tenant. Se pueden apuntar varios números a distintos agentes, pero todas las respuestas salen del remitente configurado.
- No hay protección contra mensajes repetidos: si Twilio reenvía un mensaje, el agente puede responder dos veces.
- No se registran estados de entrega ni se usan callbacks de estado.
- No se controla la ventana de 24 horas: una respuesta fuera de la ventana falla en Twilio y aparece como error en la ejecución.
- Las opciones de WhatsApp del agente solo funcionan con la respuesta progresiva.
- No se aceptan claves de API ni Messaging Services, solo Account SID, Auth Token y un número.
Para revisar
- Las credenciales están validadas y el Auth Token es el vigente.
- El remitente es un número en formato
+…. - Cada URL en Twilio termina en la clave del agente correcto y usa POST.
- Un mensaje de prueba sale, y un mensaje desde un teléfono aparece en Sesiones.
- Si se usan las opciones de WhatsApp del agente, la respuesta progresiva está activada.
- Los números de origen de llamadas salientes son solo los que el agente debe usar.