Conversation insights

Your agents have thousands of conversations, and each one knows something: was the customer happy, did they get an answer, what product were they asking about. Normally that knowledge evaporates when the chat ends. Insights capture it.

Turn insights on and every conversation produces:

• A summary, at the length you choose
• Data points you define, extracted as structured values

The results become interactive charts on the agent's Stats page, with filters and drill-down into the underlying conversations.

Performance in an employee profile

New employee agents receive Conversation Insights by default during preparation. The preparation assistant chooses measures for the job, and the employee’s Performance card summarizes recorded observations. View performance opens the measures and links to the existing charts and insight settings. Empty values mean no observations are available yet.

This local example contains 3 analyzed synthetic invoice conversations. The measures show its amount, missing fields, and approval recommendation.

See Employees for the preparation workflow. The controls below define what agents capture.

Turn it on

Open your application: Agents, pick an agent, then open its Insights tab. Flip Enable Insights for this agent.

Enable insights, then choose when extraction runs and how many conversations are sampled.

Choose when insights are generated

• Only when the thread is archived (default): extraction runs once, when the conversation is archived.
• After every message: extraction refreshes after every agent reply. Good for live dashboards, but know the cost shape before you pick it: each refresh re-summarizes the whole conversation from scratch, not just the new message. That means the work, and the bill, grows with the square of the conversation length, not linearly with it. A conversation twice as long costs roughly four times as much to keep summarized on everyTurn. This applies only to messages within conversations selected by sampling. The rest of the conversations get no automatic extraction at all, at any frequency.

"Archived" is the real trigger, and it has a precondition. It means one of two concrete events: the agent's workflow runs an End node with "reset conversation history" enabled (which archives the thread), or the thread is archived directly (via the archive API, or the in-app archive button). There is currently no scheduled or inactivity-based archiver. Nothing in Docana closes a thread just because it went quiet. If your agent's workflow has no End node and nothing ever calls the archive API for its threads (a typical always-open, WhatsApp-style agent), onEnd will produce no automatic insights at all, not just delayed or partial ones. If that describes your agent, either add an End node that resets history when the conversation is logically done, archive threads explicitly from your own backend, or switch frequency to everyTurn.

Archiving a thread through the API, and generating insights on demand from the conversation view, always extract, regardless of which frequency you picked above. That's the escape hatch for the sampled-out case below.

To archive a thread from your backend:

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

Control cost with sampling

Frequency decides how often a conversation gets re-extracted; sampling decides which whole conversations get extracted automatically at all. It picks a percentage of conversations, not a percentage of messages. Set it below 100% and the agent skips automatic extraction for the rest of the conversations, at whatever frequency you configured above.

Sampling is decided once per conversation, not once per message: a thread is either in the sampled set for its entire life or out of it for its entire life. That's deliberate. A conversation that flipped in and out between messages would leave you with a partial insight history, and no chart or aggregate built on top of that is trustworthy. Dial sampling to 10% and roughly 1 in 10 conversations gets full insight coverage from start to finish. The other 9 get none automatically. This applies to every automatic extraction: after-every-message and an End node's automatic archival alike. In particular, when frequency is set to After every message, that per-message extraction only ever runs for messages that belong to a sampled conversation. Conversations outside the sample never trigger it, no matter how many messages they get.

Explicitly requested extraction is exempt from sampling. It always runs, no matter the rate. That covers archiving a thread through the API and generating insights on demand from the conversation view: both are a caller (you, a teammate, or your own backend) asking for insights on one specific conversation, and sampling never overrides an explicit ask. If a conversation was sampled out, its insights panel shows a Generate insights button that produces a snapshot on demand. This is the reason sampling is safe to turn down in the first place.

The honest caveat: lowering sampling weakens Share insights across past conversations. That feature injects a past conversation's summary into a new one, and it can only inject a summary that exists. If sampling means most past conversations were never automatically summarized, there's less for it to draw on, and returning customers are more likely to end up repeating themselves. If you rely on that feature, don't lower sampling without weighing the tradeoff.

