> ## Documentation Index
> Fetch the complete documentation index at: https://botpress.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Measure HITL Response Time

> Measure the Time to First Agent Response for conversations in HITL.

## Prerequisites

> [!NOTE]
>
> You will need:
>
> * A [Botpress Plus plan](https://botpress.com/pricing) or higher
> * The [HITL integration and plugin configured](https://botpress.com/docs/integrations/integration-guides/hitl/introduction.md) so agents can join conversations

This guide explains how to measure the **Time to First Agent Response** for conversations handed off to a human agent via [Human-in-the-Loop (HITL)](https://botpress.com/docs/integrations/integration-guides/hitl/introduction.md). The metric captures how long a user waited from the moment they requested a human agent to the moment an agent was assigned.

The result is stored as a formatted string in a conversation variable and can be sent using a [Text Card](https://botpress.com/docs/studio/concepts/cards/send-messages.md#text), [sent to an external system](https://botpress.com/docs/studio/concepts/cards/execute-code.md), or [saved to a Botpress table](https://botpress.com/docs/studio/concepts/cards/tables.md#insert-record).

## 1. Create conversation variables

Create the following two variables in your bot, scoped as **Conversation** variables:

| Variable Name | Type | Description |
| :- | :- | :- |
| `hitlRequestTimestamp` | number | Unix timestamp (ms) of when the HITL request was made |
| `hitlTimingDisplay` | string | Formatted summary string of the timing result |

In Botpress Studio, go to **Variables** → **+ New Variable**, set the scope to **Conversation**, and configure each entry as described above.

## 2. Capture the request timestamp

Before your [Start HITL](https://botpress.com/docs/integrations/integration-guides/hitl/introduction.md#step-3-add-the-start-hitl-card-to-your-workflow) Card, insert an [Execute Code](https://botpress.com/docs/studio/concepts/cards/execute-code.md) Card that records when the user was handed off to HITL. Use the following code:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
conversation.hitlRequestTimestamp = Date.now()
```

This stores the exact moment the user was handed off to HITL, in milliseconds since the [Unix Epoch](https://en.wikipedia.org/wiki/Unix_time).

> [!NOTE]
>
> The **Unix Epoch** is January 1, 1970 at 00:00:00 UTC. Timestamps in "milliseconds since the Unix epoch" are the number of milliseconds elapsed since that moment.

## 3. Calculate and format the wait time

After your [Start HITL](https://botpress.com/docs/integrations/integration-guides/hitl/introduction.md#step-3-add-the-start-hitl-card-to-your-workflow) Card, insert another [Execute Code](https://botpress.com/docs/studio/concepts/cards/execute-code.md) Card that computes the time until an agent was assigned and formats the result. Use the following code:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const { conversation: upstream } = await client.getConversation({ id: event.conversationId })
const downstreamConvId = upstream.tags?.['hitl#downstream']

if (downstreamConvId) {
  const { conversation: downstream } = await client.getConversation({ id: downstreamConvId })
  const assignedAtMs = parseInt(downstream.tags?.['hitl:assignedAt'] || '0')

  if (assignedAtMs) {
    const requestTime = new Date(conversation.hitlRequestTimestamp)
    const assignedTime = new Date(assignedAtMs)

    const diffMs = assignedAtMs - Number(conversation.hitlRequestTimestamp)
    const diffMins = Math.floor(diffMs / 60000)
    const diffSecs = Math.floor((diffMs % 60000) / 1000)

    const fmt = (d) =>
      d.toLocaleTimeString('en-US', {
        hour: '2-digit',
        minute: '2-digit',
        second: '2-digit',
        hour12: true,
        timeZone: 'America/New_York'
      })

    conversation.hitlTimingDisplay =
      `HITL Request Time: ${fmt(requestTime)}\n` +
      `HITL Assignment Time: ${fmt(assignedTime)}\n` +
      `Wait Time: ${diffMins}m ${diffSecs}s`
  }
}
```

What this code does:

* Fetches the upstream conversation using the current conversation ID.
* Resolves the downstream HITL conversation via the `hitl#downstream` tag (set automatically by Botpress when a handoff is initiated).
* Reads the `hitl:assignedAt` tag from the downstream conversation (timestamp of when an agent accepted and assigned).
* Computes the wait time between the request and assignment.
* Formats and stores the result in `conversation.hitlTimingDisplay`.

Once the code runs, `conversation.hitlTimingDisplay` will contain a message in this format:

```
HITL Request Time: 8:28:07 PM
HITL Assignment Time: 8:28:31 PM
Wait Time: 0m 24s
```

> [!NOTE]
>
> Times are displayed in the America/New\_York timezone. Update the `timeZone` value in the `fmt` function if your team operates in a different timezone.

## 4. Use the data

The `conversation.hitlTimingDisplay` variable is available for the rest of your Workflow. You can:

* **Display it in chat**: Add a [Text](https://botpress.com/docs/studio/concepts/cards/send-messages.md#text) Card and reference `{{conversation.hitlTimingDisplay}}` to send the summary to the conversation (useful for testing and QA).
* **Log it to a Botpress Table**: Use an [Update Table Row](https://botpress.com/docs/studio/concepts/cards/tables.md#update-record) or [Insert Table Row](https://botpress.com/docs/studio/concepts/cards/tables.md#insert-record) Card to persist the data for reporting.
* **Send it to an external system**: Use an [Execute Code](https://botpress.com/docs/studio/concepts/cards/execute-code.md) Card with an `axios` or `fetch` call to forward the values to your analytics platform, CRM, or data warehouse.

> [!TIP]
>
> You can now measure Time to First Agent Response for HITL conversations and use the result in your bot Workflows, tables, or external systems.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.