Flujo Principal: Lead entra por mensajería

El principio general de Clivya CRM es ayudar a una empresa a convertir interacciones en seguimiento, seguimiento en oportunidades, y oportunidades en cotizaciones medibles. Ninguna herramienta del sistema existe de forma aislada.

Los 15 pasos operativos

El flujo esperado cuando una persona escribe por WhatsApp, Instagram, Messenger o Chat Web es el siguiente:

Mensaje entra a la bandeja centralizada.
El sistema identifica canal, remitente, fecha y "tenant" (tu empresa).
El sistema busca si ya existe el prospecto por teléfono, email o ID de red social.
Si no existe, crea el prospecto de forma automática. Si existe, vincula la conversación al historial.
El Flow Builder clasifica la intención (Precio, Disponibilidad, Soporte, Cita, etc).
El sistema asigna un asesor según las reglas (Round Robin, por etiqueta, horario o canal).
El asesor recibe la notificación y la conversación en su bandeja.
El asesor responde y actualiza el estado del prospecto.
Si el prospecto requiere precio formal, se genera una Cotización en PDF.
Si requiere cita, se agenda directamente.
Si requiere un producto físico, se consulta el inventario.
Si no compra en el momento, se marca como Seguimiento Futuro.
Si compra, se marca como estado Cerrado / Ganado.
Todos los reportes registran tiempos de primera respuesta, asesor responsable y conversión total.

Resultado correcto: Siguiendo este flujo, nunca se pierde un mensaje, ningún prospecto se queda sin dueño, el asesor sabe qué debe hacer y la gerencia tiene métricas exactas.

Bandeja Centralizada (Messaging Inbox)

La Bandeja Centralizada sirve para ver conversaciones de todos los canales en un solo lugar. Es aquí donde los asesores y administradores responden mensajes, etiquetan, asignan y cierran tratos.

Estados Sugeridos de Conversación

Para no saturar al equipo, cada ticket de conversación debe tener un estado claro:

Nueva: Recién ingresada, sin atención humana.
Abierta: El asesor está activamente conversando.
Asignada: Un líder se la transfirió a un asesor, pero aún no la atiende.
En espera de cliente: El asesor ya respondió o mandó cotización, esperando respuesta.
Cerrada: Tema resuelto.

Ejemplo Real de Uso

1. Situación: Un cliente escribe a WhatsApp: "Hola, quiero saber el precio de sus servicios".

2. Sistema automático: Clivya crea el prospecto, le asigna la etiqueta precio, asigna la conversación a un asesor disponible, y registra el cronómetro de tiempo de respuesta.

3. Acción del Asesor: Responde con una plantilla de bienvenida, le genera una cotización y como el cliente le dice "Lo reviso con mi socio", el asesor marca el estado en Seguimiento programando una alerta para el día siguiente.

Prospectos y Cotizador B2B

El módulo de Prospectos centraliza la base comercial. Permite tener una única vista 360 del cliente, sin importar si te contactó por distintos canales en distintos momentos (gracias a nuestro Sistema de Avatares que unifica teléfonos y correos).

Gestión de Prospectos

Campos base recomendados que debes llenar en Clivya:

Nombre, Teléfono, Email, Empresa.
Origen y Canal (Saber de dónde vienen tus ventas).
Asesor responsable y Monto estimado.

Estados del Kanban de Prospectos: Nuevo > Contactado > Calificado > Cotización Enviada > Negociando > Ganado / Perdido.

Herramienta Cotizador

Integrado directamente en el CRM, el cotizador sirve para enviar propuestas formales al instante, sin salir de la bandeja de mensajes.

Flujo de una Cotización

El cliente pide precios mayoristas. El asesor abre la pestaña de "Cotización" dentro de la misma conversación, selecciona los productos del inventario precargado, aplica impuestos automáticamente y genera un PDF. Ese PDF se envía por WhatsApp y el prospecto cambia su estado automáticamente a "Cotización Enviada". Si el cliente acepta, los reportes miden el monto total ganado.

Comentarios Facebook/IG y Chat Web

Gestión de Comentarios Sociales

El sistema detecta comentarios en tus publicaciones de Facebook e Instagram para clasificarlos y responderlos. No debes prometer automatizaciones por scraping, Clivya usa las APIs oficiales de Meta.

Ejemplo: Respuesta a Comentario

Un usuario comenta "precio" en una foto de Instagram. Meta envía un webhook a Clivya. El Flow Builder da "Like" al comentario, responde públicamente "Te enviamos información por DM", y ejecuta un Private Reply enviando la lista de precios por mensaje directo. El prospecto se crea con origen "Comentario IG".

Chat Web Propio

Clivya permite instalar un widget en tu propio sitio web. A diferencia de WhatsApp, aquí tienes el control total del enrutamiento. Dependiendo de tu plan:

Starter: El flow pide datos básicos (nombre/email) y el asesor humano agenda la cita manualmente.
Pro/Enterprise: La IA Conversacional consulta la disponibilidad de tu agenda en tiempo real, le propone horarios al visitante y confirma la cita automáticamente sin intervención humana.

