Contatos

O que são contatos?

Os contatos são visitantes identificados. Quando você identifica um visitante anônimo com um externalId (o ID de usuário do seu sistema) ou um email, ele vira um contato.

Os contatos permitem:

• Suporte entre dispositivos: o mesmo usuário no desktop, no celular ou depois de reinstalar o app compartilha o histórico de conversas.
• Metadados ricos: anexe contexto como tipo de plano, MRR, empresa ou etapa do ciclo de vida.
• Visibilidade no painel: os agentes de suporte veem os dados do usuário ao lado das conversas.
• Identidade persistente: as conversas seguem o usuário, não o dispositivo.

Criar contatos

Requisitos de identificação

Um contato precisa de pelo menos um destes dados:

• externalId: o ID interno de usuário do seu sistema (recomendado).
• email: o endereço de e-mail do usuário.

Os dois são aceitos, mas o externalId é preferível para um rastreamento sólido entre sistemas. Use um ID estável da sua própria tabela de usuários, como user.id, para que o Fluxo reconheça a mesma pessoa depois de limpar o armazenamento do navegador, reinstalar o app ou entrar em outro dispositivo.

Com o 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>
  );
}

Com o 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;
}

Metadados do contato

Os metadados dão contexto aos agentes de suporte durante as conversas. Eles aparecem no seu painel ao lado dos tópicos de chat.

O que incluir

Campos de metadados comuns:

• plan: nível de assinatura (free, pro, enterprise).
• signupDate: quando o usuário se cadastrou.
• company: nome da organização.
• mrr: receita recorrente mensal.
• lifecycleStage: lead, trial, customer, churned.
• lastActive: marca de tempo da última atividade.

Esquema dos metadados

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

Só valores primitivos são aceitos: nada de objetos aninhados nem arrays.

Atualizar os metadados

Os metadados podem ser atualizados a qualquer momento para refletir mudanças do usuário:

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>;
}

Como as atualizações de metadados funcionam

O <IdentifySupportVisitor /> calcula um hash dos seus metadados e evita enviar a mesma carga duas vezes. As chamadas diretas a setVisitorMetadata() sempre atualizam, então use-as em resposta a uma mudança real, não a cada render.

As atualizações mesclam as chaves que você envia com os metadados que o contato já tem. Um valor null é gravado como null; ele não remove a chave. Envie apenas os campos que você quer mudar.

Quando a autenticação muda num navegador compartilhado, identifique o novo externalId estável mesmo que já exista um contato. Uma verificação genérica do tipo !visitor?.contact pode deixar a conta anterior ligada à nova sessão.

Um contato, vários visitantes

Um mesmo contato pode ter vários visitantes associados:

• Visitante de desktop: o usuário no notebook.
• Visitante mobile: o mesmo usuário no celular.
• Visitante de tablet: o mesmo usuário no iPad.

Os três visitantes compartilham:

• O histórico de conversas.
• Os metadados do contato.
• O contexto de suporte.

Isso também cobre os casos de perda de armazenamento. Se um usuário reinstala o seu app ou perde o armazenamento do navegador, o Fluxo pode criar um visitante novo no começo. Assim que você o identificar com o mesmo externalId ou e-mail, o Fluxo o liga ao contato existente e devolve o acesso às conversas anteriores.

Você não precisa guardar o ID de visitante do Fluxo nos seus registros de usuário para usuários identificados. Guarde e envie o seu externalId estável. Os visitantes anônimos continuam ligados ao armazenamento do dispositivo e navegador atuais até serem identificados.

Assim o suporte flui entre dispositivos e reinstalações: os agentes veem o quadro completo, não importa de onde o usuário escreva.

Saiba mais

• Visitantes: usuários anônimos antes da identificação.
• IdentifySupportVisitor: componente para criar contatos.
• useVisitor: hook para gerenciar contatos via código.
• Conversas: tópicos de chat associados aos contatos.