Conversas

O que são conversas?

As conversas são sessões de chat em tópico entre os visitantes (ou os contatos) e a sua equipe de suporte. Cada conversa tem uma linha do tempo de itens: mensagens, eventos, registros de identificação e atividade de ferramentas.

Propriedades principais

Toda conversa inclui:

• status: open, resolved ou spam.
• priority: low, normal, high ou urgent.
• participants: os agentes de suporte (pessoas ou IA) envolvidos.
• tags: etiquetas para classificar (faturamento, técnico, onboarding, etc.).
• timeline: lista ordenada de itens da linha do tempo.
• lastTimelineItem: a atividade mais recente, para ordenar e pré-visualizar.

Ciclo de vida de uma conversa

Criação

As conversas são criadas quando:

• Um visitante envia a primeira mensagem pelo widget de suporte.
• O seu backend cria uma pela API.

O painel atual gerencia conversas existentes; ele não oferece aos agentes uma ação para iniciar uma conversa.

Fluxo de status

open → resolved
  │       ↑
  │       │
  └→ spam └─ reopened

• open: conversa ativa que precisa de atenção.
• resolved: conversa marcada como concluída (pode ser reaberta).
• spam: conversa classificada como tráfego indesejado ou abusivo.

Níveis de prioridade

As conversas podem ser priorizadas:

• low: perguntas gerais, comentários sem urgência.
• normal: pedidos de suporte padrão (valor padrão).
• high: problemas importantes que afetam a experiência do usuário.
• urgent: problemas críticos que exigem atenção imediata.

Os agentes de suporte podem ajustar a prioridade conforme o contexto da conversa.

Atualizações em tempo real

As conversas se sincronizam em tempo real por WebSocket:

• As mensagens novas aparecem na hora.
• Os indicadores de digitação mostram quando um agente está escrevendo.
• Os recibos de leitura registram quando as mensagens são lidas.
• As mudanças de status são transmitidas imediatamente.

O SDK do Fluxo cuida de todo o WebSocket automaticamente: não é preciso configurar nada.

Linha do tempo da conversa

Cada conversa tem uma linha do tempo de itens:

• Mensagens: texto e arquivos dos visitantes ou dos agentes.
• Eventos: atividades do sistema (atribuída, resolvida, alguém entrou).
• Registros de identificação: atividade de identificação de visitantes e contatos.
• Itens de ferramentas: registros de execução da IA e das ferramentas.

A linha do tempo oferece um histórico estruturado da conversa. Registros privados, excluídos, filtrados ou operacionais podem não aparecer para todo mundo, então não a trate como um log de conformidade imutável.

Exemplo de linha do tempo

1. [MENSAGEM] Visitante: "Como faço para redefinir minha senha?"
2. [EVENTO] A agente Sarah entrou na conversa
3. [MENSAGEM] Sarah: "Posso ajudar! Clique no seu perfil..."
4. [EVENTO] Conversa marcada como resolvida
5. [MENSAGEM] Visitante: "Obrigado, funcionou!"
6. [EVENTO] Conversa reaberta

Suporte com vários agentes

Uma conversa pode ter vários participantes:

• Agentes humanos: membros da equipe de suporte.
• Agentes de IA: assistentes automáticos.
• Modo misto: a IA faz a triagem inicial e escalona para uma pessoa.

Os agentes podem:

• Entrar e sair das conversas.
• Ver o histórico completo.
• Adicionar notas internas (itens da linha do tempo privados).

Etiquetas e organização

Etiquete as conversas para filtrá-las e gerar relatórios:

Copiartags: ["billing", "urgent", "enterprise-customer"];

As etiquetas servem para:

• Encaminhar conversas para equipes especializadas.
• Gerar relatórios e análises.
• Filtrar as visões do painel.
• Acompanhar os tipos de problema mais comuns.

Acompanhamento de leituras

O Fluxo registra quando cada participante viu a conversa pela última vez:

• Visitantes: a leitura é atualizada sozinha com o widget aberto.
• Agentes: registrado no painel.
• Não lidas: calculado por participante.

É daí que saem os indicadores de mensagens não lidas do widget e do painel.

Continuidade entre dispositivos

Para os contatos identificados, as conversas se sincronizam entre dispositivos e sobrevivem à limpeza do armazenamento:

• Você começa a conversa no desktop.
• Continua no celular.
• Reinstala o app ou limpa o armazenamento do navegador.
• Faz login de novo e se identifica com o mesmo externalId ou e-mail.
• Mesmo histórico, mesmo contexto.

Internamente, as conversas antigas guardam o ID do visitante que as criou. Depois da identificação, qualquer visitante atual ligado ao mesmo contato pode continuar listando, lendo e retomando essas conversas pelo contato compartilhado.

Os visitantes anônimos têm conversas ligadas ao dispositivo. Até serem identificados, o Fluxo limita o histórico ao ID de visitante guardado naquele dispositivo e navegador.

Construir sobre as conversas

Use os tipos Conversation gerados em @fluxolat/types para o status, a prioridade, o canal, a atribuição, o sentimento, as etiquetas, os participantes e o último item da linha do tempo. Para montar um fluxo próprio do widget, comece por Páginas e layouts e pela referência de hooks. As integrações de servidor devem usar o contrato OpenAPI gerado em packages/protocol/openapi.json; as chaves de API privadas ficam no servidor.

Saiba mais

• Itens da linha do tempo: as peças de uma conversa.
• Visitantes: os usuários anônimos que iniciam conversas.
• Contatos: usuários identificados, com histórico entre dispositivos.