FlowBuilder y Disparadores (Triggers)

El FlowBuilder permite programar mensajes y comportamientos reactivos. No aplica solo a chatbots, sino a automatizaciones internas.

Nodos Disparadores (Triggers)

Los tipos avanzados son exclusivos de planes Pro+ y se ejecutan vía el ScheduledMessageWorker en el backend.

Tipo	Ejecución	Ejemplo de Uso
`message`	Inmediata	El cliente escribe "Soporte", el bot lo deriva a un humano.
`inactivity`	Cada 1 min tick	El cliente dejó un carrito a medias. Si lleva 30 mins sin hablar, se le manda recordatorio.
`stage_change`	Outbox Events	Mueves al prospecto a la etapa "Ganado", el sistema le dispara un PDF de bienvenida por WhatsApp.
`advisor_change`	Outbox Events	Asignas el prospecto a Juan. El bot manda: "Hola, soy Juan, tu nuevo asesor".
`schedule`	Cron recurrente	Tareas internas periódicas (mover prospectos viejos a "Perdidos").

El Safe Buffer: Si programas un mensaje exactamente 24 horas después, la latencia del servidor podría hacer que se envíe en 24h 01m, causando un baneo de Meta. Clivya utiliza un safeBuffer de seguridad de 1 hora. Si el mensaje cae en la "Zona Borde", te advertiremos en pantalla que requieres una plantilla aprobada.

Reglas de Meta: Ventana de 24 horas

La regla más estricta para no ser baneados en WhatsApp, Messenger e Instagram. Todo gira en torno a la última interacción del cliente.

Qué ABRE o REINICIA la Ventana

El backend actualiza la variable lastInboundAt a 24h frescas cuando ocurre lo siguiente:

WhatsApp: Mensaje (texto/media), llamada del cliente, tap en un botón o quick-reply.
Messenger: Mensaje, Postback, botón de Get Started.
Instagram: DM directo, mención en historia, o respuesta a tu historia.

Enviar una plantilla de marketing por tu parte NO abre la ventana. Se abre solo hasta que el usuario te responde.

Cero Cold Outreach: Nunca subas listas de prospectos fríos (scrapeados o comprados) para mandarles mensajes proactivos. Solo se contacta a quien interactuó previamente Y te dio su Opt-In válido explícito. Si un cliente escribe "STOP", Clivya lo manda a la Lista de Supresión y gana sobre cualquier otra regla.

Plantillas y Quality Rating (Meta)

Cuando la ventana de 24 horas se cierra, el "Texto Libre" queda bloqueado. A partir de aquí debes usar plantillas aprobadas.

Vías Fuera de Ventana

WhatsApp: Uso estricto de Plantillas HSM (Utility, Marketing, Authentication).
Messenger: Uso de "Utility Message Templates" para cosas operativas, y "Marketing Messages API" para promociones. (Atención: Messenger no usa el sistema HSM de WhatsApp).
Instagram: Altamente bloqueado. Solo se permiten Private Replies de 1 solo toque o la etiqueta human_agent que permite atención manual por un humano hasta 7 días. (El bot no puede usar human_agent).

Quality Rating y Categorías: Recuperación o re-engagement es Marketing. Solo los updates transaccionales reales (pedido, cita, OTP) son Utility. Enviar mensajes promocionales bajo una plantilla Utility es una violación que Meta penaliza bajando tu Quality Rating de Verde a Rojo, y reduciendo tu "Tier" de 100K mensajes al día hasta suspender tu cuenta.

Autenticación y Arquitectura (.NET)

La API de Clivya CRM está desarrollada sobre .NET 8 y PostgreSQL, utilizando el patrón de Tenant Isolation. Ninguna consulta puede fugar datos hacia otros usuarios del CRM gracias al control criptográfico a nivel de bases de datos y Entity Framework.

Access Tokens y Bearer

Genera tus tokens de acceso desde el panel de desarrolladores. Tienen duración indefinida. Envíalos siempre en el Header de tu petición HTTP.

curl -X GET "https://api.clivyacrm.com/v1/ping" \
  -H "Authorization: Bearer clivya_live_aBcDeF12345" \
  -H "Accept: application/json"

Webhooks y el Outbox Pattern

Clivya soluciona el problema de los webhooks "perdidos" (cuando tu servidor se cae) usando un patrón Outbox transaccional. Todos los eventos de tus prospectos se guardan en cola en nuestra base de datos y un Worker garantiza la entrega con reintentos escalonados y DLQ (Dead Letter Queue).

Idempotencia en Endpoints (Upsert)

Para crear un prospecto desde tu ERP, utiliza el endpoint de Upsert. Es obligatorio enviar la llave de idempotencia (Idempotency-Key en los Headers) para evitar crear prospectos duplicados si tu servidor hace un reintento por falla de conexión.

POST /v1/prospects/upsert

{
  "email": "director@empresa.com",
  "phone_number": "+525544332211",
  "full_name": "Luis Martínez",
  "tags": ["B2B", "Alta Prioridad"],
  "custom_fields": {
    "empresa": "Acme Corp"
  }
}