Documentation Index
Fetch the complete documentation index at: https://botpress.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
The desk-hitl plugin connects your agent to Botpress Desk for human handoff. When escalated, your agent calls startHitl to create a Desk ticket and a support agent takes over from there.
Add desk-hitl to your agent
Add the plugin to agent.config.ts:
import { defineConfig, z } from "@botpress/runtime"
export default defineConfig({
name: "my-agent",
dependencies: {
integrations: {
webchat: "webchat@0.3.0",
},
plugins: {
"desk-hitl": {
version: "desk-hitl@latest",
},
},
},
})
Customize handoff messages
Override the default messages the plugin sends when an agent joins or a session ends:
plugins: {
"desk-hitl": {
version: "desk-hitl@latest",
config: {
agentAssignedMessage: "A support agent has joined the conversation.",
sessionEndedMessage: "The support session has ended. Is there anything else I can help you with?",
},
},
},
Connect your bot in Botpress Desk
To enable escalations, link your bot to Botpress Desk from the Desk UI. This is a one-time step per bot. Your bot must be deployed at least once before it appears in the list.
Run adk deploy to deploy your bot.
Go to AI Agents → Deflecting Bots.
If you skip this step, startHitl will fail with: “This bot is not connected to Botpress Desk. Enable it on the Deflecting Bots page in Botpress Desk, then republish.”
startHitl in an Autonomous.Tool so the model can decide when to escalate. Create a file called handToSupport.ts under src/tools/:
import { Autonomous, context, plugins, z } from "@botpress/runtime"
export default new Autonomous.Tool({
name: "handToSupport",
description:
"Transfer the conversation to a support agent. Use when the user explicitly asks for a support agent, or when their issue is beyond the bot's capabilities.",
input: z.object({
reason: z.string().describe("Why the conversation needs a support agent"),
priority: z.enum(["low", "medium", "high", "urgent"]).default("medium"),
}),
handler: async ({ reason, priority }) => {
const conversation = context.get("conversation")
await plugins["desk-hitl"].actions.startHitl({
conversationId: conversation.id,
title: reason,
priority,
})
},
})
startHitl:
| Field | Type | Description |
|---|
conversationId | string | The conversation to escalate — required |
title | string | Ticket title shown in Desk |
priority | 'low' | 'medium' | 'high' | 'urgent' | Ticket priority (default: 'medium') |
userName | string | Customer name shown in the Desk ticket |
userEmail | string | Customer email shown in the Desk ticket |
conversations/index.ts and instruct the model when to use it:
import { Conversation } from "@botpress/runtime"
import handToSupport from "../tools/handToSupport"
export default new Conversation({
channel: "*",
handler: async ({ execute }) => {
await execute({
instructions: `You are a helpful support assistant.
If the user needs help beyond your capabilities or explicitly asks for a support agent, use the handToSupport tool. After calling it, do not send any message.`,
tools: [handToSupport],
})
},
})
