Insights de conversa

Conversas de atendimento têm padrões úteis: assuntos que se repetem, problemas não resolvidos e clientes que precisam de um retorno. Os Insights transformam essas conversas em uma tabela que você pode revisar, classificar, consultar e enviar como relatório semanal. Cada conversa tem uma linha, mais um resumo do tamanho que você escolher.

Comece pela tabela

Abra sua aplicação, escolha um agente e abra Insights. Você vê a tabela dele e, acima dela, o momento em que os insights são gerados.

1. Revise as colunas sugeridas ou use Adicionar coluna para definir as suas.
2. Abra Configurações de insights para escolher quando a extração roda, a amostragem e as instruções do resumo.
3. Ligue Ativar insights ao lado do nome da tabela. O botão salva na hora. Com os Insights ativados, a tabela fica sempre atualizada.

Abrir esta página não inicia a extração nem cria uma tabela. O botão dos Insights controla a extração e as atualizações da tabela juntas. Ligar o botão de novo reaproveita a tabela existente e as colunas salvas.

Inspecione os registros e gerencie as colunas em Insights. Este exemplo de atendimento tem conversas fictícias.

Escolha quando os insights são gerados

Abra Configurações de insights. A aba Gatilho define quando os insights são gerados e quantas conversas entram na amostra. Resumo, Grupos e Compartilhamento têm abas próprias.

Três gatilhos. Ao arquivar é o padrão; Por chamada de API deixa o momento com o seu sistema.

• Ao arquivar (padrão): a extração roda uma vez, quando a conversa é arquivada.
• Após cada mensagem: a extração é refeita depois de cada resposta do agente. É boa para painéis ao vivo, mas entenda como o custo se comporta antes de escolher: cada atualização resume a conversa inteira do zero, não só a mensagem nova. Ou seja, o trabalho, e a conta, cresce com o quadrado do tamanho da conversa, não de forma linear. Uma conversa duas vezes mais longa custa cerca de quatro vezes mais para manter resumida em everyTurn. Isso vale só para as mensagens das conversas selecionadas pela amostragem. As demais conversas não recebem nenhuma extração automática, em nenhuma frequência.
• Por chamada de API: o Docana nunca extrai por conta própria. O seu sistema avisa quando uma conversa, ou um grupo de conversas, terminou. Veja Meça por chamada de API.

"Arquivada" é o gatilho real, e ele tem uma pré-condição. Significa um de dois eventos concretos: o fluxo do agente executa um nó de Fim com "Redefinir histórico da conversa" ligado (o que arquiva a thread), ou a thread é arquivada diretamente (pela API de arquivamento ou pelo botão de arquivar no app). Hoje não existe arquivamento agendado nem por inatividade. Nada no Docana fecha uma thread só porque ela ficou em silêncio. Se o fluxo do seu agente não tem nó de Fim e nada chama a API de arquivamento para as threads dele (o caso típico de um agente sempre aberto, no estilo WhatsApp), onEnd não gera nenhum insight automático, nem atrasado nem parcial. Se esse é o seu agente, adicione um nó de Fim que redefine o histórico quando a conversa termina de fato, arquive as threads explicitamente pelo seu backend ou mude para Por chamada de API e meça pelo seu backend quando a conversa terminar.

Arquivar uma thread pela API e gerar insights sob demanda pela tela da conversa sempre extraem, qualquer que seja a frequência escolhida acima. Essa é a saída para o caso de conversas fora da amostra, descrito abaixo.

Para arquivar uma thread pelo seu backend:

curl -X POST "https://platform.docana.com/api/v1/threads/${THREAD_ID}/archive/" \
  -H "Authorization: ApiKey ${DOCANA_API_KEY}"

Meça por chamada de API

Escolha Por chamada de API quando o seu sistema sabe melhor que o Docana quando uma conversa terminou: o CRM fecha o chamado, um atendimento acaba, uma pesquisa volta respondida. Nada é extraído até você chamar. Nós de Fim e mensagens novas não disparam a extração, e a amostragem não se aplica: toda chamada é medida.

