The Human-in-the-Loop (HITL) integration brings human oversight and intervention into AI-driven Workflows. It allows members of your Workspace to:

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

​
Setup

You will need:

1

Install the HITL integration to your bot

First, install the official HITL integration. This will allow you to respond to users directly within Botpress.

  1. In the Studio, select Explore Hub in the upper-right corner.
  2. Search for the HITL integration. Select it, then select Install Integration:

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:

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

  1. Select HITL.
  2. Scroll down and select Save.

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

3

Add the Start HITL card to your Workflow

Now, you can bring a live agent into the conversation anywhere in your Workflow:

  1. Open a Workflow in Studio and create (or select) a Node.
  2. Add the Start HITL Card:

  1. Fill in the required fields:
FieldsDescription
Ticket TitleThe name of the ticket created for the live agent.
User IDThe user ID associated with the ticket. Enter the {{event.userId}} variable to use the current user’s ID.
Conversation IDThe 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.

​
Respond to users

Now that you’ve set up HITL, you can assign someone in your Workspace to respond to users.

This guide shows you how respond to users with the official Botpress HITL integration. However, you can also use a compatible third-party integration like Zendesk.

1

Publish and test your bot

First, let’s simulate a user escalation.

HITL won’t work in the Emulator — you’ll need to test it using Webchat.

  1. Publish your bot and open the Webchat preview window.
  2. Chat with your bot until it begins HITL:

2

Assign the conversation

  1. Navigate to your Dashboard, then select Human-in-the-loop under your bot’s navigation bar.
  2. Select the conversation you just started:

This will open the conversation with the user. From here, you can either assign the conversation to yourself or to another member in your Workspace.

  1. Try assigning the conversation to yourself. Select Assign to me:

Now you can chat directly with the user:

Done! Now you can chat with your users directly using HITL.

​
Key Features

There are many advantages to incorporating HITL in your Workflow: