Documentación de Flujos del Chatbot

Sistema de detección inteligente de intenciones y gestión de estados

Resumen General

Filosofía del Sistema: El chatbot utiliza un sistema de detección inteligente basado en OpenAI para identificar intenciones del usuario y gestionar múltiples flujos de conversación simultáneamente, desde captura de leads hasta procesos especializados como facturación y cotizaciones.

El sistema se basa en tres componentes principales:

1. Detección de Intención

Analiza cada mensaje del usuario con OpenAI para determinar si existe una intención de registro, modificación, cancelación o consulta.

es_registro confidence

2. Gestión de Estado

Mantiene el contexto de la conversación a través de variables persistentes que controlan el flujo activo.

captura_en_progreso lead_pendiente_confirmacion

3. Clasificación de Flujo

Determina el tipo de proceso basándose en las instrucciones personalizadas (b_template) y el contexto de la conversación.

flow_type specialized_flow

Variables de Estado

Variables que controlan el comportamiento del chatbot y determinan el flujo activo:

es_registro
Type: Boolean
Descripción: Indica si el mensaje del usuario contiene una intención de registro o captura de datos.

Valores:
  • true - Usuario quiere registrar información
  • false - Consulta normal o conversación
Confianza mínima: 0.7
flow_type
Type: String
Descripción: Identifica el tipo específico de flujo o proceso activo en la conversación.

Valores posibles:
  • lead_capture - Captura de datos en progreso
  • facturacion - Proceso de facturación
  • cotizacion - Proceso de cotización
  • lead_confirmed - Registro confirmado
  • generic - Flujo genérico
specialized_flow
Type: Boolean
Descripción: Indica si el flujo actual es especializado (facturación, cotización) o genérico (lead capture).

Detección: Analiza el b_template con OpenAI buscando:
  • Menciones de "FACTURACIÓN", "INVOICE", "Sales_Header"
  • Menciones de "COTIZACIÓN", "QUOTE"
  • Queries SQL específicas
Confianza mínima: 0.7
captura_en_progreso
Type: Boolean
Descripción: Indica que el bot está en modo de captura activa, solicitando campos de forma secuencial.

Comportamiento:
  • Activa cuando es_registro = true
  • Desactiva detección de confirmaciones
  • Fuerza interpretación como datos de captura
lead_pendiente_confirmacion
Type: Boolean
Descripción: Todos los campos obligatorios fueron capturados y el bot está esperando confirmación del usuario.

Estados siguientes:
  • Confirmación → lead_confirmed
  • Corrección → lead_correction
  • Cancelación → Limpia estado
registro_completado
Type: Boolean
Descripción: El registro fue completado exitosamente (guardado en BD y/o API externa).

Efecto:
  • Previene reactivación del flujo de captura
  • Permite nuevos registros solo si usuario inicia explícitamente
  • Guarda last_created_id para referencias futuras
forzar_captura_leads
Type: Boolean
Descripción: Flag temporal para forzar inicio de captura en el siguiente mensaje.

Activado por:
  • API Integration detecta necesidad de datos
  • Detección de confirmación de contacto
  • Comandos explícitos de "actualizar" o "registrar"
Auto-limpieza: Se elimina después del próximo mensaje
lead_operation_type
Type: String
Descripción: Tipo de operación CRUD que el usuario desea realizar.

Valores:
  • create - Crear nuevo registro (default)
  • update - Modificar registro existente
  • delete - Eliminar registro
  • read - Consultar registro
Persistencia: Se mantiene durante todo el flujo

Tipos de Flujo (flow_type)

Clasificación detallada de todos los estados de flujo que el sistema puede retornar:

Flujos de Captura

lead_capture_initiated

Cuándo: API Integration detecta intención de modificar/actualizar pero faltan datos necesarios.

Comportamiento: Activa forzar_captura_leads = true para el siguiente mensaje.

{
    "flow_type": "lead_capture_initiated",
    "metadata": {
        "api_target": "api_cotizaciones",
        "operation": "update",
        "resource_id": "123"
    }
}

lead_capture

Cuándo: Bot está solicitando campos de forma secuencial. Todavía faltan campos obligatorios.

Variable de control: captura_en_progreso = true

{
    "flow_type": "lead_capture",
    "metadata": {
        "datos_capturados": {"nombre": "Juan", "email": "juan@email.com"},
        "campos_faltantes": ["telefono", "empresa"]
    }
}

lead_validation_error

