Itens da linha do tempo

As peças flexíveis que formam a linha do tempo de uma conversa.

O que são itens da linha do tempo?

Os itens da linha do tempo são as peças que formam as conversas. Em vez de tratar uma conversa como uma lista plana de mensagens, o Fluxo guarda uma linha do tempo de registros estruturados que representam tanto o conteúdo do chat quanto tudo o que acontece ao redor dele.

Esse desenho permite históricos de conversa ricos e auditáveis, com:

Mensagens: conteúdo enviado pelo visitante, por um agente humano ou pela IA.
Eventos: atividades do sistema e mudanças de estado.
Registros de identificação: atividade de identificação de visitantes e contatos.
Atividade de ferramentas: registros da IA e das ferramentas.

Por que itens e não só mensagens?

Os sistemas de chat tradicionais só lidam com mensagens. A arquitetura de linha do tempo do Fluxo traz:

Histórico estruturado: dá para ver entradas de agentes, mudanças de status e resoluções.
Contexto rico: os eventos do sistema dão contexto entre as mensagens.
Flexibilidade: mensagens, eventos, identificação e atividade de ferramentas convivem num único histórico ordenado.
Extensibilidade: novos tipos podem ser adicionados sem quebrar as conversas existentes.

Tipos de item atuais

Itens de mensagem

Os itens de mensagem guardam o conteúdo que realmente é trocado numa conversa. Podem vir de um visitante, de alguém da equipe ou de um agente de IA.

O detalhe de implementação importante é que o text continua sendo o corpo original da mensagem. O conteúdo enriquecido e o derivado ficam em parts, então um mesmo item pode manter a mensagem original e ainda guardar anexos, metadados ou traduções.

Forma canônica de um item

Propriedade

Tipo

Partes de uma mensagem:

text: conteúdo em texto puro.
image: imagens anexadas, com URL e metadados.
file: arquivos anexados, com URL, nome e tamanho.
translation: texto traduzido e guardado para um público específico.
metadata: dados do canal de origem, como o widget, o e-mail ou a API.
reasoning e tool-call: raciocínio e atividade de ferramentas da IA, quando a política permite.
source-url, source-document e citation: procedência do conhecimento.
step-start: fronteira entre passos de execução do agente.
event e feedback: conteúdo estruturado de ciclo de vida ou de feedback.

A visibilidade e a política determinam quais partes cada público recebe. A regra importante é que as parts enriquecem o item em vez de substituir o text canônico dele.

Itens de evento

Os itens de evento são registros gerados pelo sistema que explicam o que mudou em volta da conversa.

Alguns exemplos comuns:

assigned: agente atribuído à conversa
unassigned: agente removido da conversa
participant_requested: outro participante foi solicitado
participant_joined: um agente entrou na conversa
participant_left: um agente saiu da conversa
status_changed: o status da conversa mudou
priority_changed: o nível de prioridade foi ajustado
tag_added: uma etiqueta foi aplicada à conversa
tag_removed: uma etiqueta foi removida da conversa
resolved: a conversa foi marcada como resolvida
reopened: uma conversa resolvida foi reaberta
visitor_blocked: o visitante foi bloqueado no suporte
visitor_unblocked: o visitante foi desbloqueado
visitor_identified: um visitante foi vinculado a dados de contato
ai_paused / ai_resumed: o estado de atendimento da IA mudou

Os eventos registram quem fez o quê e quando, criando um histórico transparente.

Itens de identificação

Os itens de identificação capturam os momentos em que o visitante passa a ser conhecido ou a identidade dele muda de forma relevante. Eles ajudam a manter um registro auditável da identificação do contato e das mudanças de ciclo de vida relacionadas, dentro da mesma linha do tempo.

Itens de ferramenta

Os itens de ferramenta representam a atividade da IA e das ferramentas gravada na linha do tempo. Conforme a visibilidade e a política de ferramentas, eles podem alimentar o progresso que o cliente vê, os logs internos ou os rastros de decisão, sem precisar de um modelo de armazenamento à parte.

Partes de tradução

As traduções são guardadas como partes translation dentro do mesmo item, em vez de substituir o text original. Assim o Fluxo mantém a mensagem de origem para sempre e ainda resolve o melhor texto para cada público.

As traduções de team são usadas no painel.
As de visitor são usadas no widget e nas demais telas do visitante.
O painel pode mostrar o texto traduzido e ainda oferecer Ver o original.
O widget pode preferir a tradução para o visitante quando ela existe.

Forma de uma parte de tradução

Propriedade

Tipo

Exemplo de tradução

{
  "type": "message",
  "text": "Hola, necesito ayuda con mi factura",
  "parts": [
    {
      "type": "translation",
      "text": "Hello, I need help with my invoice",
      "sourceLanguage": "es",
      "targetLanguage": "en",
      "audience": "team",
      "mode": "auto",
      "modelId": "google/gemini-2.5-flash-lite"
    }
  ]
}

Propriedades de um item

Todos os itens compartilham alguns campos comuns:

id: identificador único.
conversationId: a conversa a que pertence.
organizationId: a organização dona.
type: tipo de item (message, event, identification, tool).
text: o texto canônico ou original da mensagem, quando se aplica.
parts: array de partes de conteúdo estruturado.
visibility: public ou private (notas internas do agente).
createdAt: marca de tempo.

Campos de autoria (quem criou o item):

visitorId: se foi criado por um visitante.
userId: se foi criado por um agente humano.
aiAgentId: se foi criado por um agente de IA.

O deletedAt existe como campo interno de ciclo de vida, mas em geral não faz parte do modelo conceitual do dia a dia ao raciocinar sobre linhas do tempo.