1. Em Configurações de insights, escolha Por chamada de API na aba Gatilho e salve.

   

   Com o agrupamento ligado, a dica pede o valor do grupo, ticket.id aqui. Sem agrupamento, ela pede o id da conversa.

2. Crie uma API key de alguém que pode editar a aplicação.

3. Quando uma conversa terminar, envie o id dela para measureAgentInsights. Mostrar a requisição nas configurações traz essa chamada já com o seu agente e a sua aplicação preenchidos.

   curl -X POST https://platform.docana.com/api/v1/agents/your_agent_id/insights/measure/ \
     -H "Authorization: ApiKey your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{"applicationId": 1234, "threadId": "your_conversation_id"}'

4. O Docana responde 202 na hora e extrai em segundo plano. Os valores aparecem na tabela quando a extração termina.

   { "measuring": 1, "threadId": "your_conversation_id" }

Com o agrupamento ligado, envie o valor do grupo em group no lugar do threadId. O Docana mede todas as conversas desse grupo, até 100, e encerra o grupo. A resposta traz então group e endedAt.

Chamar de novo mede a conversa de novo. Os erros dizem o que corrigir:

• 409: os Insights estão desligados neste agente, ou o gatilho dele não é Por chamada de API.
• 400: um threadId enviado a um agente que agrupa conversas, um group enviado a um que não agrupa, ou um grupo com mais de 100 conversas.
• 404: nenhuma conversa deste agente tem esse threadId ou valor de grupo, ou o dono da API key não pode editar a aplicação.

A mesma chamada existe como a ferramenta measureAgentInsights no servidor MCP do Docana.

Controle o custo com amostragem

A frequência decide com que frequência uma conversa é extraída de novo. A amostragem decide quais conversas inteiras recebem extração automática. Ela escolhe uma porcentagem de conversas, não de mensagens. Defina um valor abaixo de 100% e o agente pula a extração automática nas demais conversas, em qualquer frequência que você configurou acima.

A amostragem é decidida uma vez por conversa, não uma vez por mensagem: uma thread fica dentro da amostra a vida inteira ou fora dela a vida inteira. Isso é proposital. Uma conversa que entrasse e saísse entre uma mensagem e outra deixaria você com um histórico de insights parcial, e nenhum gráfico ou agregado feito em cima disso seria confiável. Com a amostragem em 10%, mais ou menos 1 em cada 10 conversas recebe cobertura completa de insights, do começo ao fim. As outras 9 não recebem nada automaticamente. Isso vale para toda extração automática: tanto após cada mensagem quanto no arquivamento automático por um nó de Fim. Em especial, quando a frequência está em Após cada mensagem, essa extração por mensagem só roda para mensagens de uma conversa dentro da amostra. Conversas fora da amostra nunca a disparam, não importa quantas mensagens recebam.

A extração pedida explicitamente fica fora da amostragem. Ela sempre roda, qualquer que seja a taxa. Isso inclui arquivar uma thread pela API e gerar insights sob demanda pela tela da conversa: nos dois casos alguém (você, um colega ou o seu backend) está pedindo insights de uma conversa específica, e a amostragem nunca passa por cima de um pedido explícito. Se uma conversa ficou fora da amostra, o painel de insights dela mostra um botão Gerar Insights que produz um snapshot na hora. É por isso que dá para baixar a amostragem com segurança.

A ressalva honesta: baixar a amostragem enfraquece Compartilhar insights entre conversas anteriores. Esse recurso coloca o resumo de uma conversa anterior dentro de uma nova, e só pode usar um resumo que existe. Se, por causa da amostragem, a maioria das conversas anteriores nunca foi resumida automaticamente, sobra menos material, e clientes que voltam têm mais chance de precisar se repetir. Se você depende desse recurso, pese essa troca antes de baixar a amostragem.

