%20(1).avif){kind=small}
How to Configure Botpress Human Handoff for Webchat
HitlChat powers a native Botpress chat widget on your website, allowing your Botpress bot’s conversation to be handed to a live agent the moment a human is needed.
What you need before adding Botpress web chat
- An existing Botpress bot (already built and published in Botpress).
- A HitlChat account: start a free trial if you don’t have one.
- Access to edit your website’s HTML (to paste the chat-widget snippet before
</body>).
Select Botpress in the HitlChat setup wizard
From the left menu, open Configuration. The Integration Setup tab loads with the heading “Let’s get you connected!” Under Select Integration Type, choose:
- Botpress: “Connect your existing Botpress chatbot to hitlchat and get conversation handover from your bot directly to your agents.” ← select this one.
- Voiceflow: for Voiceflow bots (covered in a separate guide).
- No chatbot: only if you want HitlChat for bulk WhatsApp messaging or the developer API, with no bot.
Click Next.
Selecting Botpress on the Integration Setup screen.
Choose WebChat as your channel
The next screen is headed “Choose how you’d like to connect your Chatbot”. The WhatsApp options at the top are for the WhatsApp channel (covered in a separate guide). Scroll to the WebChat Connection group and select:
- WebChat: “Enables human hand off using a native webchat widget on your website.”
Click Next.
Selecting WebChat under the WebChat Connection group.
Link your Botpress bot and enable human handoff
On the “Botpress Hitlchat Configuration” screen, connect HitlChat to your Botpress bot so it can route web-chat conversations to live agents. Fill in:
- Botpress Personal Access Token: in Botpress, click your profile (top right) → Account Settings ▸ Access Tokens ▸ Generate New Token, copy it, and paste it here.
- Botpress Messaging API URL: in Botpress Studio, click Integration Hub (top right), search for the Messaging API integration, install it, then copy the webhook URL it shows and paste it here.
- HitlChat Webhook URL: this one is read-only; copy it. Back in the Botpress Messaging API integration, paste it into the Response Endpoint URL box, click Save Configuration, and republish your bot.
- Bot Active toggle: leave on so your bot answers automatically. (You can pause it per-conversation later when a human takes over.)
Click Save.
Add the chat widget to your website
A green “Configuration Successful” pop-up appears: “Your WebChat configuration has been successfully saved!” It shows a widget code snippet with a Copy to Clipboard button.
Copy that snippet and paste it before the closing </body> tag on every page where you want the chat widget to appear. The widget then loads on your site, and when a visitor’s chat needs a person, the conversation is handed to a live agent in your HitlChat Inbox.
Before you copy it, set the widget’s style and branding in the Widget Script panel; the next section walks through every option.
Refresh your site and open the widget to confirm your Botpress bot replies. You’re connected. 🎉
Configure the widget: style, size & branding
Every visual and behavioural option lives in the Widget Script panel. Open Integrations, find your WebChat integration row, and click Widget Script; the same panel also appears right after setup. A live preview updates as you edit (widget style previews bottom-right, popover previews centre-screen; embed shows no preview because it renders wherever you place its container on your own page).
First, choose a widget style
- Widget (bottom-right popup): the classic launcher button in the corner that opens the chat panel above it.
- Popover (centered modal): the launcher opens the chat as a centred overlay instead, front and centre.
- Embed (inline on your page): the chat renders inside a container that ships with the snippet. Place
<div id="hitlchat-chat">wherever the conversation should live; embed style has no launcher button.
Every setting, at a glance
| Setting | What it controls | Default |
|---|---|---|
| Widget style | Widget, Popover, or Embed (above) | Widget |
| Header title | The name shown in the chat header (up to 60 characters) | HitlChat |
| Greeting message | The first message visitors see (up to 300 characters) | “Hi! How can we help?” |
| Chat button text | The launcher label, for widget and popover styles (up to 40 characters) | “Chat with us” |
| Header colour | The chat header, as a hex colour | #533dfe |
| Buttons colour | Launcher, send, attach, mic, and reply buttons | Matches the header colour |
| Width & height | Panel size in pixels (width 280–1000, height 360–1200) | 420 × 580 |
| Attachment uploads | Shows or hides the file-upload button | On |
| Voice transcription | Adds a record button so visitors can dictate their message | Off |
Botpress, web chat & human handoff FAQs
Do I need to rebuild my Botpress bot to add web chat?
No. HitlChat connects your existing Botpress bot: you install the Messaging API integration in Botpress, paste two values into HitlChat, then drop the widget snippet on your site.
Where do I add the chat widget to my website?
Paste the widget snippet from the success screen before the closing </body> tag on every page where you want the widget to appear. On most site builders this goes in a global “custom code / footer” area so it loads site-wide.
Can a human agent take over from the Botpress bot in web chat?
Yes, that’s HitlChat’s main purpose. You can pause the bot on any conversation and reply as a live agent, or use HITL keywords to trigger handoff automatically.
Can I customise how the chat widget looks?
Yes. The Widget Script panel lets you choose a display style (bottom-right widget, centred popover, or inline embed), set the title, greeting, and launcher text, pick header and button colours, resize the panel, and toggle attachments and voice transcription. Re-copy the snippet after saving changes.
What does the “Bot Active” toggle do?
When it’s on, your Botpress bot answers web-chat messages automatically. You can still pause the bot on individual conversations when an agent steps in.
Why isn’t my bot replying after setup?
Re-check that you pasted the HitlChat Webhook URL into Botpress’s Response Endpoint URL, clicked Save Configuration, and republished the bot, and that the widget snippet is installed on the page you’re testing.
How do I set up HITL keywords to hand off a chat to a human?
In HitlChat, go to Bot Settings and add your HITL keywords: words like “agent” or “human” that, when a visitor sends them, automatically transfer the web-chat conversation from your Botpress bot to a live agent.
Where do handed-off web-chat conversations appear for my team?
In the HitlChat Inbox, a shared inbox where your agents see live conversations, pick them up, reply with text or media, and transfer chats between teammates. Each team member gets their own login under User Access.
Can I use the same Botpress bot for web chat and WhatsApp?
Yes. Alongside WebChat, HitlChat connects the same Botpress bot to WhatsApp, all handled from the same shared inbox.
Related guides
See also: Botpress WebChat Handoff
Stories from real businesses
.svg)
"WhatsApp is where most of our online customer conversations happen. Our Voiceflow assistant handles the basic questions really well, but when questions get more complicated hitlchat allows our team to jump in instantly without having to move the customer to another channel. It feels like true live chat inside WhatsApp and we’ve seen higher conversions because of it"
"The hitlchat setup is super simple, and its easy to use! Most of our clients run small teams handling WhatsApp conversations powered by a Voiceflow bot. hitlchat gives them one shared workspace to manage all their conversations. Being able to step into bot conversations directly inside WhatsApp has transformed their support workflows."
"We've been building Voiceflow WhatsApp assistants for our clients across various industries (healthcare, ecommerce, restaurants etc) for a few years now. We had been looking for a way to route conversations from the Voiceflow assistant to live human agent for some time. Eventually we found out about hitlchat and honestly its been a gamechanger for us ever since. Our clients love it, and as a result we love it!"
Ready to try hitlchat ?
Create Your Free Account Now
No credit card required