Recipe: Hand off to a human

The bot can't solve everything. Catching the right moment to escalate keeps customers happy.

Hand off when the visitor explicitly asks

HANDOFF_PHRASES = [
    "speak to a human",
    "talk to a person",
    "real person",
    "agent please",
    "live chat",
    "this isn't helping",
]

def respond(message, context):
    msg = message.lower()
    for phrase in HANDOFF_PHRASES:
        if phrase in msg:
            return ("Of course — connecting you to a teammate now. "
                    "If they're not available right away, we'll email you within 1 working hour. "
                    "What's the best email to reach you on?")
    return None

When the bot returns this reply, your Live tracking dashboard will flash up the conversation so a human can take over (see Taking over a chat).

Hand off after 3 failed attempts

If the bot keeps saying "I'm not sure", that's a good escalation signal:

def respond(message, context):
    history = context.get("history", [])

    # Count recent "I don't know"-style replies from the bot
    fails = 0
    for turn in history[-6:]:
        if turn.get("role") == "assistant":
            content = turn.get("content", "").lower()
            if "i'm not sure" in content or "i don't know" in content or "i don't have that information" in content:
                fails += 1

    if fails >= 3:
        return ("I'm struggling to find the right answer for you. "
                "Let me get a teammate to help — what's the best email to reach you on?")
    return None

Hand off on urgent keywords

For some businesses, certain words mean "drop everything":

URGENT = ["leak", "flooding", "no heating", "no hot water", "emergency"]

def respond(message, context):
    msg = message.lower()
    if any(u in msg for u in URGENT):
        return ("That sounds urgent — please call our 24/7 emergency line on 0800 123 4567. "
                "I've also flagged this conversation for the on-call team.")
    return None

Combining handoff with email capture

If you want to actually capture an email when the bot escalates, see Recipe: Lead capture for the pattern.