Fini for escalation and human handoff

Fini escalates a conversation to your team when your rules say it should (Escalation Topics in the Planning Prompt, policy branches in Intent Rules, Guardrails) or when it can’t resolve the request (missing knowledge, a failed Action, or a customer who asks for a person), and it tags every escalation with a reason from a fixed taxonomy you can report on in Analytics. The handoff lands where your team already works: in the connected helpdesk for helpdesk conversations, as a ticket created by a Business Rule for widget conversations, or in Inbox native ticketing, with the transcript, customer attributes and the AI Steps trace available to the person who picks it up. Escalation is configured, not left to chance. You decide the triggers, the destination and what the customer is told, and you can audit every escalation afterwards.

What Fini handles and what it hands to your team

Fini handles	Your team handles
Deciding to escalate according to your Escalation Topics, rules and guardrails.	The conversation from the moment it’s escalated.
Telling the customer what happens next, in your wording.	Resolving the request, and any decision Fini isn’t allowed to make.
Creating the ticket in your helpdesk for widget escalations (Business Rules), or routing a native ticket to an Agent group.	Ticket ownership, queues and SLAs in your helpdesk or Inbox.
Marking the conversation’s status in the helpdesk so your views and automations can pick it up.	Feeding fixes back: knowledge gaps, missing Actions, rules that are too strict.
Staying silent once a human is assigned, if you configure it to.
Tagging the escalation reason for Analytics.

How Fini decides to escalate

Several layers can cause an escalation. Each one is configured separately, so you can fix the right layer when escalations land for the wrong reason.

Trigger	What it is	Where you configure it
Escalation Topics	Plain-language triggers in the Planning Prompt. The planner routes matching conversations to a human and skips knowledge search. Defaults cover legal or regulatory issues and persistent human requests (`agent_request_count >= 3`, `issue_repeat_count >= 3`); you add business-specific patterns.	Prompts
Customer asks for a person	Recorded as one of the two Customer requested human reasons, depending on whether it happened on the first message or after the agent tried.	Planning Prompt (how persistent a request must be)
Knowledge can’t answer	No content, conflicting content, or only partial content for the question.	Knowledge
An Action is missing or fails	The agent needed a system that isn’t connected, or the API call failed at runtime.	Actions
A rule’s policy path	A branch of an Intent Rule that, by your design, hands off instead of acting (for example a refund above your limit).	Intent Rules
Guardrails	A reply fails a check, the one rewrite also fails, and Fini replaces the reply with a handoff message and marks the conversation for escalation.	Guardrails

Whatever the trigger, the conversation’s Conversation Status becomes Escalated to Human Agent when the agent hands off or says the request was passed to a team that will follow up. That status drives the Inbox badge, the helpdesk status markers and Analytics.

To confirm (internal, remove before publish): Beyond a Reply that hands off (which Conversation Status tags as Escalated to Human Agent), is there a dedicated way for an Intent Rule to force an escalation, for example a specific node or Tool? If so, document it here and in the refunds and disputes pages.

Escalation reasons

Every escalated conversation is tagged with a reason from the Escalation Reason tag group. Analytics groups them into four families.

Family	Reason	Usually means	First fix to try
Knowledge	Missing Knowledge	No content covered the question.	Add an article or source; check Review for proposed articles.
Knowledge	Conflicting Knowledge	Two sources disagreed.	Pick the authoritative source and retire the other.
Knowledge	Partially Available	Some of the answer existed.	Complete the article, or add a rule for the partial case.
Action	Missing API Access	A needed system isn’t connected.	Build the Action.
Action	API or System Failure	An Action or integration call failed.	Read the Tool node in the AI Steps trace, then check the API.
User	Customer requested human (immediately)	The customer asked for a person on the first message.	Often unavoidable; spikes can point at the welcome message.
User	Customer requested human (after attempt)	The customer tried the agent, then asked for a person.	The most actionable reason. Read these conversations.
User	Ambiguous or Unclear Input	The agent couldn’t understand well enough to act.	Tighten intent gates, or add a clarifying-question branch.
Policy	Escalation Constraint	A policy in your Rulebook stopped the agent from acting.	Expected; audit if a category is unexpectedly high.
Policy	Guardrail or Safety Trigger	A safety check forced the handoff.	Expected; check for false positives.

