Manual de uso bot de seguimientos con ia

[Ricardo_Velasco]

Introducción

El Bot de Seguimientos Kontrolya es un sistema automatizado de seguimiento de clientes que utiliza inteligencia artificial (OpenAI GPT-4o-mini) para analizar las respuestas de los clientes y tomar decisiones inteligentes sobre cómo continuar el seguimiento.

Características Principales

• Análisis de sentimiento con IA: Detecta automáticamente el interés, rechazo o necesidad de reagendamiento

• Respuestas contextualizadas: Genera mensajes personalizados basados en el historial

• Gestión de zona horaria: Respeta el timezone configurado en cada inbox

• Plantillas WhatsApp: Soporte para plantillas aprobadas por intento

• 14 reglas inteligentes: Filtrado, detección y acciones automatizadas

• Múltiples intentos: Configuración flexible de reintentos

Nota Importante: El bot requiere una integración activa de OpenAI en tu cuenta de Chatwoot. Si no está configurada, utilizará detección por palabras clave (menos precisa).

¿Cómo Funciona?

Flujo de Trabajo del Bot

1

Creación del Seguimiento

Se crea un ContactTracking con objetivo, fecha programada y contexto de IA.

2

Programación del Job

Sidekiq programa el ContactTrackingJob para la hora especificada (respetando timezone).

3

Envío de Mensaje

Al llegar la hora, el bot envía un mensaje al cliente (IA o plantilla WhatsApp).

4

Cliente Responde

El cliente envía un mensaje de respuesta por WhatsApp/otro canal.

5

Análisis con IA

ContactTrackingResponseAnalyzerJob analiza el mensaje con OpenAI.

6

Decisión Inteligente

Basado en las REGLAS 8-18, 23, 25, 27, el bot decide la acción:

• Cancelar seguimiento (cliente rechazó)

• Marcar como exitoso (cliente interesado)

• Reagendar para otra fecha/hora

• Solicitar aclaración

• Ignorar mensaje de cortesía

7

Acción Automática

El bot ejecuta la acción y actualiza el estado del seguimiento.

Reglas del Bot

El bot implementa 14 reglas que determinan su comportamiento. Aquí están todas en orden de prioridad:

REGLA 8Filtrado de Mensajes de Cortesía SimplesFiltro

El bot ignora mensajes de cortesía sin contenido relevante para evitar falsos positivos.

Ejemplos de mensajes ignorados:

Cliente: “gracias”

Cliente: “ok”

Cliente: “bueno”

Cliente: “vale”

Resultado: El bot NO hace nada, el seguimiento permanece activo sin cambios.

REGLA 9Filtrado de Agradecimientos con DespedidaFiltro

El bot ignora agradecimientos con despedida que no indican rechazo claro.

Ejemplos de mensajes ignorados:

Cliente: “Muchas gracias, buen día”

Cliente: “Gracias, saludos”

Cliente: “Ok, hasta luego”

Resultado: El bot NO hace nada. Si después el cliente dice “no me interesa”, ahí sí se cancelará.

REGLA 10 Detección de Contexto vs CortesíaFiltro

El bot distingue entre cortesía simple y respuestas con contenido relevante.

Ejemplo - NO se ignora:

Cliente: “Gracias, pero recuérdame mañana mejor”

Resultado: Aunque empieza con “gracias”, tiene contenido relevante (reagendar), así que el bot SÍ lo procesa y reagenda para mañana.

REGLA 12Cancelación por Solicitud ExplícitaCancelación

Si el cliente dice “cancelar” o “detener”, el bot cancela el seguimiento y crea una nota privada para el agente.

Ejemplo:

Cliente: “Por favor cancela este seguimiento”

Acciones automáticas:

• Estado → cancelled

• Nota privada → “Cliente solicitó cancelación: ‘Por favor cancela…’”

• NO se envía respuesta automática al cliente

REGLA 13Cliente Muestra Interés ClaroÉxito

Si el cliente muestra interés claro, el bot marca el seguimiento como exitoso y notifica al administrador.

Ejemplos de interés claro:

Cliente: “Me interesa, ¿cuánto cuesta?”

Cliente: “Quiero saber más información”

Cliente: “Sí me interesa, cuéntame más”

Acciones automáticas:

• Estado → completed

• Notifica al administrador (asigna conversación)

• Nota privada → “¡Cliente interesado! Requiere atención humana”

• NO se envía respuesta automática (para que el agente humano tome control)

REGLA 14Cliente Rechaza el SeguimientoRechazo

Si el cliente rechaza claramente, el bot marca como completado y crea nota privada.

Ejemplos de rechazo:

Cliente: “No me interesa”

Cliente: “Ya no quiero”

Cliente: “No estoy interesado”

Cliente: “No me contacten más”

Acciones automáticas:

• Estado → completed

• Nota privada → “Cliente rechazó seguimiento: ‘No me interesa’”

