Handoff rules

The AI bot can automatically transfer conversations to a human agent (handoff). This happens based on configurable rules.

Enable Handoff

Settings → AI Chatbot → Enable Handoff

When handoff is disabled, the bot always responds — even if it is uncertain.

Handoff Triggers

1. Keywords

Settings → AI Chatbot → Handoff Keywords

Comma-separated list of keywords. If a visitor message contains one of these words, immediately transfer to an agent — before the bot even responds.

Recommended Starter List (10-15 concise words cover about 80% of cases):

agent, human, employee, person, support employee, real support, talk to someone, to the team, phone, lawyer, complaint, cancel, claim, escalation, manager

Tips for Keyword Selection:

Specific enough to avoid false positives (e.g., human instead of the)
Prefer short stems — matching is case-insensitive and partially ignores word boundaries, but too generic stems like help also catch harmless questions like "can you help me?"
No ellipses/special characters — matching is done 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 (AI Decides)

Settings → AI Chatbot → Semantic Detection

The AI reads the visitor message and decides whether a handoff request is present — even for paraphrases or in other languages. Examples that are not covered by keywords, but are by semantic detection:

"Is there someone I can talk to?"
"I would rather talk to a real person"
"Can I talk to a real human please?"
"Am I in the right place or is there a caseworker?"

How it works: The AI is instructed by the system prompt to first write a short confirmation sentence (e.g., "Of course, just a moment — I will check if an agent is available.") and append the marker [HANDOFF] at the end. The confirmation text runs normally to the visitor and is stored in the conversation; the marker is removed from the stream buffer and triggers the escalation. This way, the AI never responds silently to a handoff request — the visitor always sees a confirmation before the system takes over.

When to enable? Default is on. Only deactivate it if you want full control over the AI responses and do not want to automatically allow paraphrased handoff.

Coexistence with Keywords: Both rules are independent — keywords take effect before the AI is even selected (cheaper, deterministic), semantic detection only during the AI response.

3. Max Turns

Settings → AI Chatbot → Handoff After X Turns

After a certain number of bot messages, automatically transfer to an agent. Prevents endless bot loops.

0: Disabled (no limit)
3–5: Recommended range for support bots
10+: For bots that need to answer many questions

4. Low Confidence

Settings → AI Chatbot → Handoff at Low Confidence

If the bot does not find a relevant KB entry (confidence below the threshold), transfer to an agent instead of giving an uncertain answer.

What Happens During Handoff?

Handoff occurs progressively, so the visitor knows at every moment what is happening:

Confirmation (handoff_checking) — As soon as a handoff is detected, the visitor immediately sees a system message ("Just a moment, I am checking if an agent is available."). With semantic detection, this confirmation also comes from the AI response.
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 the status handoff — it appears in the dashboard inbox as new
- The visitor sees: "I have forwarded your request. An agent will contact you shortly."
- No automatic assignment: the first agent to respond takes over the conversation (first reply wins). This way, the team decides who jumps in — no one gets a conversation "forced upon" 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 activated), otherwise the fallback contacts (see below)
  - „Continue chatting with me" — the AI takes over again. The status changes from handoff back to open, the visitor can simply ask the next question
(c) Timeout (handoff_timeout) — Agents online, but no one has responded within the configured window
- The visitor sees the same choice card as in (b): "Leave a message" or "Continue chatting with me"
- The conversation changes back to open so the cron does not pick it up again
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 was successful.

Configure Handoff Timeout

The waiting time after which the timeout choice card appears when no agent responds can be set at three levels. The first positive number in this order applies:

Widget: Dashboard → Widgets → [Widget] → Availability → Handoff Timeout (Override) — for individual widgets, overrides tenant + system
Tenant: Dashboard → Settings → AI Chatbot → Handoff → Handoff Timeout (Tenant Default) — applies to all widgets of this tenant, except if widget override is set
System Default: RuntimeConfig key handoff_timeout_minutes (only super-admin via DB). If empty: 2 minutes hardcoded.

Recommended values:

1–2 minutes for reactive teams (business hours, many agents online) — minimal waiting time for the visitor
5–10 minutes for asynchronous teams — agents have time to see the inbox and react themselves
> 15 minutes: rather unsuitable — better use offline form + CSAT flow

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	Displayed as `tel:` link in the widget
Public Email Address	Displayed as `mailto:` link in the widget

These contacts appear in the widget only if all of the following conditions are met:

A handoff was triggered
No agent is online
The visitor clicks on "Leave a message"
The offline form is disabled in the widget (Offline Behavior = "Hide widget completely")

If both fields are empty, the widget instead shows a friendly "please try again later" message. If the offline form is active, the form continues to take precedence — the fallback contacts remain hidden.

Handoff Reasons in Analytics

Under AI → Resolution Analytics → Handoff Reasons, you can see why handoffs occur:

Reason	Description
keyword	Handoff keyword detected in visitor message
ai_intent	AI semantically detected handoff request (paraphrase)
max_turns	Maximum bot turns reached
low_confidence	No relevant KB results found
agent_responded	Agent manually took over

What Your Team Sees During a Handoff

For every handoff, SilentChat writes a line in the conversation that states the reason — with the details belonging to that reason.

Reason	Additional Information
keyword	the keyword that triggered it
ai_intent	that the AI recognized the request semantically
max_turns	the number of bot responses after which it ended
low_confidence	the confidence value and the number of knowledge base entries found
empty_response	the AI responded but without content
ai_error	the AI was not reachable or reported an error
quota_blocked	the AI quota is exhausted
bot_rule	name and ID of the rule that applied

⚠️ The visitor does not see this line. It is delivered exclusively to your team, not to the widget. Therefore, it can also contain information 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 distinguish whether the visitor explicitly asked for a human (everything is fine), whether the bot did not find the answer in the knowledge base (gap — add it later) or whether the quota was exhausted (check tariff). These are three different tasks, and only the first one is not a task.

Questions Outside Your Topic

A separate switch under Settings → AI Bot determines what happens to questions that have nothing to do with your offering.

Off (default): The bot politely states that it cannot contribute to this and stays in the conversation.
On: Such questions lead to a handoff to a human.

Leave the switch off if your widget is publicly accessible. Otherwise, every question about the weather ends up with your team.

A Handed-Off Conversation Stays with the Human

Once handed off, no further question from the visitor triggers another handoff. The conversation belongs to your team until it is closed. If the visitor starts a new conversation, the bot is in charge again.

Best Practices

Set keywords conservatively — too many keywords = too many handoffs
Set Max Turns to 5 for the beginning, then adjust based on data
Use Confidence Threshold and Low-Confidence Handoff together
Check Resolution Analytics regularly to optimize handoff reasons
Enter Fallback Contacts if you have deactivated the offline form — otherwise, visitors see only the "please try again later" note when "no agent available". With a phone number or email, the visitor can immediately contact you from the widget.