# Human Handoff

> Configure keyword-based handoff to route conversations to your team when needed.

Source: https://waslo.io/docs/human-handoff · Last updated: 2026-10-12

## How Handoff Works

When a customer uses specific keywords in their message, Waslo automatically:

1. Pauses the AI agent for that conversation
2. Flags the lead as needing a person (shown as "Needs Attention" on the dashboard and "Handoff" in the Leads table)
3. Sends a configured handoff message to the customer
4. Notifies your team via Email, WhatsApp, or Telegram (if configured; WhatsApp alerts need a connected Waslo QR number, or an official number whose ready-made alert template is approved)
5. Shows the lead in the **Needs Attention** widget on your dashboard

## Setting Up Handoff

1. Go to **AI Agent → Human Handoff**
2. Toggle **Enable Human Handoff**
3. Add keywords that should trigger a handoff (e.g., "speak to someone", "human", "agent", "manager")
4. Customize the handoff message the customer receives

### Example Handoff Message

> "I'm connecting you with a team member who can help you further. They'll be with you shortly!"

## Handoff Keywords

Add keywords that indicate a customer wants to speak to a human. Common examples:

- "speak to someone"
- "human"
- "agent"
- "manager"
- "real person"
- "help me"
- "complaint"

The default list on a new workspace is **human, agent, بشر, موظف** — add or remove keywords for your own scripts and languages.

### How keywords are matched

Keywords match as **whole words**, not as a raw substring — so a short keyword no longer fires inside an unrelated word. A few deliberate exceptions keep real-world phrasing working:

- **Latin-script keywords of 4+ letters** also match common Spanish/Portuguese/Turkish inflected forms. The keyword "human" also matches "humano"; "agent" also matches "agente".
- **Arabic-script keywords** also match when wrapped in a small set of Arabic clitics: the definite article "ال" and its combined forms ("وال", "بال", "فال", "كال", "لل"), the standalone letters "و", "ف", "ب", "ل", and the masculine plural endings "ين"/"ون". So the keyword "موظف" (employee) also matches "الموظف" (the employee) and "الموظفين" (the employees).
  - **Tip:** this doesn't extend to the feminine endings ة/ى/ات — "موظف" will **not** match "موظفة" (a female employee). If you want that caught too, add "موظفة" as its own keyword.
- **Chinese, Japanese, and Thai** keywords still match as a plain substring, since these scripts don't use spaces between words — so "转人工" still matches anywhere inside a longer message.

## Per-Number Handoff

You can configure different handoff keywords and messages per WhatsApp number using the **Context Selector** at the top of **AI Agent → Human Handoff**. Per-channel handoff configuration (Telegram, Instagram, etc.) is on the roadmap — for now those channels use the org default.

Saving your handoff settings for a specific WhatsApp number or channel only touches the handoff fields on that page — it no longer overwrites that same number's or channel's personality or classification settings, and saving those pages no longer erases handoff settings either. Each settings page saves independently.

## Replying yourself pauses the agent

When you answer a customer yourself, the agent steps back for that customer so the two of you never reply over each other. This works wherever you can type outside Waslo:

| Where you replied | Pauses the agent |
|-------------------|------------------|
| The Waslo inbox | Yes |
| Your phone, on a Waslo QR number | Yes |
| The WhatsApp Business app, on an official QR number | Yes — the app's automatic greeting and away messages don't |
| Meta Business Suite or the Messenger app | Yes |
| The Instagram app | Yes |
| Outlook, in a thread the agent is handling | Yes (checked every minute) |
| A Telegram Business account (the account connection) | Yes |
| Telegram, on the bot connection | No |

Your reply also appears in the Waslo thread, so the history stays complete. The lead panel shows why the agent paused.

## When two agents talk to each other

If your number ends up chatting with another automated agent, the two could reply to each other forever. Waslo stops that: when the agent keeps replying to the same sender — **3 replies within 10 minutes** if the other side is itself a number connected to Waslo, or **12 replies within 10 minutes** for anyone else — it pauses that conversation and marks it **Needs Attention** with the reason. Resume it like any other pause once you've checked it. This applies to WhatsApp QR and WhatsApp Cloud numbers.

## Team hours and the wait for a person

Under **AI Agent → Human Handoff → Team hours** you can set when someone from your team is around. Outside those hours, a customer who asks for a person is not left waiting on a paused agent: the agent says when your team is back, asks for an email or phone if it has none, keeps helping, and the conversation stays in your queue. With no hours set, your team counts as always available.

On website chat, if nobody takes a request for a person within the wait you choose (10 minutes by default), the visitor is told the team is busy, asked for a way to reach them, and the agent resumes. Turn on **Also on WhatsApp and other channels** to apply the same wait everywhere; otherwise the other channels keep waiting for a person.

## Resuming AI

After handling a lead personally, click **Resume AI**:

1. In the conversation header in the Inbox (the quickest way), or
2. On the **Leads** page — the lead's agent-status cell shows "Handoff" when a person is needed, or "Paused" when the agent is paused — or
3. From the **Needs Attention** widget on the dashboard.

The AI will start responding to new messages again.

## Telegram Notifications

Get instant notifications when a handoff is triggered:

1. Go to **Integrations → Telegram Notifications**
2. Set up your Telegram bot and chat ID
3. Enable **Notify on handoff**

You'll receive a Telegram message with the lead's name, phone number, and the message that triggered the handoff.