Ajuste o resumo

Escolha um Tamanho do resumo:

• Curto: de 1 a 3 frases. Contexto rápido.
• Médio: de 4 a 7 frases. O padrão para a maioria dos times.
• Detalhado: de 8 a 15 frases. Para revisões de compliance ou de passagem de atendimento.

Adicione Instruções personalizadas para direcionar o resumo, como "Foque nos próximos passos, nas decisões tomadas e nas perguntas que ficaram sem resposta."

Defina as colunas

Escolha Adicionar coluna ou abra o menu de uma coluna para editá-la. Cada coluna extraída é um ponto de dados nos insights da conversa:

• Nome da coluna: um nome como Sentimento do Cliente.
• Tipo: texto, número ou booleano (sim/não).
• Fonte: extração da conversa por IA, um nó do fluxo alcançado ou a contagem de execuções dele.
• Descrição: o que extrair, como "O humor geral do cliente no fim da conversa. Use Positivo, Neutro ou Negativo."

Configurações novas sugerem sentimento, tópico e resolução. Você pode definir até 50 colunas extraídas. Editar uma coluna mantém a identidade dela e os valores já coletados. As novas instruções valem para as próximas extrações. Elas não apagam os valores existentes nem extraem de novo as conversas anteriores. Uma extração posterior do mesmo campo atualiza o valor dele na linha daquela conversa.

Colunas novas ficam vazias nas conversas mais antigas até esses campos serem extraídos. Se você quer fazer outra pergunta, adicione uma coluna nova em vez de reaproveitar a identidade de uma coluna existente. Remover uma coluna para a coleta e tira a coluna da tabela, mas preserva o histórico de insights das conversas.

Uma coluna de sim/não ou de número também pode decidir o vencedor de um experimento A/B. Colunas de texto descrevem uma conversa, mas não servem para comparar duas versões.

O editor de colunas muda o que o agente extrai. Colunas de classificação usam a ação Classificar, que é separada.

Meça eventos do fluxo sem IA

Algumas perguntas não precisam de um modelo para serem respondidas. "Esta conversa chegou na etapa de transferência?" é um fato que o fluxo já sabe. A Fonte de um ponto de dados decide como o valor dele é produzido:

• Extração da conversa por IA (o padrão): um modelo lê a conversa e segue a sua descrição.
• Nó alcançado: sim ou não, o fluxo passou pelo nó que você escolheu. O tipo fica travado em Booleano.
• Contagem de execuções do nó: quantas vezes o fluxo passou por esse nó. O tipo fica travado em Número.
• Subagente chamado: sim ou não, o fluxo chamou o subagente que você escolheu. O tipo fica travado em Booleano.
• Quantidade de chamadas ao subagente: quantas vezes o fluxo chamou esse subagente. O tipo fica travado em Número.

Escolha uma fonte e depois o nó, a partir do rascunho atual do agente. Pontos baseados em nó não custam nada para calcular, dão sempre a mesma resposta e podem ser medidos em conversas anteriores (veja o preenchimento de histórico). Isso faz deles a melhor métrica de vitória para um experimento.

Um ponto de dados Transferido para um humano com a Fonte em Nó alcançado e o nó do fluxo escolhido no rascunho atual. Agente de exemplo sintético.

Duas coisas para ter em mente. Uma passagem significa que o fluxo executou aquele nó, incluindo execuções que falharam ali. Não significa que uma ação externa deu certo ou que um resultado de negócio aconteceu. E o nó pertence a uma versão específica do agente: se um rascunho posterior remove ou substitui esse nó, o ponto mantém o vínculo salvo até você escolher outro nó.

Meça chamadas de subagentes em qualquer versão

Um nó aponta para uma versão do agente. Se você quer saber "o agente de transferência foi chamado?", teria que listar todos os nós que o chamam, e um nó adicionado em uma versão posterior ficaria de fora. Conversas que rodaram em outra versão voltariam como indisponíveis.

