How to Set Up Human Handoff Keywords & Bot Settings

In HitlChat’s Bot Settings you can control when your bot hands a conversation to a human. Add HITL keywords so customers can ask for a live agent, and set an inactivity timer to return idle chats to the bot. It works the same whether your bot is built in Botpress or Voiceflow.

Before you start

A connected bot (Botpress or Voiceflow). Bot Settings stay disabled until you’ve created an integration.
A HitlChat account with access to Bot Settings.

Open Bot Settings

From the left menu, click Bot Settings. The page has two tabs:

Human Hand-off Settings: your HITL keywords and notifications (Step 2).
General Settings: turn the bot on/off and set the inactivity timer (Step 3).

Set up your HITL keywords

On the Human Hand-off Settings tab, fill in the fields you need, then click Save:

Phrases to trigger human hand-off (applies to incoming messages only): the words a customer can send to reach a person, e.g. transfer to human, speak to agent. When a customer’s message contains one, the bot pauses and waits for a human agent to take over, and the chat is flagged Human Requested.
Phrases to hand control back to Bot (applies to outgoing messages only): when an agent sends a message containing one of these (e.g. Thank you for contacting us. Have a great day!), control is handed back to the bot and it resumes replying.
Email notifications (sent on every hand-off request): one or more email addresses (comma-separated) that get an alert whenever a customer requests a human.
Webhook URL (called on every hand-off request): a URL that receives a POST request on each hand-off, if you want to wire it into your own systems.

Handed-off chats land in the Human Req tab of your Inbox, where an agent can pick them up. See Take Over a Chat & Pause Your Bot.

Advanced Settings: bot on/off, timers & message gathering

Switch to the Advanced Settings tab for the bot behaviour controls:

Bot Active: toggle your Botpress or Voiceflow bot on or off for the whole integration. When set to Inactive, the bot will not respond to any incoming messages. This is how you completely deactivate the bot (different from pausing a single chat in the Inbox).
Image Transcription: when enabled, images sent by customers are transcribed for any text they contain and forwarded to the bot as a text message.
Audio Transcription Language: the language used when transcribing customer voice notes (and web chat voice input) to text. Auto Detect (the default) works well for longer recordings, but very short voice notes can be detected as the wrong language — if your customers speak a specific language, select it here for reliable transcriptions. Set per connection, so WhatsApp and web chat can each have their own language.
Do not pause bot on human handoff: when a handoff is triggered the chat is flagged Human Requested but the bot stays active, so the customer can keep chatting to it until an agent actually replies. Leave off to pause the bot on handoff (the default).
Auto-reassign to bot after inactivity: if a conversation has no activity for the number of minutes you set, it’s automatically handed back to the bot. Enter 0 to disable it; the maximum is 1440 (24 hours). Click Save to apply.
Bot Delay Response Time: delay each bot reply by the number of seconds you set before it’s sent to the customer, so responses feel more natural. Enter 0 to disable; the maximum is 60 (1 minute).
Message Gathering Time: when a customer fires off several messages in quick succession, wait for this many seconds of silence and forward them to the bot as one combined message — so the bot replies once to the whole burst instead of answering every message separately. Applies to text messages. Enter 0 to disable; the maximum is 60 (1 minute).

Example keyword sets to start from

Your keywords are whatever your customers actually type. These starter sets cover the common cases; trim and add to fit your audience and language.

Universal: agent, human, help, support, “talk to a person”, “real person”
eCommerce: refund, complaint, cancel, “where is my order”, damaged
Services & bookings: reschedule, quote, urgent, emergency, callback
B2B & sales: pricing, demo, “speak to sales”, partnership

For the outgoing direction, keep hand-back phrases distinct from anything an agent would type in normal conversation: “back to bot”, “bot resume”, “handing back”.

Pick words that are unambiguous on their own. “Help” catches genuine requests but also “this helped, thanks!” on phrase match; when in doubt, prefer two-word phrases.

HITL keywords & bot settings FAQs

How do I set up human handoff for a Botpress or Voiceflow bot?

It’s the same for both. To set up human handoff for a Botpress bot or a Voiceflow bot, open Bot Settings → Human Hand-off Settings and add your HITL trigger phrases. When a customer sends one, the bot pauses and the chat is flagged Human Requested for an agent to pick up.

What are HITL keywords?

HITL (human-in-the-loop) keywords are phrases that trigger a hand-off. When a customer’s incoming message contains one, the bot pauses and the chat is flagged Human Requested so an agent can take over.

Where do triggered chats show up?

In the Human Req tab of your Inbox. An agent opens the chat and takes it over from there; see Take Over a Chat & Pause Your Bot.

How does control go back to the bot?

Three ways: an agent re-assigns the chat to Bot in the Inbox; an agent sends one of your hand-back phrases (outgoing keywords); or the Auto-reassign after inactivity timer returns idle chats to the bot.

How do I completely turn the bot off?

On Advanced Settings, set the Bot Active toggle to Inactive. The bot then won’t respond to any incoming messages across your integration. (Pausing a single chat in the Inbox is separate and only affects that conversation.)

What does the inactivity timer do, and how do I disable it?

Auto-reassign to bot after inactivity returns a conversation to the bot if there’s no activity for the minutes you set. Enter 0 to disable it; the maximum is 1440 minutes (24 hours).

What is Message Gathering Time and when should I use it?

Customers often type in bursts — three or four short messages in a row. Without gathering, the bot answers each one, which creates an awkward back-and-forth. Set Message Gathering Time to a few seconds and HitlChat waits for that much silence, then forwards the whole burst to your bot as one combined message so it replies once, with full context. It applies to text messages; enter 0 to disable and 60 seconds is the maximum.

Can I be notified when a customer asks for a human?

Yes. Add email addresses under Email notifications and/or a Webhook URL; both fire on every hand-off request.

Does this work the same for Botpress and Voiceflow?

Yes. HITL keywords, the inactivity timer and the Bot Active toggle work identically whether your bot is built in Botpress or Voiceflow.

Related guides

Inbox

How to Take Over a Chat & Pause Your Bot

Take over a live chat in the Inbox: pause the bot, reply as a human, and hand control back.

Read guide →

Stories from real businesses

Daniel Ortega

eCommerce Ops Manager

"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"

Sanjay Mehta

Conversational AI Agency

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

Lucas Bennett

Voiceflow Developer

"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