Human-in-the-Loop (HITL)

Allow a live agent to participate directly in the bot’s conversation.

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:

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

2. 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.

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

2. Select it, then select Install Plugin.

3. 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.

4. Select HITL.
5. 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

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

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

   
3. 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.