Measure HITL Response Time

Prerequisites

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). 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, sent to an external system, or saved to a Botpress table.

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 Card, insert an Execute Code Card that records when the user was handed off to HITL. Use the following code:

conversation.hitlRequestTimestamp = Date.now()

This stores the exact moment the user was handed off to HITL, in milliseconds since the Unix Epoch.

3. Calculate and format the wait time

After your Start HITL Card, insert another Execute Code Card that computes the time until an agent was assigned and formats the result. Use the following code:

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

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 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 or Insert Table Row Card to persist the data for reporting.
• Send it to an external system: Use an Execute Code Card with an axios or fetch call to forward the values to your analytics platform, CRM, or data warehouse.