> ## Documentation Index
> Fetch the complete documentation index at: https://docs.caplena.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Chat Conversation Analysis
> Turn raw transcripts into structured, readable conversations.
If you've ever imported a chat transcript and seen it display as one long block of text, you know how hard that is to work with. Caplena can display each message as its own bubble, clearly labeled by speaker, just like a real conversation thread.
***
### How It Works
Three things need to be in place for chat parsing to work:
Tell Caplena who said what. Every message must start with one.
Tell Caplena which labels to look for. Without this, the column shows as plain text.
Ensure every row follows the same pattern so every message gets parsed correctly.
If all three are in place, Caplena renders the conversation as structured chat. If it can't reliably detect the structure, it falls back to the original text — nothing gets lost, but the structured view is much easier to read and analyze.
***
### Supported Formats
#### Speaker labels only
The most common format. Each message starts with a label, followed by the message text:
```text theme={null}
<> Hello<> Hi!
Alice Miller: Hallo
Peter Smith: Salve
[Agent] Hello
>>Customer>> Hi there
```
#### Speaker labels with timestamps
Timestamps before the speaker label are fully supported. Caplena handles the most common date and time formats automatically:
```text theme={null}
[12:34] <> Hello
[12:35] <> Hi!
03.12.2023, 18:01:56: Alice Miller: Hallo
[03.12.2023, 18:37:56] Peter Smith: Salve
03/12/2023, 6:01 PM - Alice Miller: Hallo
2023-12-03T18:01:56Z <> Hello
```
**The golden rule:** as long as every message starts with a recognizable label and that label is configured in Caplena, the transcript will parse correctly.
Not sure if your format will parse? [Download the sample file →](/hubfs/chat_transcripts_test.xlsx?hsLang=en) — it covers every supported format with real examples and shows exactly which speaker labels to configure for each one.
***
### Configure Speaker Labels
To enable chat parsing, tell Caplena which speaker labels appear in your data. This is done in column settings.
1. Open your project and go to **Project Settings**
2. Enable the **Chatbot conversation** toggle — this unlocks the speaker configuration fields
3. Under **Define who is speaking in your data**, click **+ Add speaker**
4. For each speaker, fill in:
* **Speaker name** – a display label (e.g. *User*, *Agent*). For display only.
* **Speaker identifier** – the **exact prefix string as it appears in your data** (e.g. `<>`, `Question:`, `Jon Doe:`)
* **Position** – whether the speaker's bubbles align **Left** or **Right**, just like a messaging app (e.g. customer on the left, agent on the right).
* **Color** – a bubble color so each speaker is easy to tell apart at a glance.
5. Add one entry per speaker. You can have up to 10.
The **Position** and **Color** styling applies everywhere chat transcripts are shown — the topic assignment row list, coding drawer, focus mode, and the row widgets in reports.
You don't have to set position and color manually — when Caplena detects the speakers it assigns sensible defaults automatically, alternating left/right so conversations stay readable. Adjust them only when you want something different.
The Speaker identifier field is a **free-text input**. Type the exact prefix from your data, including any brackets, colons, or special characters. Caplena matches character by character — a missing colon or extra space will prevent parsing.
Copy a real line from your data and paste just the prefix into the Speaker identifier field to avoid typos.
***
### Troubleshooting
**Why this happens:** Speaker labels either weren't configured or don't exactly match the data.
**What to check:** Take one real row from the dataset and compare it character by character with what's been configured. Pay close attention to spaces, brackets, colons, and capitalization. Then check a handful of other rows to confirm the same format is used throughout — different styles across rows can prevent parsing.
**Why this happens:** When a line doesn't start with a recognized speaker label, Caplena treats it as a continuation of the message above.
**What to check:** Look for label variations that haven't been configured — a third speaker, a bot with a slightly different label, or a line that was formatted differently. Make sure every label variation that appears in the data has been added to the column configuration.
**Why this happens:** When the format is too inconsistent to parse reliably, Caplena falls back to the original text rather than risk splitting messages incorrectly.
**What to check:** Look for rows that use a different pattern — a different label style, a different timestamp format, or a mix of both. Standardizing those outlier rows before import will usually resolve it.
**Why this happens:** Translations sometimes strip or reformat speaker labels, so the translated transcript loses the structure needed for chat parsing.
**What to check:** Compare an original row and its translated counterpart side by side. If labels are missing or reformatted in the translated version, the structured chat view won't be available for that content.