Cuándo: Usuario confirmó pero los datos no pasan la validación de la API.

Comportamiento: Limpia estado de confirmación, solicita corrección de campos específicos.

{
    "flow_type": "lead_validation_error",
    "metadata": {
        "validation_errors": [
            {"field": "email", "error": "Formato inválido"},
            {"field": "telefono", "error": "Debe contener 8 dígitos"}
        ]
    }
}

lead_validation_error_pre_confirmation

Cuándo: Validación falla ANTES de mostrar confirmación (durante captura).

Comportamiento: Mantiene captura_en_progreso = true, solicita corrección inmediata.

{
    "flow_type": "lead_validation_error_pre_confirmation",
    "metadata": {
        "validation_errors": [{"field": "email", "error": "Email ya existe"}]
    }
}

Flujos de Confirmación

lead_confirmation_request

Cuándo: Todos los campos obligatorios fueron capturados. Bot solicita confirmación al usuario.

Variable de control: lead_pendiente_confirmacion = true

{
    "flow_type": "lead_confirmation_request",
    "metadata": {
        "datos_capturados": {
            "nombre": "Juan Pérez",
            "email": "juan@email.com",
            "telefono": "62141994",
            "empresa": "TechCorp"
        },
        "pendiente_confirmacion": true
    }
}

lead_confirmed

Cuándo: Usuario confirmó los datos y el registro fue exitoso (BD local + API externa).

Estado final: registro_completado = true

{
    "flow_type": "lead_confirmed",
    "metadata": {
        "registered_id": "CTZ-2024-001",
        "api_response": "success",
        "resource_type": "cotizacion"
    }
}

lead_correction

Cuándo: Usuario solicitó corregir datos después de la confirmación.

Comportamiento: Mantiene lead_pendiente_confirmacion = true, permite corrección de campos.

{
    "flow_type": "lead_correction",
    "metadata": {
        "datos_anteriores": {...},
        "campo_a_corregir": "telefono"
    }
}

Flujos de Error

lead_api_error

Cuándo: La API externa retornó un error controlado (400, 404, 422, etc.).

Comportamiento: Muestra error al usuario, NO limpia estado (permite retry).

{
    "flow_type": "lead_api_error",
    "metadata": {
        "api_error": "Customer not found",
        "status_code": 404,
        "api_name": "api_cotizaciones"
    }
}

lead_api_exception

Cuándo: Excepción no controlada al llamar la API (timeout, connection error, etc.).

Comportamiento: Muestra error genérico, mantiene datos en estado para retry.

{
    "flow_type": "lead_api_exception",
    "metadata": {
        "exception": "Connection timeout",
        "api_name": "api_cotizaciones"
    }
}

Flujos Especializados

Decisión Inteligente: El sistema detecta automáticamente si el b_template define un flujo especializado analizando su contenido con OpenAI, eliminando hardcodeos.

Detección de Flujo Especializado

El análisis se realiza en detectar_intencion_registro() cuando b_template tiene más de 200 caracteres:

// Prompt de análisis enviado a OpenAI
Analiza estas instrucciones personalizadas (B_TEMPLATE) y determina:

1. ¿Definen un flujo de negocio ESPECIALIZADO?
2. ¿O es un flujo GENÉRICO de captura de leads?

CRITERIOS:
- Si menciona "FACTURACIÓN", "INVOICE", "Sales_Header", SQL queries → specialized (facturacion)
- Si menciona "COTIZACIÓN", "QUOTE", SQL de cotizaciones → specialized (cotizacion)  
- Si solo pide nombre/email/teléfono sin proceso específico → generic (lead_capture)

Respuesta JSON:
{
    "is_specialized_flow": true/false,
    "flow_type": "facturacion|cotizacion|orden|lead_capture|generic",
    "confidence": 0.0-1.0,
    "reasoning": "Explicación"
}

Ejemplo: Flujo de Facturación

Configuración

es_registro = FALSE
flow_type = "facturacion"
specialized_flow = TRUE
confidence = 0.95

¿Por qué es_registro = FALSE?

Porque el análisis inteligente detectó que NO es un flujo genérico de lead capture. El b_template define un proceso especializado de facturación que requiere:

  • Inserción directa en base de datos MySQL
  • Múltiples tablas (Sales_Header, Sales_Lines)
  • Lógica de negocio específica (auto-generación de IDs, cálculos, etc.)
  • NO usar APIs externas de leads

Comportamiento del Sistema

