Contactos

¿Qué son los contactos?

Los contactos son visitantes identificados. Cuando identificas a un visitante anónimo con un externalId (el ID de usuario de tu sistema) o un email, pasa a ser un contacto.

Los contactos permiten:

• Soporte entre dispositivos: el mismo usuario en escritorio, móvil o tras reinstalar la aplicación comparte el historial de conversaciones.
• Metadatos ricos: adjunta contexto como el tipo de plan, el MRR, la empresa o la etapa del ciclo de vida.
• Visibilidad en el panel: los agentes de soporte ven los datos del usuario junto a las conversaciones.
• Identidad persistente: las conversaciones siguen al usuario, no al dispositivo.

Crear contactos

Requisitos de identificación

Un contacto necesita al menos uno de estos datos:

• externalId: el ID interno de usuario de tu sistema (recomendado).
• email: la dirección de correo del usuario.

Se aceptan los dos, pero externalId es preferible para un seguimiento sólido entre sistemas. Usa un ID estable de tu propia tabla de usuarios, como user.id, para que Fluxo reconozca a la misma persona tras borrar el almacenamiento del navegador, reinstalar la aplicación o iniciar sesión en otro dispositivo.

Con el componente

Copiarimport { IdentifySupportVisitor } from "@fluxolat/next/identify-visitor";
import { auth } from "@/lib/auth";
import { headers } from "next/headers";
 
export default async function DashboardLayout({ children }) {
  const session = await auth.api.getSession({
    headers: await headers(),
  });
 
  return (
    <div>
      {session?.user && (
        <IdentifySupportVisitor
          externalId={session.user.id}
          email={session.user.email}
          name={session.user.name}
          image={session.user.image}
          metadata={{
            plan: session.user.plan,
            signupDate: session.user.createdAt,
            company: session.user.company,
            mrr: session.user.mrr,
          }}
        />
      )}
      {children}
    </div>
  );
}

Con el hook

Copiar"use client";
 
import { useVisitor } from "@fluxolat/next/hooks";
import { useEffect } from "react";
 
export function AuthHandler({ user }) {
  const { identify } = useVisitor();
 
  useEffect(() => {
    if (!user) {
      return;
    }
 
    void identify({
      externalId: user.id,
      email: user.email,
      name: user.name,
      image: user.avatar,
      metadata: {
        plan: user.plan,
        signupDate: user.createdAt,
      },
    });
  }, [
    user?.id,
    user?.email,
    user?.name,
    user?.avatar,
    user?.plan,
    user?.createdAt,
    identify,
  ]);
 
  return null;
}

Metadatos del contacto

Los metadatos dan contexto a los agentes de soporte durante las conversaciones. Aparecen en tu panel junto a los hilos de chat.

Qué incluir

Campos de metadatos habituales:

• plan: nivel de suscripción (free, pro, enterprise).
• signupDate: cuándo se registró el usuario.
• company: nombre de la organización.
• mrr: ingresos recurrentes mensuales.
• lifecycleStage: lead, trial, customer, churned.
• lastActive: marca de tiempo de la última actividad.

Esquema de los metadatos

Copiartype VisitorMetadata = Record<string, string | number | boolean | null>;

Solo se admiten valores primitivos: nada de objetos anidados ni arrays.

Actualizar los metadatos

Los metadatos se pueden actualizar en cualquier momento para reflejar los cambios del usuario:

Copiar"use client";
 
import { useVisitor } from "@fluxolat/next/hooks";
 
export function UpgradeButton() {
  const { setVisitorMetadata } = useVisitor();
 
  const handleUpgrade = async () => {
    await upgradeToPro();
 
    // Update metadata so agents see the new plan
    await setVisitorMetadata({
      plan: "pro",
      upgradedAt: new Date().toISOString(),
      mrr: 99,
    });
  };
 
  return <button onClick={handleUpgrade}>Upgrade to Pro</button>;
}

Cómo se aplican las actualizaciones de metadatos

<IdentifySupportVisitor /> calcula un hash de sus metadatos y evita enviar dos veces la misma carga. Las llamadas directas a setVisitorMetadata() siempre actualizan, así que úsalas como respuesta a un cambio real, no en cada renderizado.

Las actualizaciones fusionan las claves que envías con los metadatos que ya tiene el contacto. Un valor null se guarda como null; no borra la clave. Envía solo los campos que quieras cambiar.

Cuando cambia la autenticación en un navegador compartido, identifica el nuevo externalId estable aunque ya haya un contacto. Una comprobación genérica del tipo !visitor?.contact puede dejar la cuenta anterior asociada a la nueva sesión.

Un contacto, varios visitantes

Un mismo contacto puede tener varios visitantes asociados:

• Visitante de escritorio: el usuario en su portátil.
• Visitante móvil: el mismo usuario en su teléfono.
• Visitante de tablet: el mismo usuario en su iPad.

Los tres visitantes comparten:

• El historial de conversaciones.
• Los metadatos del contacto.
• El contexto de soporte.

Esto cubre también los casos de pérdida de almacenamiento. Si un usuario reinstala tu aplicación o pierde el almacenamiento del navegador, Fluxo puede crear al principio un visitante nuevo. En cuanto lo identifiques con el mismo externalId o correo, Fluxo lo enlaza con el contacto existente y le devuelve el acceso a sus conversaciones anteriores.

No necesitas guardar el ID de visitante de Fluxo en tus registros de usuario para los usuarios identificados. Guarda y envía tu externalId estable. Los visitantes anónimos siguen ligados al almacenamiento del dispositivo y navegador actuales hasta que se identifican.

Así el soporte fluye entre dispositivos y reinstalaciones: los agentes ven el cuadro completo sin importar desde dónde escriba el usuario.

Más información

• Visitantes: usuarios anónimos antes de identificarse.
• IdentifySupportVisitor: componente para crear contactos.
• useVisitor: hook para gestionar contactos desde código.
• Conversaciones: hilos de chat asociados a los contactos.