The full definitions live in Analytics → Escalation reasons.

How the handoff works on each surface

Surface	Where the human picks it up	How Fini hands off	Configure
Helpdesk integrations (Zendesk, Intercom, Front, HubSpot, Salesforce, Gorgias, LiveChat)	The same ticket or conversation in your helpdesk.	Fini marks the conversation’s status in the helpdesk: tags such as `fini_escalated_human_agent` in Intercom, Front, Gorgias and LiveChat; conversation-status properties in HubSpot; a custom escalation ticket field in Zendesk; the Fini Transfer field in Salesforce. Your helpdesk views and assignment rules take it from there.	The integration’s page under Deploy
Widget, escalating into a helpdesk	A new ticket in Zendesk, Front, Salesforce, HubSpot or Gorgias.	A published Business Rule with source Widget and trigger On Escalation creates the ticket, can post a final message to the customer, and writes the external ticket ID or URL back to the conversation.	Rulebook → Business Rules
Widget and native email, handled in Fini	Inbox native ticketing.	The escalated conversation becomes a native ticket and is routed to an Agent group by tag (tags on the escalating turn first, then earlier conversation tags), then assigned by Round robin or Least loaded. A human reply pauses the agent.	Agent groups, Inbox
Slack	The Slack channel or DM.	The agent escalates to teammates when needed; Reply Rules decide whether it replies, leaves an internal note, or stays silent.	Slack
Voice	Your human phone queue.	The voice agent escalates to a human queue when needed; the call appears in Inbox with the same AI Steps trace. Inbound routing is set up with your Fini contact.	Voice in the agent sidebar, see Deploy

If no Business Rule applies to a widget escalation, no destination ticket is created by the Business Rules runtime. Every agent that serves the widget and escalates into a helpdesk needs an assigned, published Business Rule.

Start from a default template (Use Default Rule) when it matches your helpdesk. Use Create Custom when routing depends on who the customer is. The tree below is an example to adapt; the ticket-creation Tool is an Action you configure against your helpdesk’s API, and the field names are placeholders.

Steps  (Business Rule: Source Widget, Trigger On Escalation)
├── Fallback
│   ├── Steps  (priority lane)
│   │   ├── Check: plan Equals enterprise
│   │   └── Tool:  Create Helpdesk Ticket
│   │         in:  transcript, interaction_id, user_attributes,
│   │              priority = urgent, queue = priority_support
│   │         out: ticket_id, ticket_url
│   └── Tool:  Create Helpdesk Ticket
│         in:  transcript, interaction_id, user_attributes,
│              priority = normal, queue = general
│         out: ticket_id, ticket_url
└── Send Message: tell the customer a teammate has the conversation,
                  and share ticket_id

Map the transcript, interaction ID and attributes from the Business Rule context fields (Interaction History Transcript, Interaction ID, Formatted User Attributes), and use Test on the rule card before relying on it.

What context the human receives

The goal is that your teammate never has to ask the customer to repeat themselves.

Context	Where it comes from
The full conversation	The helpdesk thread itself, or Interaction History Transcript mapped into the ticket by a Business Rule.
Who the customer is	User Attributes, mapped with Formatted User Attributes in Business Rules, or visible on the conversation in Inbox.
A link back to the Fini conversation	Interaction ID in Business Rules; HubSpot support-form handoffs require Fini’s interaction ID property for this reason.
Files the customer uploaded	On Zendesk chat escalations from the widget, uploads are forwarded as native attachments when Zendesk accepts the file; the transcript includes download links as a fallback.
Why the agent escalated, and what it tried	The AI Steps trace in Inbox: planning, the rule that ran, Tool inputs and outputs, guardrail verdicts and the tags applied, including the escalation reason.
A triage note	Fini can post an internal note explaining why it escalated, visible to your team only.

To confirm (internal, remove before publish): On helpdesk integrations (not widget escalations), does Fini post a triage internal note summarizing the conversation and escalation reason by default, or only when configured? If configurable, where is it set?

