The Human in the loop (HITL) interface allows you to implement human agent intervention in your integration.
Terminology
Throughout this document, we will use the following terms:- Integration
- The code that connects Botpress to an external service.
- External service
- The service that provides HITL functionality. This could be a help desk system like Zendesk, or any other system that allows human agents to send and receive messages to end users.
- Human agent
- A person who interacts with end users through the external service. This could be a support agent, a sales representative, or any other type of human agent.
- End user
- A person who interacts with your bot through Botpress. This could be a customer, a user, an employee, or any other type of end user.
- External user
- A representation of an end user within the external service. This is typically created when a HITL session is started.
- HITL session
- A conversation between an end user and a human agent. This is typically represented as a ticket in the external service.
- HITL interface
- The interface that defines the contract for implementing HITL functionality in your integration. This interface specifies the actions, events, and channels that your integration must implement to support HITL.
- HITL plugin
- The Botpress plugin that manages HITL sessions and relays messages between end users and your integration. Installing this plugin in a bot enables HITL functionality using the selected integration.
- Entity
- In the context of the HITL interface and plugin, an entity can be provided in order to support extra parameters in the
startHitl
action. This is useful to provide extra information about the HITL session, such as a ticket priority or customer identification number.
External service requirements
The external service providing HITL functionality must support the following:- An API that allows creating external users.
- An API that allows creating HITL sessions.
- An API that allows adding messages to HITL sessions.
- An API that allows closing HITL sessions.
- Webhooks that can notify your integration of the following events:
- HITL session closure.
- Human agent assignment.
- Human agent reply.
Updating your package.json
file
Finding the current interface version
The current version of thehitl
interface is:
You will need this version number for the next steps.
Adding the interface as a dependency
Once you have the HITL interface version, you can add it as a dependency to your integration:Open the package.json file
package.json
file.Add the dependencies section
bpDependencies
section in your integration‘s package.json
file, create one:Add the interface as a dependency
bpDependencies
section, add the HITL interface as a dependency. For example, for version 2.0.0
, you would add the following:"<interface-name>": "interface:<interface-name>@<version>"
.Save the package.json file
package.json
file.Install the interface
bp add
command to install it. This command will:- Download the interface from Botpress.
- Install it in a directory named
bp_modules
in your integration‘s root directory.
Adding a helper build script
To keep your integration up to date, we recommend adding a helper build script to yourpackage.json
file:
Open the package.json file
package.json
file.Add the build script
scripts
section, add the following script:build
script already exists in your package.json
file, please replace it.Save the package.json file
package.json
file.npm run build
, it will automatically install the HITL interface and build your integration.
Editing your integration definition file
Adding the interface to your integration definition file
Now that the HITL interface is installed, you must add it your integration definition file in order to implement it.Open the integration.definition.ts file
integration.definition.ts
file.Import the interface
Add an empty entity
new IntegrationDefinition()
statement, add an empty entity:ticket
or hitlTicket
.Extend your definition
.extend()
function at the end of your new IntegrationDefinition()
statement:.extend()
will be explained in the next section.Configuring the interface
The.extend()
function takes two arguments:
- The first argument is a reference to the interface you want to implement. In this case, it’s
hitl
. - The second argument is a configuration object. Using this object, you can override interface defaults with custom names, titles, and descriptions.
Renaming actions
Thehitl
interface defines three actions that are used to interact with the external service:
createUser
- Used by the HITL plugin to request the creation of a user in the external service and on Botpress.startHitl
- Used by the HITL plugin to request the creation of a HITL session in the external service.stopHitl
- Used by the HITL plugin to request the closure of a HITL session in the external service.
createUser
to hitlCreateUser
, you can do it like this:
startHitl
to createTicket
and stopHitl
to closeTicket
. These systems use tickets to represent help requests, so renaming actions to match their terminology makes your integration clearer and easier to understand.Renaming events
Thehitl
interface defines these events to notify the plugin of changes in the external service:
hitlAssigned
- Emitted by your integration to notify the HITL plugin that a human agent has been assigned to a HITL session.hitlStopped
- Emitted by your integration to notify the HITL plugin that a HITL session has been closed.
hitlAssigned
to agentAssigned
, you can do it like this:
Renaming channels
Thehitl
interface defines these channels:
hitl
- Used by the HITL plugin to send and receive messages from the external service. This represents the communication channel for the HITL session, like a support ticket on Zendesk or a direct message thread on Slack.
hitl
to supportTicket
, you can do it like this:
Implementing the interface
Implementing the actions
Implementing createUser
The createUser
action is used by the HITL plugin to request the creation of an external user (a requester) in the external service.
createUser
in the “Configuring the interface” section, please use the new name instead of createUser
.Create a Botpress user
client.createUser()
method.Create an external user
Map the external user to the Botpress user
Map the Botpress user to the external user
Yield control back to the plugin
Implementing startHitl
The startHitl
action is used by the HITL plugin to request the creation of a HITL session (typically a ticket) in the external service.
startHitl
in the “Configuring the interface” section, please use the new name instead of startHitl
.Fetch the Botpress user
input.userId
that was passed in the input parameters.Retrieve the external user's ID
Create a Botpress conversation
client.getOrCreateConversation()
method.Create the HITL session
Map the Botpress conversation to the HITL session
ticketId
tag on the Botpress conversation.Map the HITL session to the Botpress conversation
Yield control back to the plugin
Relaying the conversation history
The input parameters of thestartHitl
action contain a messageHistory
parameter. This parameter contains the conversation history that should be relayed to the external service to provide the human agent with context about the conversation. This parameter is an array of every message that was sent in the conversation prior to the HITL session being started.
If you decide to relay the conversation history to the external service, you can do so by iterating over the messageHistory
array and sending each message to the external service using its API or SDK. However, doing so might cause a significant number of notifications being sent to the external service. To alleviate this, you can choose to send only the last few messages in the conversation history, or to concatenate the messages into a single message. For example you could combine messages like this:
Adding extra parameters to the startHitl
action
If the external service requires extra parameters when starting a HITL session, you can add them to the hitlSession
entity, or whichever name you chose for the entity in the Adding the interface to your integration definition file section. For example, if the external service requires a priority
parameter, you can add it like this:
priority
parameter in the “Start HITL” card within the Botpress Studio, allowing the bot authors to set it. The value of this parameter will then be passed to the startHitl
action as part of the hitlSession
input parameter:
Implementing stopHitl
The stopHitl
action is used by the HITL plugin to request the closure of a HITL session (typically a ticket) in the external service.
stopHitl
in the “Configuring the interface” section, please use the new name instead of stopHitl
.Fetch the Botpress conversation
input.conversationId
that was passed in the input parameters.Retrieve the HITL session's ID
Close the HITL session
Yield control back to the plugin
reason
parameter. Please ignore it. This parameter will be removed in future versions of the HITL interface.Implementing the channel
Thehitl
channel is used by the HITL plugin relay end user messages to the HITL session, which is usually a ticket or thread in the external service.
hitl
in the “Configuring the interface” section, please use the new name instead of hitl
.Retrieve the HITL session's ID
Retrieve the external user's ID
- If the payload contains a
userId
parameter, the message has been sent by the end user. Retrieve the external user‘s ID from the tags of the Botpress userpayload.userId
. - If the payload doesn’t contain a
userId
parameter, the message has been sent by the bot. Retrieve the external user‘s ID from the tags of the attached Botpress user.
Send the message to the HITL session
Implementing the events
You should set up webhooks so that the integration receives notifications about these events:- A new message is added to the HITL session (usually a ticket).
- A human agent has been assigned to the HITL session.
- The HITL session was closed.
Incoming messages
When notified by the external service that a new message has been added to the HITL session, you should relay the message to the Botpress conversation:Retrieve the Botpress conversation's ID
Retrieve the external user's ID
Add a message to the Botpress conversation
client.createMessage()
method.Implementing hitlAssigned
When notified by the external service that a human agent has been assigned to the HITL session, you should notify the HITL plugin by emitting the hitlAssigned
event:
Retrieve the Botpress conversation's ID
Retrieve the external user's ID
Emit the hitlAssigned event
hitlAssigned
event by calling the client.createEvent()
method.hitlAssigned
in the “Configuring the interface” section, please use the new name instead of hitlAssigned
.Implementing hitlStopped
When notified by the external service that the HITL session was closed, you should notify the HITL plugin by emitting the hitlStopped
event:
Retrieve the Botpress conversation's ID
Retrieve the external user's ID
Emit the hitlStopped event
hitlStopped
event by calling the client.createEvent()
method.hitlStopped
in the “Configuring the interface” section, please use the new name instead of hitlStopped
.