# Sessions

Sessions is your primary tool for understanding how your agents behave in real conversations. Every interaction an agent has, whether text, voice, or a mix of both, across any channel, is recorded as a session in **Observatory > Sessions**. Each one holds the full conversation along with the data you need to understand what happened and why.

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, open the session and follow the workflow steps that produced that response.

Once you have found the session you are looking for, [Inside a Session](https://docs.helvia.ai/observatory/inside-a-session) covers everything you can learn from it, including the transcript, metadata and the complete execution trace.

<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 are available even before they expire. Use the refresh button <i class="fa-arrow-rotate-right">:arrow-rotate-right:</i> to reload the session list and see ongoing conversations as they come in.
{% endhint %}

### Navigating Sessions

Open **Observatory > Sessions > Chat Sessions** to start exploring your agent's conversations. From here you can sort, filter, and tag sessions to find exactly what you need. Whether you are investigating a user complaint, reviewing test results, or tracking how a workflow change affects real conversations, this is your starting point.

<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><a href="inside-a-session">Expand any session</a> 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](https://docs.helvia.ai/inside-a-session#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 %}

### 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>

### Missed Questions

A missed question is a user message that your workflow explicitly flagged as something the agent could not answer. Go to **Observatory > Sessions > Missed Questions** to see them. This is not automatic detection. You decide where in the workflow a question counts as "missed" by placing a Missed Question Node on the path where the agent has no answer.

<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%2FEgraAhJTyJGcX46WG3H5%2Fmissed%20question%20node.png?alt=media&#x26;token=c99f182e-4864-4fec-8e20-e612b1ed1f98" alt="" width="130"><figcaption></figcaption></figure></div>

This makes missed questions a targeted feedback loop. Instead of guessing what users are asking that your agent can't handle, you get a concrete list sorted by frequency. Review it regularly to prioritize new content, update existing workflows, or expand your knowledge base.

{% hint style="info" %}
To see missed question trends over time and how they compare to answered questions, check the [Missed Questions tab](https://docs.helvia.ai/analytics#missed-questions) in Analytics.
{% endhint %}

#### Reporting Missed Questions

Before anything appears in Observatory, you need to tell the platform which user messages count as missed. Place the **Missed Question Node** in the workflow path where the agent cannot provide an answer. Any user message that reaches this node gets recorded as a missed question, linked to the session and the specific message that triggered it.

<details>

<summary><strong>Advanced: Reporting via the API</strong></summary>

You can also report missed questions programmatically or with a **HTTP Request Node** by sending a POST request with the following payload:

```json
{
  "missedQuestion": {
    "question": "{{userTextMessage}}"
  },
  "sessionId": "{{sessionId}}",
  "messageId": "{{messageId}}"
}
```

Each report is tied to a specific session and message, so it appears in the same context as node-reported questions.

</details>

Two system variables let you build workflow logic around missed questions. Use `{{missedQuestionsCount}}` to track the total number of misses in the current session, and `{{consecutiveMissedQuestionsCount}}` to detect when the agent fails multiple times in a row. For example, you could escalate to LiveChat after three consecutive misses. See [Variables](https://docs.helvia.ai/build/variables#system-variables-reference) for the full list.

#### Browsing Missed Questions

The Missed Questions table collects every reported question in one place. Identical questions are grouped into a single row with an occurrence count, so repeated questions surface at the top rather than cluttering the list. Grouping is based on exact wording, so two messages phrased differently appear as separate rows even if the intent is the same.

<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%2FBDqBtBX95pJ8jxtsMkLe%2FMissed%20question%20dashboard.png?alt=media&#x26;token=47b04ab6-cdc4-4446-b380-2c6bfb68c7a7" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
Sort by **Occurrences** to prioritize the highest-impact knowledge gaps first.
{% endhint %}

The page shares the same date range and agent filters as Chat Sessions. If results look unexpected, check these first. Use the search bar to find specific questions by keyword, or narrow results to a particular agent or deployment with the agents filter. Export the full list as a CSV file using the **Download** button and use the adjacent options menu <i class="fa-ellipsis">:ellipsis:</i> to choose between comma or semicolon separation.

#### Investigating a Missed Question

Knowing *what* was missed is only the starting point. You need the surrounding conversation to understand *why* it was missed and decide how to fix it.

Select any row to open the **Missed Question Details** panel. At the top, a stats bar shows three metrics: the number of occurrences within your date range, the total occurrences since the agent was created, and how many distinct chat sessions contained this question.

<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%2F1kc0iALZHAzX7ulGsJiQ%2Fmissed%20question%20details.png?alt=media&#x26;token=92b24af7-29eb-43f0-97f4-e37752e387a4" alt="" width="375"><figcaption></figcaption></figure></div>

From here you can browse and select any session where the question appeared and see the conversation transcript with the missed question highlighted. This gives you the context to understand whether the gap is a missing intent, unexpected phrasing, or a workflow routing issue. Select **Go to Session** to open the full session for a deeper look.

### 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
* **Review missed questions by frequency:** Sort by occurrences to surface the most common knowledge gaps first. Fixing one high-frequency miss improves more conversations than fixing ten rare ones
* **Tag sessions for follow-up:** Use tags to mark sessions that need review, retraining, or escalation so your team can filter for them later
* **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 browse, filter, and export sessions, and track unanswered user questions through Missed Questions.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.helvia.ai/observatory/sessions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.