Subagente chamado e Quantidade de chamadas ao subagente resolvem isso apontando para o subagente em vez de um nó. Em cada execução, o Docana lê a versão do agente que de fato rodou, encontra os nós de subagente que chamam o agente escolhido e conta os que foram executados. Um nó novo que chama o mesmo subagente entra na conta sem você mexer no Insight, e o preenchimento de histórico também mede conversas de versões mais antigas. O seletor lista os subagentes que o rascunho atual chama.

Por exemplo, para acompanhar a taxa de transferência, adicione um ponto de dados booleano com subAgentCalled no agente de transferência:

{
  "id": "transfer-called",
  "name": "Transfer triggered",
  "description": "The conversation was transferred to a human attendant.",
  "type": "boolean",
  "source": { "kind": "subAgentCalled", "agentId": "your_transfer_agent_id" }
}

A fração de conversas com true é a sua taxa de transferência. Com um experimento agrupado por atendimento, o mesmo ponto dá a taxa de transferência por atendimento. O ID do agente vem de subAgents em listAgentInsightSourceNodes (ou docana agents insights nodes). Como o ID de um agente é o mesmo no controle e na candidata, um experimento que usa esse ponto como métrica principal pula a etapa de mapeamento de nós.

Preencha o histórico de insights de nós em conversas anteriores

A extração por IA só cobre as conversas que estavam na amostra quando aconteceram. Pontos de nó e de subagente conseguem olhar para trás, porque o histórico de execução já está guardado. Em Configurações de insights, Preencher histórico de insights de nós mede os pontos de nó salvos nas conversas criadas dentro de um intervalo de datas.

Preenchimento de histórico dos insights de nós salvos. Escolha os pontos de nó salvos e um intervalo de datas de criação e depois inicie. Agente de exemplo sintético.

Como a contagem funciona:

• O intervalo seleciona conversas pela data de criação. Cada conversa selecionada é medida até o fim do intervalo, sem ser cortada no começo dele.
• O intervalo pode ter no máximo 366 dias e precisa terminar no passado.
• O progresso mostra as conversas processadas e, separadamente, as observações de pontos que foram medidas ou ficaram indisponíveis. Intervalos grandes rodam em lotes de 100 conversas. Pare depois do lote atual, tente de novo um lote que falhou ou continue de onde parou.

O preenchimento de histórico nunca inventa evidência. Uma conversa cujo histórico foi podado, cuja versão não existe mais ou cujos registros de execução são de antes do rastreamento de histórico volta como indisponível, não como zero. Ele também não refaz a extração por IA e não mexe nas observações de IA existentes.

Veja os resultados

Revise as linhas direto em Insights. Escolha Gráficos para ver os padrões acima da tabela:

• Texto usa barras ordenadas com rótulos completos, contagens e porcentagens.
• Campos de sim/não mostram a divisão em um gráfico de rosca com uma legenda fácil de ler.
• Números mostram média, mediana, mínimo, máximo e os valores ao longo do tempo.

Abra Ver linha do tempo das conversas para ver as observações individuais e os links para as conversas ou execuções. Cada linha do tempo mostra no máximo as 500 observações mais recentes. Contagens, porcentagens, médias e outras estatísticas de resumo continuam incluindo todas as observações correspondentes no intervalo de datas escolhido. Os detalhes das conversas carregam quando a linha do tempo está visível.

Use o intervalo de datas e os filtros Produção/Avaliação para refinar os gráficos. Esses filtros são separados dos filtros e da paginação da tabela.

Os gráficos descrevem as observações de insights extraídas, incluindo observações repetidas quando a extração roda após cada mensagem. A tabela mantém uma linha atual por conversa. As colunas de classificação ficam disponíveis na tabela, mas não entram nesses gráficos de extração.

Stats continua focada no desempenho das execuções, duração, erros e avaliações.

Explore os padrões e os registros de origem no mesmo espaço de trabalho.

