Etapas del ciclo de vida (lifecycle)

El lifecycle stage es la etapa del cliente en su relación con tu negocio. Es ortogonal al pipeline de tickets (que es por conversación): una persona puede ser customer (ya pagó) y tener un ticket abierto en nuevo simultáneamente.

Pipeline kanban vs Lifecycle funnel — la diferencia

Brote tiene dos vistas que se parecen pero son distintas:

	Pipeline kanban	Lifecycle funnel
Por	Ticket (una conversación)	Contacto (la persona)
Stages	Definidos por la org (Nuevo, Calificado, Cerrado-ganado/perdido…)	Canon Brote (Lead → MQL → SQL → Opportunity → Customer → Evangelist → Churned)
Multiplicidad	Una persona puede tener N tickets en N stages	Una persona = un solo lifecycle stage
Propósito	Workflow operativo de una conversación específica	Etapa relacional del cliente con tu negocio
URL	`/app/pipelines/...`	`/app/contacts/funnel`

Brote vincula los dos automáticamente

No tienes que actualizar el lifecycle manualmente cuando un ticket cierra:

Cuando pasa esto	Lifecycle del contacto se actualiza así
Ticket pasa a stage `is_won = true`	Bumpea de Lead/MQL/SQL/Opportunity → Customer
Pago aprobado en Mercado Pago, Flow o Khipu	Bumpea a Customer

Si el contacto ya está en Customer, Evangelist o Churned, no se degrada — Brote no pisa estados manuales con automáticos.

El cambio queda registrado en contact_lifecycle_history con source = 'workflow' para distinguir de los cambios manuales (source = 'manual') y de imports (source = 'csv_import').

Con Meta CAPI conectado

Si tu org tiene Meta Conversions API conectado, cada transición de lifecycle también dispara un evento server-side:

Stage destino	Evento Meta
MQL / SQL	`Lead`
Opportunity	`InitiateCheckout`
Customer	`Purchase` (vía webhook de pago)
Evangelist	`CompleteRegistration`

Esto cierra el funnel completo de atribución: Meta sabe qué ad generó cada Lead, MQL, SQL, Opportunity y Purchase, no solo la conversión final.

Etapas estándar

Etapa	Color	Cuándo
Lead	gris	Entró al chat pero todavía no calificó
MQL	azul	Marketing Qualified — interés expresado
SQL	violeta	Sales Qualified — intención clara de comprar
Oportunidad	ámbar	Negociando precio/términos
Cliente	verde	Pagó al menos una vez
Evangelista	cyan	Cliente que refiere a otros
Churned	rojo	Cliente perdido o inactivo

Cómo cambiar la etapa

Desde el pipeline visual (`/app/contacts/funnel`)

La vista kanban del funnel muestra todos tus contactos agrupados por etapa. Arrastra una card de una columna a otra para mover el contacto. La conversión entre etapas (% que pasa de N → N+1) se calcula en vivo arriba de cada columna.

Casos típicos:

Lead que respondió interés concreto → MQL.
MQL que pidió precio → SQL.
SQL al que mandaste cotización → Opportunity.
Opportunity que pagó → Customer.
Customer inactivo 3+ meses → Churned.

La columna “Sin etapa” agrupa contactos que todavía no clasificaste. Arrastra de ahí a la columna que corresponda.

Filtro de texto arriba del board: busca por nombre, teléfono, email o tag. Acelera el trabajo cuando tienes 500+ contactos.

Desde el panel lateral de una conversación

En cualquier conversación del inbox, en el panel derecho hay un picker “Etapa del cliente”. Click → eliges la etapa nueva. Brote guarda el cambio + registra quién lo hizo y cuándo en contact_lifecycle_history (para reporting + auditoría).

Desde un CSV import

Incluye la columna lifecycle, stage o etapa en tu CSV. Valores válidos: lead, mql, sql, opportunity, customer, evangelist, churned.

Desde el agente IA (próximo)

Estamos trabajando en una tool del agente set_lifecycle_stage para que la IA mueva al contacto cuando detecta señales claras (ej: cliente dice “ya pagué” → mover a customer automático).

Reporting

Las etapas alimentan:

Funnel de conversión: lead → mql → sql → customer (cuántos pasan de cada etapa a la siguiente).
Tiempo promedio en cada etapa: para detectar cuellos de botella.
Segmentación de campañas: enviar broadcast solo a customer o excluir churned.

Por ahora estas vistas viven en el dashboard general; en una próxima update vamos a tener un funnel dedicado en /app/analytics/funnel.

Historial de cambios

Cada cambio queda registrado:

contact_lifecycle_history (
  contact_id,
  from_stage,
  to_stage,
  changed_by,
  source ('manual' | 'csv_import' | 'workflow' | 'api'),
  created_at
)

Útil para auditoría y para detectar reversiones (cliente vuelve de churned a customer = recompra).