Handoff rules
The AI bot can hand conversations over to a human agent automatically (handoff). This happens based on configurable rules.
Enable handoff
Settings → AI bot → Handoff → Enable handoff
If handoff is switched off, keywords, semantic detection and "Hand over when the bot is unsure" no longer apply. Three cases hand over anyway, because the bot cannot sensibly keep answering: the maximum number of bot replies is reached (if set), the AI quota is used up, or the AI returns an empty answer and no fallback text is stored.
Handoff triggers
1. Keywords
Settings → AI bot → Handoff → Handoff keywords
A comma-separated list of keywords. If a visitor message contains one of them, the conversation is handed over to an agent immediately — before the bot answers at all.
Recommended starter list (10–15 concise words cover about 80% of cases):
agent, human, person, employee, real support, talk to someone, to the team, phone, lawyer, complaint, cancel, claim, escalation, manager
Tips for choosing keywords:
- Specific enough to avoid false positives (for example
humanrather thanthe) - Prefer short word stems — matching is case-insensitive and partly ignores word boundaries, but stems that are too generic, such as
help, also catch harmless questions like "can you help me?" - No ellipses or special characters — matching works on plain text
- Not too long — 10–15 good words beat 50 mediocre ones. Paraphrases are covered by semantic detection (see below)
2. Semantic detection (the AI decides)
Settings → AI bot → Handoff → Semantic detection (AI decides)
The AI reads the visitor message and decides itself whether a handoff is wanted — also for paraphrases or in other languages. Examples that keywords do not catch, but semantic detection does:
- "Is there someone I can talk to?"
- "I would rather speak to a real person"
- "Can I talk to a real human please?"
- "Am I in the right place or is there a case worker?"
How it works: the system prompt tells the AI to write only the marker [HANDOFF] when it detects handoff intent, without any text of its own. The stream buffer removes the marker and it triggers the handoff; the visitor never sees it. The confirmation ("One moment — I am checking whether an agent is available.") follows as a system message in the visitor's language — so the bot never stays silent on a handoff request, and the wording is always the same.
When to enable it? The default is on. Turn it off only if you want full control over the AI replies and do not want paraphrased handoff requests handled automatically.
Coexistence with keywords: both rules are independent — keywords apply before the AI is chosen (cheaper, deterministic), semantic detection only during the AI reply.
3. Max turns
Settings → AI bot → Handoff → Max. bot replies before handoff
After a certain number of bot messages the conversation is handed over to an agent automatically. Prevents endless bot loops.
- 0: disabled (no limit)
- 3–5: recommended range for support bots
- 10+: for bots that should answer many questions
4. Bot uncertainty
Settings → AI bot → Handoff → Hand over when the bot is unsure and Also hand over on off-topic questions
If the bot finds nothing in the knowledge base above the match threshold, the switch Also hand over on off-topic questions decides:
- Off (default): it does not hand over at once. The AI answers itself: if the question fits your topic and only the knowledge is missing, it does not guess but says it has nothing reliable on that. If the visitor then asks for a human, semantic detection hands over. If the question has nothing to do with your offer (time, recipes, general knowledge), it politely declines without tying up a team member.
- On: every question below the threshold goes straight to a human without asking the AI (reason low_confidence). Until September 2026 this was the only behaviour.
In both cases the knowledge gap is recorded under Knowledge Base → Gaps. "Hand over when the bot is unsure" also controls whether the conversation goes to your team when the AI fails (reason ai_error, only after all reserve models have failed too).
Knowledge gap within your own topic: If the AI only lacks the knowledge, it offers the visitor a handover to a human ("Shall I hand you over to a team member?") and hands over once the visitor agrees. This only applies when handoff is switched on and AI detection is on ("Hand over when the bot is unsure"). With handoff switched off the AI makes no such offer and does not hand over. The same applies to the maximum number of bot replies (section 3), an exhausted AI quota and an empty model response: without handoff switched on there is no handover, the visitor gets a short notice, and the message lands in your inbox.
What happens during a handoff?
The handoff is progressive, so the visitor always knows what is happening:
-
Confirmation (
handoff_checking) — as soon as a handoff is detected, the visitor immediately sees a system message ("One moment, I am checking whether an agent is available."). This applies to every trigger, including semantic detection. -
Check agent availability — the routing system queries the presence status of all team members.
-
Depending on the result:
(a) At least one agent online (
handoff_connected)- The conversation gets status
handoff— it appears as new in the dashboard inbox - The visitor sees: "I have forwarded your request. An agent will be with you shortly."
- No automatic assignment: the first agent who replies takes the conversation (first reply wins). The team decides who steps in — nobody has a conversation pushed on them.
(b) No agent online (
handoff_no_agents_choice)- The visitor gets a choice card with two options:
- "Leave a message" — opens the offline form (if enabled), otherwise the fallback contacts (see below)
- "Keep chatting with me" — the AI takes over again. The status changes from
handoffback toopen, and the visitor can simply ask the next question
(c) Timeout (
handoff_timeout) — agents are online, but nobody replied within the configured window- The visitor sees the same choice card as in (b): "Leave a message" or "Keep chatting with me"
- The conversation returns to
openso the cron job does not pick it up again
- The conversation gets status
-
Tracking — every handoff is recorded with its reason (
keyword/ai_intent/max_turns/low_confidence) in the AI resolution analytics — regardless of whether the escalation succeeded.
Configure the handoff timeout
The wait after which the timeout choice card appears when no agent replies can be set on three levels. The first positive number in this order applies:
- Widget:
Dashboard → Widgets → [Widget] → Availability → Handoff timeout (override)— for single widgets, overrides tenant and system - Tenant:
Dashboard → Settings → AI bot → Handoff timeout (tenant default)— applies to all widgets of this tenant unless a widget override is set - System default: runtime-config key
handoff_timeout_minutes(super admin only, via the database). If empty: 2 minutes hard-coded.
Recommended values:
- 1–2 minutes for responsive teams (business hours, many agents online) — minimal wait for the visitor
- 5–10 minutes for asynchronous teams — agents have time to see the inbox and respond themselves
- > 15 minutes: rather unsuitable — use the offline form and CSAT flow instead
The cron job runs every 60 seconds. Worst-case latency = configured timeout + up to 60 s.
Fallback contacts for widget visitors
Widget configuration → Offline behavior → Fallback contacts
Two optional fields:
| Field | Purpose |
|---|---|
| Public phone number | Shown as a tel: link in the widget |
| Public email address | Shown as a mailto: link in the widget |
These contacts appear in the widget only if all of the following are true:
- A handoff was triggered
- No agent is online
- The visitor clicks "Leave a message"
- The offline form is disabled in the widget (offline behavior = "Hide widget completely")
If both fields are empty, the widget shows a friendly "please try again later" message instead. If the offline form is active, the form still takes over — the fallback contacts then stay hidden.
Handoff reasons in analytics
Under AI → Resolution analytics → Handoff reasons you see why handoffs happen:
| Reason | Description |
|---|---|
| keyword | Handoff keyword found in the visitor message |
| ai_intent | The AI detected a handoff request semantically (paraphrase) |
| max_turns | Maximum bot turns reached |
| low_confidence | No matches above the threshold, "Also hand over on off-topic questions" is on |
| ai_error | The AI was unreachable (all reserve models failed) |
| empty_response | The AI answered without content, no fallback text stored |
| quota_blocked | The AI quota is used up |
| agent_responded | An agent took over manually |
What your team sees on a handoff
On every handoff SilentChat writes a line into the conversation that names the reason — with the details that belong to it.
| Reason | What is shown in addition |
|---|---|
| keyword | the keyword that triggered it |
| ai_intent | that the AI recognised the request by meaning |
| max_turns | the number of bot replies after which it ended |
| low_confidence | the confidence value and the number of knowledge entries found |
| empty_response | the AI answered, but without content |
| ai_error | the AI was unreachable or reported an error |
| quota_blocked | the AI quota is used up |
| bot_rule | name and ID of the rule that applied |
⚠️ The visitor does not see this line. It is delivered only to your team, not to the widget. That is why it may also contain details that would confuse a visitor — such as confidence values.
Without the reason every handoff looks the same. A team that takes over ten times a day cannot otherwise tell whether the visitor explicitly asked for a human (all fine), whether the bot did not find the answer in the knowledge base (gap — add it) or whether the quota was used up (check your plan). These are three different tasks, and only the first is no task.
Questions outside your topic
A separate switch under Settings → AI bot → Handoff → Also hand over on off-topic questions decides what happens with questions unrelated to your offer.
- Off (default): the bot says kindly that it cannot help with that and stays in the conversation.
- On: such questions lead to a handoff to a human.
Leave the switch off if your widget is publicly reachable. Otherwise every question about the weather ends up with your team.
A handed-over conversation stays with a human
Once handed over, no further question from the visitor triggers another handoff. The conversation belongs to your team until it is closed. The bot is only responsible again if the visitor chooses "Keep chatting with me" on the choice card (no agent online or wait time expired) or starts a new conversation.
Best practices
- Set keywords conservatively — too many keywords = too many handoffs
- Set max turns to 5 to begin with, then adjust based on data
- Leave "Also hand over on off-topic questions" off as long as your widget is publicly reachable — the AI then does not invent an answer, and anyone who asks for a human is still handed over
- Check the resolution analytics regularly to tune handoff reasons
- Enter fallback contacts if you have disabled the offline form — otherwise visitors see only the "please try again later" notice when no agent is available. With a phone number or email the visitor can get in touch straight from the widget.