• NO se envía respuesta automática

• El seguimiento NO continuará

REGLA 15Reagendamiento por Solicitud del ClienteReagendar

Si el cliente pide que lo contacten en otro momento, el bot reagenda automáticamente.

Ejemplos de reagendamiento:

Cliente: “Recuérdame en 20 minutos”

Cliente: “Llámame a las 14:30”

Cliente: “Mejor mañana”

Cliente: “En 2 horas por favor”

Acciones automáticas:

• Extrae fecha/hora del mensaje (con IA o regex)

• Calcula nueva fecha usando timezone del inbox

• Actualiza scheduled_for

• Reprograma job en Sidekiq

• Envía confirmación: “Te contactaré el 27/12/2025 a las 14:30”

REGLA 16Interpretación de Horas sin AM/PMReagendar

Cuando el cliente dice una hora sin especificar AM/PM, el bot asume formato PM (tarde).

Ejemplos:

Cliente dice	Bot interpreta	Formato 24h
“a las 3”	3 PM	15:00
“a las 5”	5 PM	17:00
“a las 11”	11 PM	23:00
“a las 10 AM”	10 AM (respeta)	10:00
“a las 3 PM”	3 PM (respeta)	15:00

Razón: En México (y LATAM en general), cuando alguien dice “te llamo a las 3”, normalmente se refiere a la tarde (3 PM), no a la madrugada (3 AM).

REGLA 17Conservación del Día ActualReagendar

Si el cliente solo indica hora (sin fecha), el bot intenta mantener el día actual. Si la hora ya pasó, programa para el día siguiente.

Ejemplo:

Escenario: Son las 10:00 AM del 26/12/2025

Cliente dice	Hora programada	Razón
“a las 3” (15:00)	26/12/2025 15:00	Hoy mismo (hora no ha pasado)
“a las 9” (21:00)	26/12/2025 21:00	Hoy mismo (hora no ha pasado)
“a las 8” (08:00 AM)	27/12/2025 08:00	Mañana (ya pasaron las 8 AM hoy)

REGLA 18Respuesta Poco ClaraAclaración

Si la respuesta del cliente es ambigua o poco clara, el bot solicita aclaración de manera educada.

Ejemplo:

Cliente: “mmm no sé”

Bot: “Entiendo. Para apoyarte mejor, ¿podrías decirme si te gustaría que te contactemos en otro momento o si prefieres que no insistamos?”

Acciones automáticas:

• NO modifica el estado del seguimiento

• Envía mensaje generado por IA solicitando aclaración

• Actualiza ai_context con la respuesta poco clara

• Seguimiento permanece activo esperando respuesta clara

REGLA 23Zona Horaria del InboxTimezone

TODOS los cálculos de fecha/hora usan el timezone configurado en el inbox, no UTC.

Ejemplo de funcionamiento:

Configuración:

• Inbox timezone: America/Mexico_City (UTC-6)

• Hora actual México: 14:00 CST

• Hora actual UTC: 20:00 UTC

Cliente: “recuérdame a las 5” (17:00)

Procesamiento del bot:

1. IA recibe: “Hora actual (America/Mexico_City): 14:00 CST”

2. IA interpreta: “a las 5” = 17:00 (REGLA 16: PM por defecto)

3. Bot calcula en timezone: 17:00 CST del mismo día

4. Rails guarda en DB: 23:00 UTC (conversión automática)

5. Al ejecutar: Se convierte de vuelta a 17:00 CST

Importante: Aunque la DB guarda en UTC, el bot SIEMPRE calcula y muestra en el timezone del inbox. No necesitas hacer nada especial, Rails lo maneja automáticamente.

REGLA 25Ignorar Mensajes sin TextoFiltro

El bot ignora mensajes que solo contienen imágenes, videos, audios, stickers o documentos sin texto.

Ejemplos:

Mensaje del cliente	Acción del bot
[Imagen sin texto]	Ignora (no procesa)
[Audio de voz]	Ignora (no procesa)
[PDF sin mensaje]	Ignora (no procesa)
+ “Mira esta foto”	Procesa (tiene texto)
“Sí me interesa” +	Procesa (tiene texto)

REGLA 27Prioridad Absoluta a Fecha+Hora ExactaReagendar

Cuando el cliente especifica fecha Y hora exactas, esa combinación tiene prioridad absoluta sobre cualquier otra regla de cálculo.

Ejemplo:

Cliente: “El 28 de diciembre a las 10:00 AM”

Procesamiento:

• IA extrae: specific_date: "2025-12-28"

• IA extrae: specific_time: "10:00"

• Bot calcula: 28/12/2025 10:00 CST (usando timezone del inbox)

• NO aplica REGLA 17 (conservar día actual)

• NO aplica REGLA 16 (PM por defecto) porque especificó AM

• Resultado: 28/12/2025 10:00 AM