Cuando specialized_flow = true y flow_type = "facturacion":

  1. El sistema NO activa lead_capture tradicional
  2. Delega extracción de datos a instrucciones del b_template
  3. Cuando usuario confirma → llama database_service.execute_database_operations()
  4. DatabaseService ejecuta INSERT directo en BD usando instrucciones IA
  5. Retorna flow_type = "facturacion" en metadata

Ejemplo: Flujo de Cotización

Configuración

es_registro = TRUE
flow_type = "lead_capture"
specialized_flow = FALSE
confidence = 0.85

¿Por qué es_registro = TRUE?

Porque las cotizaciones usan el flujo genérico de lead capture con validación de API externa. No requiere INSERT directo en BD.

Comparación: Facturación vs Cotización

Característica Facturación Cotización
es_registro FALSE TRUE
specialized_flow TRUE FALSE
flow_type "facturacion" "lead_capture"
Destino de datos INSERT directo MySQL POST a API REST
Validación Lógica en DatabaseService Schema de API config
Control de captura Instrucciones en b_template api_config fields + capture_order

Ciclo de Vida Completo

Flujo Normal (Lead Capture)

Usuario: "Quiero cotizar"
→
es_registro = TRUE
Bot: "¿Tu nombre?"
→
captura_en_progreso = TRUE
Usuario: "Juan Pérez"
→
datos: {nombre: "Juan Pérez"}
Bot: "¿Tu email?"
→
flow_type = "lead_capture"
Usuario: "juan@email.com"
→
datos: {..., email: "juan@..."}
Bot: "Confirma: Juan, juan@..."
→
lead_pendiente_confirmacion = TRUE
Usuario: "Sí, correcto"
→
Guardar BD + API
Bot: "¡Registrado!"
→
flow_type = "lead_confirmed"
registro_completado = TRUE

Flujo Especializado (Facturación)

Usuario: "Crear factura"
→
Análisis b_template
OpenAI: specialized_flow = TRUE
→
es_registro = FALSE
flow_type = "facturacion"
Bot extrae datos vía RAG
→
Conversación guiada por b_template
Usuario confirma datos
→
database_service.execute_operations()
INSERT en MySQL
→
Sales_Header + Sales_Lines
Bot: "Factura #INV-001"
→
flow_type = "facturacion"
invoice_created = TRUE

Ejemplos Prácticos

Ejemplo 1: Cotización Normal

Usuario: Hola, quiero una cotización para Sage 50 Bot: ¡Claro! Te ayudo con la cotización. ¿Cuál es tu nombre? [Estado] es_registro=TRUE, captura_en_progreso=TRUE, flow_type="lead_capture" Usuario: Juan Pérez Bot: Gracias Juan. ¿Cuál es tu email? [Estado] datos_capturados={nombre: "Juan Pérez"} Usuario: juan@empresa.com Bot: Perfecto. ¿Tu número de teléfono? [Estado] datos_capturados={nombre: "Juan Pérez", email: "juan@empresa.com"} Usuario: 62141994 Bot: Excelente. Por favor confirma: • Nombre: Juan Pérez • Email: juan@empresa.com • Teléfono: 62141994 • Producto: Sage 50 ¿Es correcto? [Estado] lead_pendiente_confirmacion=TRUE, flow_type="lead_confirmation_request" Usuario: Sí, correcto Bot: ¡Cotización registrada exitosamente! ID: CTZ-2024-001 [Estado] flow_type="lead_confirmed", registro_completado=TRUE, last_created_id="CTZ-2024-001"

Ejemplo 2: Facturación (Flujo Especializado)

Usuario: Necesito crear una factura Bot: [Análisis de b_template...] [Análisis IA] is_specialized_flow=TRUE, flow_type="facturacion", confidence=0.95 [Estado] es_registro=FALSE, specialized_flow=TRUE, flow_type="facturacion" Bot: Te ayudo a crear la factura. ¿Nombre del cliente? Usuario: Comercial López S.A. Bot: ¿Qué productos va a incluir en la factura? Usuario: 2 Sage 50 Platinum Bot: Factura: • Cliente: Comercial López S.A. • Producto: Sage 50 Platinum (x2) • Total: $1,200.00 ¿Confirmas? [Estado] lead_pendiente_confirmacion=TRUE Usuario: Confirmo Bot: [Ejecutando database_service.execute_database_operations()...] [INSERT INTO Sales_Header...] [INSERT INTO Sales_Lines...] Factura creada exitosamente • Número: INV-2024-042 • Total: $1,200.00 • Estado: Nueva ¿Necesitas algo más? [Estado] flow_type="facturacion", invoice_created=TRUE, last_invoice_number="INV-2024-042"

