Cómo Funciona
El pipeline completo del bot: desde que llega un mensaje de WhatsApp hasta que el bot responde automáticamente.
Cómo Funciona
Cuando un cliente le envía un mensaje por WhatsApp, el bot de Trochai ejecuta un pipeline de procesamiento inteligente que tarda solo unos segundos. Esta página explica cada etapa del proceso.
Visión general del pipeline
El bot sigue estos pasos cada vez que un cliente envía un mensaje:
Recepción del mensaje
Meta (WhatsApp) envía el mensaje a Trochai a través de un webhook seguro. El sistema valida la autenticidad del mensaje mediante firma HMAC y lo almacena en la base de datos.
Agrupación de mensajes (debounce)
En lugar de responder a cada mensaje individual, el bot espera brevemente para agrupar mensajes consecutivos. Esto es importante porque muchas personas envían múltiples mensajes seguidos. El sistema espera 15 segundos de silencio o un máximo de 1 minuto desde el primer mensaje para crear un "lote" completo.
Procesamiento del lote
Un proceso automático revisa cada minuto si hay lotes listos para procesar. Cuando encuentra un lote listo, concatena todos los mensajes y los envía al pipeline de IA.
Verificación de estado
Antes de procesar, el bot verifica:
- Que el bot esté habilitado a nivel global (ajustes de la organización)
- Que el bot esté habilitado para esa conversación específica
- Que la organización tenga mensajes de IA disponibles en su plan
Clasificación de intención
El bot analiza el mensaje del cliente y determina qué quiere hacer. Clasifica el mensaje en una de 8 intenciones posibles: buscar una propiedad, agendar una visita, preguntar sobre financiamiento, etc.
Si el bot no está seguro de la intención (confianza menor al 70%), escala automáticamente la conversación a un agente humano.
Extracción de filtros y búsqueda
Para intenciones relacionadas con propiedades, el bot extrae los criterios de búsqueda mencionados por el cliente (ubicación, precio, habitaciones, tipo de propiedad) y ejecuta una búsqueda híbrida combinando filtros estructurados con búsqueda semántica.
Generación de respuesta
Con la intención clasificada, los resultados de búsqueda y el historial de la conversación, el bot genera una respuesta natural en español (o inglés, según la configuración). La respuesta incluye detalles de propiedades con enlaces, información de proyectos y preguntas de seguimiento.
Envío por WhatsApp
La respuesta se envía al cliente a través de la API de WhatsApp de Meta. También se guarda en la base de datos como un mensaje enviado por el bot, visible en la bandeja de entrada.
Debounce: Por qué el bot espera antes de responder
Es muy común que los clientes envíen mensajes de esta forma:
Hola Busco una casa En Escazú Qué tenga 3 habitaciones
Sin el sistema de debounce, el bot respondería 4 veces a cada mensaje individual. Con el debounce, el bot espera a que el cliente termine de escribir y agrupa todo en una sola solicitud inteligente.
Cómo funciona el debounce:
| Parámetro | Valor | Descripción |
|---|---|---|
| Ventana de silencio | 15 segundos | Si el cliente no envía otro mensaje en 15 segundos, el lote se considera completo |
| Tiempo máximo | 1 minuto | Tiempo máximo desde el primer mensaje. Si el cliente sigue escribiendo, el lote se procesa igualmente |
| Frecuencia de revisión | Cada minuto | Un proceso automático revisa si hay lotes listos para procesar |
Mientras el bot recopila mensajes, aparece un indicador de "recopilando mensajes..." en la bandeja de entrada. Cuando empieza a generar la respuesta, el indicador cambia a "escribiendo..." para que los agentes sepan que el bot está trabajando.
Motor de IA
El bot utiliza OpenAI (GPT) como motor principal para generar respuestas, y el modelo text-embedding-3-small para crear vectores de búsqueda semántica (embeddings). Si OpenAI experimenta problemas temporales, el sistema cambia automáticamente a un proveedor alternativo para mantener el servicio sin interrupciones.
Contexto de la conversación
El bot mantiene contexto de la conversación para dar respuestas coherentes. En cada interacción, el bot:
- Lee los últimos 10 mensajes del historial de la conversación
- Distingue entre mensajes del usuario, del bot y de agentes humanos
- Usa el historial para entender el contexto (por ejemplo, si el cliente ya preguntó por una propiedad específica)
Esto permite interacciones naturales como:
Cliente: Busco un apartamento en Escazú Bot: [muestra 3 opciones] Cliente: El segundo tiene parqueo? Bot: [responde sobre el segundo apartamento]
Respuestas optimizadas para WhatsApp
Las respuestas del bot están optimizadas para la experiencia de WhatsApp:
- Longitud controlada: Máximo ~500 caracteres para mantener la legibilidad
- Formato compatible: Solo usa negritas (compatible con WhatsApp), sin markdown complejo
- Enlaces directos: Incluye enlaces a las páginas de detalle de propiedades y proyectos
- Tono amigable: Usa emojis de forma moderada para hacer la conversación más natural
Seguridad del bot
El bot incluye múltiples capas de seguridad:
- Anti-inyección de prompt: El bot ignora intentos de manipulación en los mensajes de los clientes (como instrucciones para cambiar su comportamiento)
- Aislamiento de datos: El bot solo accede a las propiedades y datos de su organización. Nunca comparte información entre organizaciones
- Límite de tokens: Los mensajes de los clientes se truncan para evitar abusos
- Respuestas basadas en datos: El bot solo recomienda propiedades que existen en su inventario, nunca inventa información
Diagrama del flujo
WhatsApp → Webhook → Validacion HMAC → Guardar mensaje
↓
Agregar a lote (debounce)
↓
Cron (cada minuto) procesa lotes listos
↓
Verificar bot habilitado + limites de IA
↓
Clasificar intencion (8 tipos)
↓
┌──────────────────────────────────┐
│ Segun la intencion: │
│ - Buscar propiedades/proyectos │
│ - Agendar visita │
│ - Responder pregunta general │
│ - Escalar a agente humano │
└──────────────────────────────────┘
↓
Generar respuesta con IA
↓
Enviar por WhatsApp + guardar en DBSiguientes pasos
- Intenciones del bot -- Los 8 tipos de mensajes que el bot reconoce
- Base de conocimiento -- Búsqueda híbrida y embeddings
- Configuración -- Ajuste el comportamiento del bot