Conte resultados por grupo de conversas

Às vezes, uma conversa não é a unidade que importa. Um cliente abre um chamado, escreve no WhatsApp, volta no dia seguinte em uma conversa nova e recebe uma pesquisa de satisfação no fim. Você quer saber quantos chamados foram resolvidos sem transferência, não quantas conversas.

Se toda execução recebe o mesmo campo no contexto da requisição, o Docana consegue agrupar as conversas por ele. Em Configurações de insights, abra Grupos, marque Agrupar conversas por campo de contexto e digite o caminho com um nome de campo por caixa: ticket e depois id lê ticket.id.

Agrupado por ticket.id com Insights por chamada de API: o grupo termina quando o seu sistema o mede, e cada coluna de IA é lida uma vez para o grupo inteiro.

Quando um grupo termina depende da frequência com que os Insights são gerados:

• Ao arquivar ou Após cada mensagem: o Docana encerra o grupo N horas depois da última execução dele. 24 por padrão, até 168. Escolha um tempo maior que o intervalo comum entre duas conversas do mesmo grupo.
• Por chamada de API: o grupo termina quando o seu sistema o mede. Envie o valor do grupo em vez de uma conversa, o ticket.id neste exemplo, e o Docana mede cada conversa desse grupo, lê todas juntas para as colunas de IA e encerra o grupo:

curl -X POST https://platform.docana.com/api/v1/agents/your_agent_id/insights/measure/ \
  -H "Authorization: ApiKey your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"applicationId": 1234, "group": "T-1001"}'

Uma conversa com o mesmo valor depois da chamada abre o grupo de novo, então meça de novo quando ela terminar. Grupos que ninguém mede ficam em andamento e não contam. Uma chamada mede até 100 conversas.

Esta é a mesma configuração pela API, CLI ou MCP, como frequency e grouping ao lado de dataPoints. closeWhen acompanha a frequência: { "kind": "onRequest" } com "frequency": "onRequest", e { "kind": "idle", "hours": 24 } nos outros casos.

{
  "frequency": "onRequest",
  "grouping": {
    "path": ["ticket", "id"],
    "closeWhen": { "kind": "onRequest" }
  }
}

Uma conversa pertence ao grupo da execução mais recente deste agente que trouxe um valor. Execuções de subagentes não contam. Conversas sem valor, com um valor vazio ou com um objeto ou lista nesse caminho ficam fora dos grupos. Os gráficos mostram quantas foram. Caminhos dentro de env são recusados, porque os valores dos grupos aparecem na tabela.

Como uma coluna conta para um grupo depende de onde ela vem, e as configurações mostram isso ao lado de cada coluna:

• Colunas de IA são extraídas uma vez por grupo, lendo todas as conversas dele juntas, da mais antiga para a mais nova. Aí "O problema foi resolvido?" responde pelo chamado inteiro: resolvido na terceira conversa depois de duas tentativas que falharam conta como resolvido, e reaberto depois de resolvido conta como não resolvido. O grupo é lido quando termina. Se uma nova atividade o reabre, ele é lido de novo quando terminar de novo, e os valores novos substituem os anteriores.
• Colunas de nó e de subagente vêm do que cada conversa executou, então se combinam de forma exata: um sim/não é verdadeiro se qualquer conversa for verdadeira, e as contagens se somam.

Assim, uma coluna Transfer triggered no agente de transferência dá a fração de chamados que precisaram de transferência, e uma coluna de IA Resolvido dá a fração de chamados resolvidos, as duas por grupo.

Ler um grupo custa uma chamada de modelo a mais quando ele termina, além das chamadas de cada conversa. A transcrição guarda até 100 conversas e os 60.000 caracteres mais recentes. Passando disso, as conversas mais antigas ficam de fora. A amostragem vale por grupo, então um grupo é lido inteiro ou não é lido.

