# Chat Sessions

Chat Sessions is your primary tool for understanding how your agents behave in real conversations. Every interaction an agent has, across any channel, is recorded as a session. Each session captures the full transcript, the workflow execution trace, variable states, and metadata like duration and deployment origin.

This makes sessions the foundation of agent analysis. When a test fails, the result links to the session that caused it. When a user reports strange behavior, you trace it here. When you want to understand *why* an agent responded a certain way, the interaction log inside each session shows every step the workflow took to produce that response.

<div data-with-frame="true"><figure><img src="https://604830754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBM1xs3i59ajeTgi4uVfN%2Fuploads%2FQ8oZXmADwF9wenK5sxkM%2Fsession%20dashboard.png?alt=media&#x26;token=27566e66-dae1-444f-be0e-7aa179851604" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
Sessions appear in Observatory after they expire, not in real time. You can configure the [session expiration timer](https://docs.helvia.ai/build/agents#additional-settings) in **Designer > Settings > Configuration**.&#x20;
{% endhint %}

### Navigating Sessions

Open **Observatory > Sessions** to start exploring your agent's conversations. From here you can sort, filter, and tag sessions to find exactly what you need, then drill into any session to understand what happened and why.&#x20;

<table data-card-size="large" data-column-title-hidden data-view="cards"><thead><tr><th>Title</th><th>Description</th></tr></thead><tbody><tr><td><h4><i class="fa-magnifying-glass">:magnifying-glass:</i></h4><h4>Deep Dive</h4></td><td>Expand any session to inspect the full conversation, workflow trace, and variable states</td></tr><tr><td><h4><i class="fa-arrow-down-arrow-up">:arrow-down-arrow-up:</i></h4><h4>Sort &#x26; Browse</h4></td><td>Sort by date, scan across agents, and contacts to spot patterns at a glance</td></tr><tr><td><h4><i class="fa-tags">:tags:</i></h4><h4>Tag &#x26; Organize</h4></td><td>Review the tags each session collected during the workflow run and use them to filter and organize conversations</td></tr><tr><td><h4><i class="fa-down-to-bracket">:down-to-bracket:</i></h4><h4>Export Transcripts</h4></td><td>Download individual session records or export in bulk based on your current filters</td></tr></tbody></table>

Every session records the agent that handled it, when the conversation started, the contact who initiated it, which deployment served it, how long it lasted, and any tags assigned during the workflow. Click any session to expand it into the detail panel.

<div data-with-frame="true"><figure><img src="https://604830754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBM1xs3i59ajeTgi4uVfN%2Fuploads%2FbfCZtnUP4dYThbOdZUgk%2Fsessions%20table.png?alt=media&#x26;token=2d322a10-22bf-418b-88de-c535f6c0fcfb" alt=""><figcaption></figcaption></figure></div>

<details open>

<summary><strong>Agent</strong></summary>

The agent that handled the conversation. Each row displays the agent's name and icon.

</details>

<details>

<summary><strong>Created At</strong></summary>

The timestamp when the session started. Click the column header to sort sessions by date in ascending or descending order.

</details>

<details>

<summary><strong>Contact</strong></summary>

The end-user who initiated the conversation

</details>

<details>

<summary><strong>Deployment</strong></summary>

The specific deployment that served the conversation (e.g., "Webchat Production" or "Automated Agent Testing Deployment"). Useful for distinguishing between channels or test environments.

</details>

<details>

<summary><strong>Duration</strong></summary>

The total time elapsed from the first message to the last interaction in the session.

</details>

<details>

<summary><strong>Tags</strong></summary>

Labels assigned during the workflow run via the Tag node. Use tags to categorize and filter sessions by topic, intent, or any custom criteria you define in your workflows.

</details>

<details>

<summary><strong>Actions</strong></summary>

Two actions per row:

* Click the download icon to [export the session record](#exporting-sessions)
* Click the arrow icon to open the [session detail panel](#session-details)

</details>

### Searching and Filtering

All Observatory views share the same filters at the top of the page, a date range picker, time zone indicator, and an agent filter. If your results look unexpected or empty, check these first. Selecting the wrong date range or agent filter is the most common reason for missing sessions.

{% columns %}
{% column %}

#### <i class="fa-calendar">:calendar:</i> Date Range&#x20;

<div data-with-frame="true"><figure><img src="https://604830754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBM1xs3i59ajeTgi4uVfN%2Fuploads%2FC2X5hnQe5jlMgcUJHW4l%2Fdate%20picker.png?alt=media&#x26;token=32c035e5-d596-40c5-a50d-b413b927b932" alt=""><figcaption></figcaption></figure></div>

Set a start and end date to define the time window for displayed sessions. The timezone is shown below the picker for reference.

{% hint style="warning" %}
After selecting your dates, click **Apply** to update the results.
{% endhint %}
{% endcolumn %}

{% column %}

#### <i class="fa-robot">:robot:</i> Agents Filter

<div data-with-frame="true"><figure><img src="https://604830754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBM1xs3i59ajeTgi4uVfN%2Fuploads%2FX8XImkzpwG09j264czLJ%2Fagent%20picker.png?alt=media&#x26;token=6f1147ad-fd22-4402-af6c-4bb360abfc42" alt=""><figcaption></figcaption></figure></div>

Filter by agent or narrow it down to a specific deployment to isolate conversations from a particular channel or environment.
{% endcolumn %}
{% endcolumns %}

With hundreds of sessions accumulating over time, finding the right conversation requires more than scrolling. Use the search bar and quick filters together to surface exactly the sessions you need.

{% columns %}
{% column %}

#### <i class="fa-magnifying-glass">:magnifying-glass:</i> Search

<div data-with-frame="true"><figure><img src="https://604830754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBM1xs3i59ajeTgi4uVfN%2Fuploads%2FP2I9w4pzaby0UMqGryAA%2Fsearch%20by.png?alt=media&#x26;token=466f9f99-a99f-4946-a1e4-3460ff5fc20d" alt=""><figcaption></figcaption></figure></div>

Switch between seven search modes, each targeting a different session attribute like message content, tags, or variables

{% endcolumn %}

{% column %}

#### <i class="fa-filter">:filter:</i> Quick Filters

<div data-with-frame="true"><figure><img src="https://604830754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBM1xs3i59ajeTgi4uVfN%2Fuploads%2FJN5pEX0K95Xb9w9KYqYl%2Ffilter%20contains.png?alt=media&#x26;token=231665ca-86af-48c4-8c06-7abf1bbc567e" alt=""><figcaption></figcaption></figure></div>

Toggle filters for sessions with specific events like user feedback, LiveChat escalations, or CSAT responses.
{% endcolumn %}
{% endcolumns %}

{% hint style="success" %}
Combine filters with the date range and agent selector to narrow results quickly. For example, filter by "Contains CSAT Response" on a specific agent to find conversations with a user survey.&#x20;
{% endhint %}

### Session Details

Select any session to open the detail panel. This is where you move from browsing sessions to actually understanding what happened in a conversation. The panel splits into two areas: the conversation transcript on the left and a sidebar with metadata, variables, and tickets on the right:

<div data-with-frame="true"><figure><img src="https://604830754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBM1xs3i59ajeTgi4uVfN%2Fuploads%2FSVIBWDKTQGoFvGIGMfuw%2FSession%20details.png?alt=media&#x26;token=51299cd7-7359-4de7-85a5-b5f57da43463" alt="" width="563"><figcaption></figcaption></figure></div>

#### The Conversation Transcript

The transcript displays the full conversation with user messages on the left and agent messages on the right. This is the opposite of a typical chat interface, where the current user's messages appear on the right. Here, the perspective is reversed because you are reviewing someone else's conversation.

Each message is labeled as Bot or the user contact name along with a timestamp. The key feature of the transcript is that each user message is clickable. Clicking it reveals the [interaction log](#the-interaction-log) for that specific message, showing every step the workflow executed to produce the agent's response.

#### Sidebar Tabs

The sidebar provides context about the session:

{% tabs %}
{% tab title="Session Details" %}
Shows important metadata for the session. The session ID is useful when referencing a specific conversation in support requests or when using the API.&#x20;

Use the **Tags** field to manually add new tags to the session and review existing ones..&#x20;

This is also where you run and view Session Analysis. Click **Run** to generate insights, or review existing results if analysis has already been triggered automatically or from a previous run.
{% endtab %}

{% tab title="Variables" %}
A read-only snapshot of all workflow variables and their values at the end of the session. Use the search field to filter by variable name or value. This is useful for verifying whether the agent collected the right information during the conversation, like a user's intent, language, or any custom data your workflow captures.

To see how variables changed *during* the conversation, use the Variable Values tab inside the interaction log, which captures the state at each individual user message.
{% endtab %}

{% tab title="Contact" %}
Displays the end-user's name and email when available. This tab is not available for sessions generated by automated tests, since those conversations use synthetic users without real contact information.
{% endtab %}

{% tab title="Tickets" %}
A view of support tickets linked to this session from external ticketing platforms like Zendesk. If your agent creates or escalates tickets during a conversation, the references appear here so you can cross-reference the session with your support system.
{% endtab %}
{% endtabs %}

### The Interaction Log

Open the interaction log by selecting any user message in the conversation transcript.

<div data-with-frame="true"><figure><img src="https://604830754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBM1xs3i59ajeTgi4uVfN%2Fuploads%2FbiDbPdhTdzoB2hK5QlRr%2FSession%20transcript.png?alt=media&#x26;token=bfa9028a-41c2-467d-9c91-cb8260ce0300" alt="" width="563"><figcaption></figcaption></figure></div>

When your agent receives a user message, the workflow executes a series of steps to produce a response. A step corresponds to a single operation the workflow performed, like calling an LLM, assigning a variable or making a HTTP request. The interaction log captures this full sequence so you can see exactly what happened and in what order.

<table data-column-title-hidden data-view="cards"><thead><tr><th>Title</th><th>Description</th></tr></thead><tbody><tr><td><h4><i class="fa-clock">:clock:</i></h4><h4>Timestamp &#x26; Duration</h4></td><td>When the step executed and how long it took to complete. Use duration to identify slow operations in your workflow</td></tr><tr><td><h4><i class="fa-layer-group">:layer-group:</i></h4><h4>Type</h4></td><td>The kind of operation: LLM, HTTP, Semantic Search, Variable, or Tag. Filter by type to isolate specific steps</td></tr><tr><td><h4><i class="fa-triangle-exclamation">:triangle-exclamation:</i></h4><h4>Errors</h4></td><td>Whether the step failed. Filter by errors to jump directly to problematic operations without scanning the full trace</td></tr><tr><td><h4><i class="fa-code">:code:</i></h4><h4>JSON Payload</h4></td><td>Expand any step to see the raw request and response data. For LLM steps this includes the model, prompt and more</td></tr><tr><td><h4><i class="fa-copy">:copy:</i></h4><h4>Copy</h4></td><td>Hover over any JSON block to reveal the copy button. Grab the payload for further inspection or testing outside the platform</td></tr><tr><td><h4><i class="fa-brackets-curly">:brackets-curly:</i></h4><h4>Variable Values</h4></td><td>Switch to the <strong>Variable Values</strong> tab to see the state of all workflow variables at this point in the conversation</td></tr></tbody></table>

The interaction log panel also includes a **Variable Values** tab. This shows a snapshot of all workflow variables at the moment of that specific user message. Unlike the Variables tab in the sidebar (which shows final values), this captures intermediate state. Use it to verify that variables were assigned in the correct order with the expected values.

This is what makes session debugging concrete instead of speculative. Instead of guessing why your agent said something, you can trace the exact sequence of operations and see the raw data behind each one.

<details>

<summary><strong>Example: LLM JSON Payload</strong></summary>

```
{
  "request": {
    "model": "gpt-5.4",
    "prompt": "<prompt>",
    "history": [
      {
        "role": "assistant",
        "content": "Happy Wednesday morning! Ready to crush today’s priorities and keep things light? Let’s make this a smooth, focused start."
      },
      {
        "role": "user",
        "content": "Let's get started. How can I be more productive with my calendar?"
      }
    ],
    "provider": "OPEN_AI_LLM",
    "maxTokens": 250,
    "timestamp": "<timestamp>",
    "temperature": 0,
    "includeHistory": true,
    "maxHistoryTurns": 10
  },
  "response": {
    "reply": "",
    "timestamp": "<timestamp>",
    "extractedParams": {
      "message": "Use your calendar as a **plan, not a diary**:\n\n- **Time-block** your top 1–3 priorities daily\n- Add **buffers** (10–15 min) between meetings\n- Batch similar work (emails/admin) into set slots\n- Schedule **deep work** like a meeting (no notifications)\n- Do a **5-min daily plan** + **15-min weekly review**\n\nWhat calendar do you use (Google/Outlook/etc.) and what’s your biggest issue—overbooked, distractions, or forgetting tasks?"
    }
  }
}
```

</details>

### Session Analysis

Session Analysis turns individual conversations into structured, trackable data. It uses an LLM to generate insights from a completed session: a summary, sentiment score, resolution status, urgency level, and classification tags.

{% hint style="info" %}
Session Analysis is powered by a plugin that needs to be activated and configured first. See the [Plugins](https://docs.helvia.ai/build/plugins#session-analysis) page for setup instructions and advanced configuration options.
{% endhint %}

Open a session and navigate to the **Session Details** tab. Select **Run** to trigger it. After the first execution, the button changes to **Rerun**, letting you regenerate insights after updating your plugin configuration. To run analysis automatically on new sessions, configure the session analysis mode in the [plugin settings](https://docs.helvia.ai/build/plugins#session-analysis).

<div data-with-frame="true"><figure><img src="https://604830754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBM1xs3i59ajeTgi4uVfN%2Fuploads%2FPld5u9xpmvz05CUmHhUm%2Fsession%20analysis.png?alt=media&#x26;token=85236216-aee4-4470-b528-31470e541279" alt="" width="340"><figcaption></figcaption></figure></div>

### Exporting Sessions

Export session transcripts to share findings with your team or analyze conversations outside the platform. Three formats are available: txt, csv, and xlsx.

{% columns %}
{% column %}

#### <i class="fa-down-to-bracket">:down-to-bracket:</i> Individual Export

Click the download icon in the **Actions** column of any session row, or use the download button inside the session detail panel.
{% endcolumn %}

{% column %}

#### <i class="fa-box-arrow-down">:box-arrow-down:</i> Bulk Export

Click the download icon in the top-right toolbar to export multiple sessions at once based on your current filters and date range.

{% hint style="warning" %}
Sessions generated by automated tests are excluded from bulk export.&#x20;
{% endhint %}
{% endcolumn %}
{% endcolumns %}

<details>

<summary><strong>Example: Individual Session Record</strong></summary>

```
Timezone: Eastern European Standard Time

-- Session details:
Agent: <agent_id>
Session id: <session_id>
Date Created: <date>
Last Interaction: <date>
Duration: <duration>
Message Count: 3
Tags: []
Sentiment: 
Summary: 
Urgency: 
Resolution: 
Features: 
Metadata: [subscriberName=<name>, subscriberEmail=<email>, deploymentId=<deployment_id>, deploymentName=<deployment_name>, platformOrigin=<platform_origin>]
-- Messages
Sender | Time | Message | Tags | CSAT
<user_info> (user) | 10:35 | Jump to node: agent_start | [] | 
(bot) | 10:35 | Happy Wednesday morning! Ready to crush today’s priorities and keep things light? Let’s make this a smooth, focused start. | [] | 
<user_info> (user) | 10:35 |  Let's get started. How can I be more productive with my calendar? | [] | 
(bot) | 10:35 | Use your calendar as a **plan, not a diary**:

- **Time-block** your top 1–3 priorities daily
- Add **buffers** (10–15 min) between meetings
- Batch similar work (emails/admin) into set slots
- Schedule **deep work** like a meeting (no notifications)
- Do a **5-min daily plan** + **15-min weekly review**

What calendar do you use (Google/Outlook/etc.) and what’s your biggest issue—overbooked, distractions, or forgetting tasks? | [] | 

```

</details>

### Best Practices

* **Check your filters first:** The date range and agent filter are shared across Observatory. If sessions seem missing, verify these are set correctly
* **Go straight to the interaction log:** When debugging, open the interaction log on the problematic message. The execution trace tells you more than the response text alone
* **Use session analysis for trends:** Run analysis across sessions to track sentiment and resolution patterns over time. Use Expert Mode to define custom insight categories that match your business needs
* **Cross-reference with test results:** Automated test results link directly to their generated sessions. Use this to investigate why specific test scenarios failed

{% hint style="success" %}
You can now navigate sessions, search and filter conversations, inspect individual interactions down to the LLM call level, and generate structured insights with Session Analysis.
{% endhint %}