Human-in-the-Loop (HITL)

For new workspaces, HITL has moved to Botpress Desk, our new AI helpdesk for modern support teams. From your dashboard, go to Human Handoff > Open Botpress Desk to get started setting up your workspace.

Users on existing workspaces can follow the steps below and continue using the legacy HITL integration.

The Human-in-the-Loop (HITL) integration allows members of your Workspace to:

Chat directly with users
Approve AI-generated outputs before they’re sent
Handle complex or sensitive scenarios

The HITL integration needs to be configured before you can use Human Handoff.

Setup

You will need:

A Botpress Plus plan or higher

Step 1: Install the HITL integration

First, install the official HITL integration:

In Botpress Studio, select Explore Hub in the upper-right corner.

Search for the HITL integration, then select Install Integration.

Step 2: Install the HITL plugin

Next, install the official HITL plugin. This will allow you to start HITL from any point in your Workflow.

Navigate back to Botpress Hub and search for the HITL plugin.

Select it, then select Install Plugin.

In the Configuration menu, open the dropdown under HITL integration.

This dropdown will display all HITL-compatible integrations you’ve installed. Since this is a guide to the official Botpress HITL integration, we’ll select that one for now.

Select HITL.

Scroll down and select Save.

The plugin’s Configuration section contains many optional fields. You can use these to customize your HITL experience.

Step 3: Add the Start HITL card to your Workflow

Open a Workflow in Studio and create (or select) any Node.

Add the Start HITL Card at the point where you want to hand off conversations to a live agent:

In the Card’s inspector, fill in the required fields:

Fields	Description
Ticket Title	The name of the ticket created for the live agent.
User ID	The user ID associated with the ticket. Enter the `{{event.userId}}` variable to use the current user’s ID.
Conversation ID	The conversation ID associated with the ticket. Enter the `{{event.conversationId}}` variable to use the current conversation’s ID.

Done! HITL will begin whenever the Start HITL card executes.

For more information about assigning live agents and managing conversations, check out the Human Handoff guide.

Cards

Create external user

Create an end user in the external service and in Botpress

inputobject

outputobject

Start new HITL session

Create a new HITL session in the external service and in Botpress

inputobject

outputobject

Stop HITL session

Stop an existing HITL session in the external service

inputobject

Triggers

hitlAssigned

payloadobject

hitlStopped

payloadobject