Os Gráficos abrem por grupo quando o agrupamento está ligado. Um grupo só conta depois que termina. A linha acima dos gráficos mostra quantos terminaram, quantos ainda estão em andamento e quantas conversas ficaram sem grupo. Mude para Conversa para ver os gráficos por conversa. O intervalo de datas escolhe os grupos pela última atividade, e um grupo que recebe nova atividade depois de terminar volta a ficar aberto até terminar de novo. A tabela mantém uma linha por conversa e adiciona uma coluna Group com o valor de cada conversa.

Use a tabela e envie relatórios

A tabela em Insights é a mesma Tabela gerenciada disponível em Tabelas. Abrir em Tabelas abre esse mesmo recurso. As duas telas compartilham filtros, o chat à esquerda, exportação, tela cheia, classificações e entregas. Os controles de envio e de extração de documentos ficam escondidos porque são as conversas que fornecem essas linhas.

Use Classificar para adicionar uma coluna de classificação, como Prioridade de retorno, com base nos valores salvos de resolução e de sentimento. Reclassificar não extrai as conversas de novo.

Escolha Entregas para configurar um relatório semanal. Inclua todos os registros correspondentes, filtre Conversation completed pelo período do relatório e escolha um agendamento para sexta-feira. Adicione um PDF ou um gráfico para resumir os tópicos e as taxas de resolução. Iniciar os Insights não agenda nem envia nada.

Os insights salvos compatíveis entram automaticamente, sem outra extração por IA. Não existe caixa de histórico nem botão de sincronização separado: com os Insights ativados, a tabela se atualiza sozinha. Desligue Ativar insights ao lado do nome da tabela para pausar a extração, o compartilhamento e as atualizações da tabela juntos. As linhas existentes continuam disponíveis, e você ainda pode editar as definições das colunas.

Cada conversa mantém uma linha, atualizada quando os insights compatíveis mudam. O histórico original de insights dela continua disponível. Conversation started, Conversation completed e Insights updated registram as datas relevantes. A amostragem e a frequência continuam decidindo quais conversas produzem resultados. Observações ausentes ou incompatíveis aparecem como células vazias.

Criar uma tabela segue os preços e o orçamento de tabelas do seu plano. Retomar as atualizações reaproveita a tabela existente. Agentes importados com Insights ativados e campos configurados também criam a tabela deles. Uma sincronização de conversa que falha tenta de novo de forma independente, enquanto as outras conversas continuam.

As permissões das conversas de origem e as políticas de linha da tabela continuam valendo. Compartilhar uma tabela não dá acesso a conversas privadas.

Use a mesma configuração pela API, CLI ou MCP.

Lembre os usuários entre conversas

Em Configurações de insights, abra Compartilhar com conversas anteriores e ligue Compartilhar insights entre conversas anteriores. A partir daí, o agente recebe resumos das conversas anteriores de um usuário quando uma nova começa. Os clientes param de se repetir, e o agente continua de onde as coisas pararam.

Isso depende de as conversas anteriores terem resumos de fato. Se você baixou a amostragem (veja Controle o custo com amostragem), menos delas vão ter. Pese isso antes de baixar a taxa em um agente que depende desse recurso.

Boas práticas

1. Comece pelos pontos de dados sugeridos: eles cobrem o que a maioria dos times pergunta primeiro. Adicione os seus quando surgirem perguntas reais.
2. Escreva as descrições como instruções: a descrição é um prompt. "Se o usuário perguntou sobre preços" extrai melhor que "preços".
3. Prefira sim/não ou rótulos fixos para categorias: use uma coluna booleana ou uma classificação com opções nomeadas.
4. Use o modo de arquivamento para relatórios de resultado: se você só lê os insights uma vez por semana, não extraia em toda mensagem.

Próximos passos

• Testes A/B: use um ponto de dados para decidir se uma nova versão do agente é melhor
• Testes de agentes: pegue problemas antes que eles apareçam nos seus insights
• Rotinas: rode um agente em um agendamento, como um relatório semanal de insights