Escalation

Some questions a bot shouldn't try to answer. Escalation rules let you detect those moments and route the conversation to a human, a system, or both.

The model#

An escalation rule has three parts:

• Trigger — when the rule fires. One of five types.
• Action — what happens when it fires. One of four types.
• Message — what the bot says to the visitor at that point.

Rules are evaluated in priority order. Higher priority wins; ties are stable in creation order.

Trigger types#

keyword#

Substring or regex match against the visitor's message.

1
2
3
4
5
6
7

{
  "trigger_type": "keyword",
  "trigger_config": {
    "keywords": ["refund", "chargeback", "billing error"],
    "match_mode": "substring"
  }
}

Cheapest trigger (runs before any model call), so good for high-confidence triggers like billing terms.

explicit#

Matches when the visitor explicitly asks for a human.

1

{ "trigger_type": "explicit" }

Detects phrasings like "talk to a person", "real human", "agent please". Multi-language; tuned per locale.

intent#

Classifies the visitor's message against intent labels you provide.

1
2
3
4
5
6
7

{
  "trigger_type": "intent",
  "trigger_config": {
    "intents": ["buying-intent", "cancellation-intent"],
    "threshold": 0.7
  }
}

Runs a small classifier model — fires before the main chat completion. Costs ~50 tokens per check.

sentiment#

Fires when the visitor's recent messages show sustained negative sentiment.

1
2
3
4
5
6
7

{
  "trigger_type": "sentiment",
  "trigger_config": {
    "threshold": -0.6,
    "window_messages": 3
  }
}

Useful as a safety net — if the visitor is getting frustrated, hand off before the experience deteriorates further.

confidence#

Fires when the bot's own response carries low confidence — typically because retrieved knowledge was thin or unrelated.

1
2
3
4
5
6
7

{
  "trigger_type": "confidence",
  "trigger_config": {
    "threshold": 0.5,
    "consecutive_low_turns": 2
  }
}

Evaluated after generation. The bot says its escalation message instead of the low-confidence response. Helps prevent confident-sounding hallucinations.

Action types#

email#

Sends a transcript and a "needs human attention" link to a fixed inbox.

1
2
3
4
5
6
7

{
  "action_type": "email",
  "action_config": {
    "to": "support@example.com",
    "subject_template": "[ScaiBot escalation] {bot_name} – {trigger_name}"
  }
}

webhook#

POSTs a JSON payload to your URL. Useful for piping into a CRM, helpdesk, or your own backend.

1
2
3
4
5
6
7
8

{
  "action_type": "webhook",
  "action_config": {
    "url": "https://your-crm.example.com/escalations",
    "headers": {"X-Source": "scaibot"},
    "signing_secret": "wh_secret_..."
  }
}

The webhook is signed (HMAC-SHA256 over the body, in X-ScaiBot-Signature). Verify it the same way you'd verify any ScaiGrid outbound webhook.

slack#

Posts a message into a Slack channel via an incoming webhook.

1
2
3
4
5
6
7

{
  "action_type": "slack",
  "action_config": {
    "webhook_url": "https://hooks.slack.com/services/...",
    "channel_override": "#support-escalations"
  }
}

scaiqueue#

Enqueues the conversation into a ScaiQueue topic for human-review workflows.

1
2
3
4
5
6
7

{
  "action_type": "scaiqueue",
  "action_config": {
    "topic": "human-review",
    "priority": 5
  }
}

ScaiQueue's typed message channels are the right fit when you want a UI for human reviewers to pick up escalations in order.

What the visitor sees#

The bot replies with the rule's message. The widget shows it as a regular assistant message but adds a subtle "escalated to support" badge underneath. Subsequent visitor messages on the same conversation still arrive — you decide on the human side whether to take over the chat (via a separate UI) or close it.

Patterns#

Cheap-first ordering. Put keyword and explicit rules at high priority; intent and sentiment at lower priority. You skip the expensive classifier and the model call entirely when the cheap rules match.

Confidence as a safety net. Add one confidence rule with a moderate threshold and a generic escalation message ("I'm not sure I have a good answer for this — let me get someone who can help.") at the lowest priority. It catches edge cases the other rules miss.

Sentiment with care. Sentiment classifiers misfire on irony, frustration about something else, and curt-but-not-hostile messages. Use a window of at least 2-3 messages and a strict threshold.

Webhook actions for everything else. When in doubt, use a webhook — it's the most flexible. Email and Slack are convenient defaults; ScaiQueue is for serious workflows.