%20(1).avif){kind=small}
How to Configure Botpress Human Handoff for Webchat
To add human handoff to your website’s chat within HitlChat, connect your Botpress bot and choose the WebChat channel. HitlChat then powers a native chat widget on your site, allowing the 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.
You can tweak the widget in the snippet’s options — for example the title, theme colour, greeting message, and chat-button text.
Refresh your site and open the widget to confirm your Botpress bot replies — you’re connected. 🎉
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 snippet includes options such as the title, theme colour, greeting message and chat-button text, so you can match it to your brand.
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