How to add human handover to your WhatsApp AI agent

A great WhatsApp AI agent handles most conversations on its own. But some conversations need a human — and knowing when to step in is what separates a good bot from a frustrating one. Adding human handover to your WhatsApp AI agent is one of the highest-leverage things you can do, and it's simpler than most people expect.

TL;DR

• Human handover pauses your bot and notifies you when a conversation needs a real person — so customers never get stuck.
• Three trigger types cover almost every handover scenario: keyword triggers, confidence-based triggers, and time-based resumption.
• CodeWords makes it conversational. Just tell Cody, the builder inside CodeWords, "pause when I reply manually" and the handover logic is built for you.

Why human handover matters

No AI agent gets it right 100% of the time. A customer might have a complex complaint that needs empathy. A sales prospect might be ready to buy and want to talk to a real person before committing. A support question might require account access the bot doesn't have.

Without a handover mechanism, your bot does one of two things: it either keeps trying to answer and gets it wrong, or it says "I don't know" with no way forward. Both outcomes damage trust.

Human handover solves this cleanly. The bot recognizes it's out of its depth, pauses, alerts you, and gives you the full context to take over. The customer experiences a seamless transition — from bot to human — without repeating themselves.

The three trigger types

Keyword triggers

The simplest handover trigger is a keyword. When a customer types "agent", "human", "speak to someone", or "representative", the bot detects the intent and hands over immediately.

This is the most reliable trigger because it reflects explicit customer intent. The customer has decided they want a person. Respect that decision quickly.

You can define a list of keywords in your system prompt or logic layer. Common ones include:

• "human"
• "agent"
• "speak to someone"
• "call me"
• "manager"

Confidence-based triggers

A more sophisticated trigger fires when the AI itself doesn't know the answer with sufficient confidence. This is harder to implement at the model level, but you can approximate it by instructing your agent to say a specific phrase — like "I need to check this with my team" — when it's uncertain, and then treating that phrase as a handover signal.

Alternatively, if you're building with a platform that exposes confidence scores, you can set a threshold. Any response below that threshold routes to a human rather than being sent to the customer.

Time-based resumption

After a human has replied, you don't always want the bot to resume immediately. A natural pause — say, two hours — gives the conversation room to breathe. If the human hasn't continued the conversation after that window, the bot can step back in automatically.

This works well for businesses where the owner handles escalations during business hours and the bot covers the rest. The bot pauses at handover, the human deals with the issue, and the bot resumes overnight when the human is offline.

What happens during handover

When a handover is triggered, three things should happen in sequence.

First, the bot sends an acknowledgement to the customer. Something like: "I'm going to connect you with a member of our team. You'll hear back shortly." This sets expectations and stops the customer from sending five more messages wondering what's going on.

Second, the bot notifies you. The notification should arrive via Slack or email — whichever you check most often — and include the full conversation transcript so you have context before you reply. A notification that just says "new handover" without the conversation history is unhelpful.

Third, the bot pauses. It stops monitoring that conversation for new messages. If the customer messages again while you're handling it, the bot doesn't jump back in and create confusion.

How to build this with CodeWords

CodeWords makes handover logic straightforward because you describe it in plain English. Cody, the builder inside CodeWords, translates your description into a working agent.

When you're setting up your WhatsApp agent in CodeWords, tell Cody something like:

"If the customer says 'human', 'agent', or 'speak to someone', pause the bot, send them a message saying we'll follow up shortly, and notify me on Slack with the full conversation transcript. Resume the bot automatically if I haven't replied within two hours."

Cody builds that logic for you. You don't need to configure webhooks, set up conditional branches, or write a line of code.

For the Business API connection, handover works by updating a flag in memory — CodeWords uses Redis to track conversation state, so the bot knows which conversations are paused and which are active.

For the Personal Device connection, the mechanism is slightly different: the bot detects when a reply has been sent from the phone directly (rather than from the agent) and uses that as the signal to pause.

Permanent handover vs temporary pause

There's an important distinction between a permanent handover and a temporary pause.

A temporary pause is the most common pattern. The bot pauses, a human handles the issue, and the bot resumes after a set time window or once the human explicitly reactivates it. This is right for most service and support scenarios.

A permanent handover removes the conversation from bot coverage entirely. You'd use this for a customer who has specifically asked never to be handled by a bot, or for a sensitive situation — a complaint, a refund dispute, a potential churn risk — where ongoing human attention is warranted.

In CodeWords, you can tell Cody to support both: "If the customer says 'no bots', remove them from automated replies permanently." Cody adds that customer to an exclusion list stored in memory.

When to resume the bot

Resuming too quickly creates a jarring experience. Resuming too slowly leaves you doing manual work that the bot should be handling.

The right resumption timing depends on your business:

• High-volume support — resume after two hours if no human reply
• Sales — resume the next business morning if no human reply
• Personal assistant bots — don't auto-resume; manual reactivation only