Estados de Seguimiento

Un seguimiento puede estar en uno de los siguientes 7 estados:

Estado	Descripción	¿Puede ejecutarse?
pending	Recién creado, esperando primera ejecución	Sí
scheduled	Programado para próximo intento	Sí
active	En proceso de ejecución (enviando mensaje)	Sí
paused	Pausado manualmente por usuario	No (hasta reanudar)
completed	Completado exitosamente o cliente rechazó	No
cancelled	Cancelado manualmente	No
failed	Falló por error técnico	No

Transiciones de Estado

→ pending → active (al ejecutarse primera vez)

→ active → scheduled (si necesita reintento)

→ active → completed (si cliente respondió positiva/negativamente)

→ scheduled → paused (acción manual)

→ paused → active (al reanudar)

→ cualquiera → cancelled (acción manual)

Configuración de Zona Horaria

La configuración correcta de la zona horaria es CRÍTICA para que el bot funcione correctamente.

Cómo Configurar el Timezone del Inbox

1. Ve a Settings → Inboxes

2. Selecciona el inbox de WhatsApp/SMS

3. Busca el campo “Timezone”

4. Selecciona: America/Mexico_City (o tu zona horaria)

5. Guarda cambios

MUY IMPORTANTE: Si no configuras el timezone, el bot usará America/Mexico_City por defecto. Esto puede causar problemas si tus clientes están en otra zona horaria.

Zonas Horarias Soportadas (México/LATAM)

Zona Horaria	Región	Offset UTC
America/Mexico_City	Ciudad de México, Guadalajara, Monterrey	UTC-6 (CST)
America/Tijuana	Baja California	UTC-8 (PST)
America/Cancun	Quintana Roo	UTC-5 (EST)
America/Bogota	Colombia	UTC-5 (COT)
America/Lima	Perú	UTC-5 (PET)
America/Santiago	Chile	UTC-4 (CLT)
America/Buenos_Aires	Argentina	UTC-3 (ART)

Ejemplo de Problema sin Timezone Correcto

Escenario sin configurar timezone:

• Inbox NO tiene timezone configurado

• Bot usa America/Mexico_City por defecto

• Tus clientes están en America/Buenos_Aires (UTC-3)

• Diferencia: 3 horas

Resultado:

Cliente en Argentina dice: “recuérdame a las 3 PM”

Bot calcula: 15:00 CST (México) = 17:00 ART (Argentina)

Cliente esperaba: 15:00 ART (Argentina)

Solución: Configurar timezone correcto

Si configuras el inbox con America/Buenos_Aires, el bot calculará correctamente en hora de Argentina.

Casos de Uso Prácticos

Caso 1: Seguimiento de Cotización

Configuración:

• Objetivo: “Seguimiento de cotización enviada”

• Programado para: 1 día después

• Max intentos: 3

• Intervalo: 2 días

Flujo:

1

Día 1 - 10:00 AM: Bot envía mensaje

“Hola Juan, ¿pudiste revisar la cotización que te enviamos?”

2

Cliente responde:

“Sí la vi, pero recuérdame mañana a las 3 PM mejor”

3

Bot analiza con IA:

• Intent: reschedule

• Fecha: mañana (Día 2)

• Hora: 15:00 (REGLA 16: “3” = PM)

4

Bot reagenda y confirma:

“Perfecto Juan, te contactaré mañana 27/12/2025 a las 15:00. ¡Gracias!”

5

Día 2 - 3:00 PM: Bot envía segundo mensaje

“Hola de nuevo Juan, ¿ya tuviste oportunidad de revisar la cotización?”

6

Cliente responde:

“Sí me interesa, ¿cuándo podemos proceder?”

7

Bot detecta interés (REGLA 13):

• Marca seguimiento como completed

• Notifica al administrador

• NO envía respuesta automática

• Agente humano toma control

Caso 2: Cliente Rechaza el Seguimiento

Flujo:

1

Bot envía:

“Hola María, ¿te gustaría conocer más sobre nuestros servicios?”

2

Cliente responde:

“No me interesa, gracias”

3

Bot detecta rechazo (REGLA 14):

• Intent: rejected

• Marca como completed

• Nota privada: “Cliente rechazó…”

• NO envía más mensajes

Caso 3: Mensaje de Cortesía (No Procesado)

Flujo:

1

Bot envía:

“Hola Pedro, ¿te interesa la propuesta?”

2

Cliente responde:

“ok”

3

Bot detecta cortesía (REGLA 8):

• Mensaje ignorado (sin contenido relevante)

• Seguimiento permanece active

• Esperará al próximo intento programado

4

2 días después - Bot envía segundo intento:

“Hola Pedro, seguimos pendientes. ¿Te gustaría continuar?”

5

Cliente responde:

“Sí, envíame la información completa”

6

Bot detecta interés (REGLA 13):

• Marca como completed

• Notifica administrador