Ejemplo 3: Corrección de Datos

Usuario: Quiero cotizar Bot: ¿Tu nombre? [Estado] captura_en_progreso=TRUE Usuario: María García Bot: ¿Tu email María? Usuario: maria@correo Bot: ¿Tu teléfono? Usuario: 98765432 Bot: Confirma: • Nombre: María García • Email: maria@correo • Teléfono: 98765432 ¿Es correcto? [Estado] lead_pendiente_confirmacion=TRUE Usuario: No, el email es maria@correo.com Bot: Entendido. Actualizando email a maria@correo.com ¿Ahora es correcto? [Estado] flow_type="lead_correction", datos actualizados Usuario: Sí Bot: ¡Registrado con ID: CTZ-2024-002! [Estado] flow_type="lead_confirmed"

Ejemplo 4: Validación con Error

Usuario: Quiero registrarme Bot: [Captura nombre, email, teléfono...] Bot: Confirma tus datos... [Estado] lead_pendiente_confirmacion=TRUE Usuario: Sí Bot: [Validando con API...] [API retorna: email ya existe, teléfono formato inválido] Lo siento, encontré estos problemas: • Email: Este email ya está registrado • Teléfono: Debe contener exactamente 8 dígitos ¿Puedes proporcionar un email diferente? [Estado] flow_type="lead_validation_error", lead_pendiente_confirmacion=FALSE Usuario: Usa maria.garcia@correo.com Bot: ¿Y el teléfono correcto? Usuario: 98765432 Bot: Confirma datos actualizados... [Estado] lead_pendiente_confirmacion=TRUE (nuevamente) Usuario: Sí Bot: ¡Registrado exitosamente! [Estado] flow_type="lead_confirmed"

Ejemplo 5: Cancelación de Proceso

Usuario: Quiero cotizar Bot: ¿Tu nombre? [Estado] captura_en_progreso=TRUE Usuario: Pedro Bot: ¿Tu email Pedro? [Estado] datos_capturados={nombre: "Pedro"} Usuario: Cancela, mejor después Bot: [Detecta intención de cancelación con confidence >= 0.7] Entendido, he cancelado el proceso. ¿En qué más puedo ayudarte? [Estado] captura_en_progreso=FALSE, lead_pendiente_confirmacion=FALSE lead_datos_temporales={}, campos_capturados={}

Tabla Resumen de Estados

flow_type es_registro specialized_flow Descripción
lead_capture TRUE FALSE Captura genérica en progreso
lead_confirmation_request TRUE FALSE Esperando confirmación del usuario
lead_confirmed TRUE FALSE/TRUE Registro completado exitosamente
lead_correction TRUE FALSE Usuario corrigiendo datos
lead_validation_error TRUE FALSE Error de validación post-confirmación
lead_api_error TRUE FALSE Error de API externa
facturacion FALSE TRUE Flujo especializado de facturación
cotizacion FALSE/TRUE TRUE/FALSE Depende si usa API o INSERT directo
generic FALSE FALSE Flujo normal sin especialización

Decisiones Inteligentes del Sistema

1. Análisis de B_Template

Antes de activar lead capture, el sistema analiza el b_template con OpenAI para determinar si es un flujo especializado.

  • Confianza >= 0.7 → Marca specialized_flow = TRUE
  • Retorna inmediatamente es_registro = FALSE
  • Evita activar lead capture genérico innecesariamente

2. Persistencia de Contexto

El sistema mantiene contexto entre mensajes usando el estado persistent:

  • lead_operation_type - Tipo de operación CRUD
  • lead_api_config_name - API seleccionada
  • update_resource_id - ID del recurso a modificar
  • campos_capturados - Datos ya capturados

3. Prevención de Bucles

Para evitar reactivación infinita de flujos:

  • No reinicia captura si registro_completado = TRUE
  • Limpia forzar_captura_leads después de usar
  • Respeta pendiente_confirmacion para no re-detectar operaciones

4. Auto-Recuperación de Errores

En caso de fallos, el sistema mantiene el estado para permitir retry:

  • API error → Mantiene lead_datos_temporales
  • Validación error → Mantiene captura_en_progreso
  • Usuario puede corregir sin reiniciar desde cero