Guardrails and escalation settings to configure

Goal	Configuration
Never talk over a human	No Reply with `Human Agent Assigned Equals True`; on Zendesk, add a group with `Escalated Conversation Equals True` (a documented example in Reply Rules).
Hand specific topics to people	Add them to Escalation Topics in the Planning Prompt. Be specific about the pattern: “escalate when the customer has explicitly asked for a human three or more times” works; “escalate frustrated customers” doesn’t.
Keep rule-backed topics with the rule	If a topic has an Intent Rule (cancel, refund, account update), let the rule handle it rather than listing the topic as an escalation trigger.
Draft but don’t send for sensitive intents	Internal Comment for the intent’s tag, so a human reviews and sends.
Say the right thing at handoff	Put exact escalation wording in Predefined Replies in Main Guidelines, and the widget’s final message in the Business Rule.
Stop unsafe replies	Guardrails. A failed check gets one rewrite; if that fails, the customer receives a handoff message and the conversation is marked for escalation.

How to tune escalation

Read the escalation reasons weekly. In Analytics, the escalation doughnut and the Escalation reason filter tell you which family dominates. Knowledge reasons are fixed in Knowledge, Action reasons in Actions, User reasons by reading conversations, Policy reasons by auditing your own rules.
Start with “after attempt”. Filter to the after-attempt Customer requested human reason and read ten conversations. These show where the agent was close but lost the customer.
Check which subsection fired. For an escalation you didn’t expect, open the conversation in Inbox and read the AI Steps panel, which shows the Planning Prompt reasoning. Edit the subsection responsible.
Audit guardrail escalations. In Guardrails, filter to Firing policies and review verdicts. A hit counts the initial failed check, including replies that were rewritten successfully, so hits are not the same as escalations.
Lock fixes in. Add the conversations you fixed to the Test Suite so a later change doesn’t bring the escalation back.

What to measure

Metric	Where	What it tells you
Human escalation rate	KPI card in Analytics	The share of conversations your team receives. Deflection rate is its complement and also counts conversations waiting on the customer.
AI resolution rate	Conversation Status doughnut, share Resolved by AI	The share the agent fully resolved, the counterpart to escalation.
Escalation reasons	Escalation doughnut and the Escalation reason filter	What to fix next, by family.
Escalated Rate per intent or rule	Intent rule breakdown and Knowledge performance tables	Which intents and knowledge areas leak to humans.
Hourly resolution	Hourly breakdown (ranges up to 31 days)	Hours where resolution rate falls off, often a staffing or routing gap.
CSAT	Average CSAT, with the Conversation status filter set to Escalated to Human Team	Whether escalated customers end satisfied.

Business Rules

Widget escalation templates, custom escalation trees, field mapping and testing.

Cancellation flow

Walkthrough that pairs an Intent Rule with an Internal Comment review gate for VIP customers.

Prompts

Escalation Topics in the Planning Prompt and Predefined Replies.

Agent groups

Route native tickets to human teams by tag, availability and workload.

Reply Rules

No Reply, Internal Comment and Direct Reply conditions.

Analytics

Escalation reasons, escalation rate and resolution by intent.

Use cases

Walkthroughs

Industry setup

How-tos

Fini for escalation and human handoff

What Fini handles and what it hands to your team

How Fini decides to escalate

Escalation reasons

How the handoff works on each surface

Example widget escalation Business Rule

What context the human receives

Guardrails and escalation settings to configure

How to tune escalation

What to measure

Business Rules

Cancellation flow

Prompts

Agent groups

Reply Rules

Analytics

​What Fini handles and what it hands to your team

​How Fini decides to escalate

​Escalation reasons

​How the handoff works on each surface

​Example widget escalation Business Rule

​What context the human receives

​Guardrails and escalation settings to configure

​How to tune escalation

​What to measure

​Related

Business Rules

Cancellation flow

Prompts

Agent groups

Reply Rules

Analytics

What Fini handles and what it hands to your team

How Fini decides to escalate

Escalation reasons

How the handoff works on each surface

Example widget escalation Business Rule

What context the human receives

Guardrails and escalation settings to configure

How to tune escalation

What to measure

Related