Shape the summary

Pick a summary length:

• Short: 1 to 3 sentences. Quick context.
• Medium: 4 to 7 sentences. The default for most teams.
• Detailed: 8 to 15 sentences. For compliance or hand-off reviews.

Add custom instructions to steer it, like "Focus on action items, decisions made, and any unresolved questions."

Define data points

This is where insights earn their keep. Click Add Data Point and define:

• Name: what to call it, like "Customer Sentiment"
• Type: text, number, yes/no, or a list of options
• Description: tell the AI what to extract, like "The customer's overall mood by the end of the conversation"

Docana also suggests ready-made data points (Goal Achieved, Customer Sentiment, Resolution Status, Escalation Needed, Urgency, and more). Click Add all to start with those and prune later. You can define up to 50.

A yes/no or number data point can also decide the winner of an A/B experiment. Text points describe a conversation, but two versions cannot be ranked by them.

Choose suggested data points or define your own name, type, and extraction description.

Measure workflow events without AI

Some questions do not need a model to answer them. "Did this conversation reach the handoff step?" is a fact the workflow already knows. A data point's Source decides how its value is produced:

• AI conversation extraction (the default): a model reads the conversation and follows your description.
• Node reached: yes or no, did the workflow visit the node you pick. The type is locked to Boolean.
• Node execution count: how many times the workflow visited that node. The type is locked to Number.

Pick a source, then pick the node from the agent's current draft. Node-sourced points cost nothing to compute, give the same answer every time, and can be measured over past conversations (see backfill). That makes them the best winner metric for an experiment.

A Handed off to a human data point with Source set to Node reached and the workflow node picked from the current draft. Synthetic example agent.

Two things to keep straight. A visit means the workflow executed that node, including executions that failed there. It does not mean an external action succeeded or a business outcome happened. And the node belongs to a specific version of the agent: if a later draft removes or replaces it, the point keeps its saved binding until you pick another node.

Backfill node insights over past conversations

AI extraction only covers conversations that were sampled when they happened. Node-sourced points can look backwards, because the execution history is already stored. Below the data points, Backfill node insights measures saved node points for conversations created inside a date range.

The backfill box below the data points. Pick saved node points and a creation-date range, then start. Synthetic example agent.

How it counts:

• The range selects conversations by creation date. Each selected conversation is measured through the end of the range, not cut off at its start.
• The range can span at most 366 days and must end in the past.
• Progress reports conversations processed and, separately, point observations that were measured or unavailable. Large ranges run in batches of 100 conversations. Stop after the current batch, retry a failed one, or resume where you left off.

Backfill never invents evidence. A conversation whose history was pruned, whose version is gone, or whose execution records predate history tracking comes back as unavailable, not as zero. It also does not rerun AI extraction, and it leaves existing AI observations untouched.

See the results

Open the agent's Stats tab. Every data point is a chart. Click a segment to see the conversations behind it. "Why did escalations spike on Tuesday" stops being a meeting and becomes a click.

Remember users across conversations

Turn on Share insights across past conversations and the agent receives summaries of a user's previous conversations when a new one starts. Customers stop repeating themselves, and the agent picks up where things left off.

This depends on past conversations actually having summaries. If you've turned sampling down (see Control cost with sampling), fewer of them will. Weigh that before lowering the rate on an agent that leans on this feature.

Best practices

1. Start with the suggested data points: they cover what most teams ask first. Add custom ones when real questions come up.
2. Write descriptions like instructions: the description is a prompt. "Whether the user asked about pricing" extracts better than "pricing".
3. Prefer yes/no and options over free text: structured types make cleaner charts.
4. Use archive mode for outcome reporting: if you only read insights weekly, don't extract them on every message.

Next steps

• A/B Testing: Use a data point to decide whether a new version of the agent is better
• Testing Agents: Catch problems before they show up in your insights
• Routines: Run an agent on a schedule, like a weekly insights report