You can also give the human an explicit resume command. Something like typing "resume bot" in the WhatsApp conversation triggers the system to hand back to the agent. This gives you control without requiring you to log into a dashboard.

Testing your handover flow

Before you go live, test the full handover sequence:

1. Send a message that triggers handover (type "human")
2. Confirm the bot sends the acknowledgement message
3. Confirm you receive the Slack or email notification with the transcript
4. Reply from your phone (for Personal Device) or from the dashboard (for Business API)
5. Wait for the auto-resumption window to expire
6. Confirm the bot picks up the next message normally

Edge cases to check: what happens if you reply while the bot is mid-sentence? What if the customer sends three messages before the handover acknowledgement arrives? These scenarios are worth testing before you have real customers in them.

Build a smarter agent that knows its limits

The best WhatsApp AI agents aren't the ones that try to handle everything — they're the ones that handle what they can and escalate gracefully when they can't. Human handover isn't a fallback for a bad bot; it's a feature of a great one.

If you're building your WhatsApp agent with CodeWords, you can describe your entire handover flow in plain English and have Cody build it for you. No code, no configuration files, no developer required.

---

Related reading

• How to build a WhatsApp AI agent in 2026 (no code)
• How to monitor and debug your WhatsApp AI agent in production
• WhatsApp AI agents vs traditional chatbots: what's the difference?

Three kinds of human involvement, not one

"Handover" gets used for three quite different things, and conflating them is how teams end up promising customers something they haven't built.

Contact instructions. The agent gives the customer a verified way to reach a person: a phone number, an email address, an office hours note. Nothing is transferred; the customer is told where to go. Simplest to build, and honest when nobody is available right now.

Owner notification. The agent alerts someone internally with a summary of the conversation and the customer's details. The customer doesn't reach a person in the moment, but a person knows and can follow up. This is the right default for most small operations.

Operator transfer. The conversation moves into a staffed queue where an agent picks it up live. This is what customers usually imagine when a bot says it's connecting them, and it only works if that queue exists, is connected, and has been tested end to end.

The failure that damages trust is a bot saying "connecting you to an agent" when what actually exists is the second kind, or the first. The customer waits for a person who was never coming.

Decide which of the three you have, build the message to match it exactly, and only promise a live transfer once you've verified the queue receives conversations and someone is watching it.

Designing the handback

Most guidance covers getting a conversation to a person and stops there, which leaves the more awkward half undone.

Decide who ends the takeover. The safest rule is that automation stays paused until a person explicitly releases it. Time-based resumption catches people mid-conversation and reads badly.

Carry the context forward. If the agent resumes, it needs to know what the person said, or it will contradict them. Nothing erodes trust faster than a bot cheerfully repeating an offer a colleague just withdrew.

Mark the transition. Customers should know when they're talking to a person and when they're not. A short line either way is enough, and it prevents the specific frustration of explaining something at length to software while believing it's staff.

Log both sides. For a complaint, an audit, or simply working out what happened, you want one record of the whole conversation rather than two halves in different systems.

The handback is where most implementations are thinnest, and it's where a customer's impression of the whole system gets set, because it's the part they experience as either seamless or obviously stitched together.

Frequently asked questions

What should the bot say when it hands over?

Whatever is literally true about what happens next. "I've passed this to the team and someone will reply here by tomorrow morning" sets a real expectation. "Connecting you now" should only appear if a person genuinely picks up now.

How quickly should a handover happen?

Immediately on an explicit request. When a customer asks for a person, that's a decision they've made, and arguing with it through two more bot turns is the most reliable way to make a mildly annoyed customer a properly annoyed one.

Should the bot resume afterwards?

Usually not in the same conversation without someone deciding it should. The safe default is that a human takeover pauses automation until a person explicitly releases it, because a bot rejoining mid-conversation after a complaint reads as dismissive.

What if nobody is available?

Then say so accurately rather than queueing someone indefinitely. Capture the request, tell the customer when to expect a reply, and make sure that promise reaches somebody who will keep it. An honest "tomorrow morning" is better service than an implied "shortly" that turns into Monday.

Should every conversation offer a route to a person?

Yes, and make it easy to find rather than a last resort after three failed attempts. Customers who can reach a person when they want one are more tolerant of an agent handling the rest, and hiding the exit produces exactly the frustration people associate with bots.

How do I test this properly before going live?

Trigger each path deliberately from a real customer number rather than an internal test account, and confirm a person actually receives it on the device they'd normally be using. The common failure is an escalation that works in testing because someone was watching the dashboard, and fails in practice because nobody has it open on a Saturday.

Should the handover route differ by topic?

Usually yes, and it's worth the extra setup. A billing question and a complaint want different people, and routing on topic means the person who picks it up can actually resolve it. Sending everything to one inbox is simpler to build and reliably slower for the customer.