🚨 Escalation Rules

Define precisely when and how conversations should be escalated from the AI bot to a human team member. Escalation rules ensure that high-stakes conversations — complaints, VIP customers, purchase opportunities — always reach the right person.

---

How Escalation Works

When a conversation matches an escalation rule, ICE:

1. Creates an Escalation record with priority, reason, and AI-generated context
2. Updates the thread status to ESCALATED
3. Assigns it to the designated team member or role
4. Notifies the assignee (and optionally other roles)
5. Optionally triggers a workflow for advanced automation

The AI also provides a suggested reply so the human agent can respond faster.

---

Escalation Rule Structure

Each rule is defined with the following fields:

Field	Description
name	Human-readable rule name (e.g., "VIP Complaint Handler")
isActive	Whether the rule is currently enabled
priority	LOW, MEDIUM, HIGH, or CRITICAL
conditions	JSON array of conditions that trigger this rule (see below)
assignToRole	Role to assign escalated threads to (e.g., ADMIN)
assignToUserId	Specific team member to assign to (overrides role)
notifyRoles	Additional roles to notify (e.g., ["OWNER", "ADMIN"])
addCrmTags	Tags automatically applied to the thread upon escalation
triggerWorkflow	Whether to trigger an automation workflow
workflowId	The specific workflow to execute

---

Default Escalation Triggers

Out of the box, UniPulse includes sensible defaults that you can customize:

Trigger	Condition	Default Priority
Negative sentiment	Thread sentiment is negative with high confidence	HIGH
Purchase intent	purchaseIntentScore above threshold	MEDIUM
Complaint / refund request	Intent classified as complaint or refund	HIGH
Low AI confidence	confidenceScore below the configured maxConfidenceForAuto	MEDIUM
Human requested	Customer explicitly asks to speak to a person	HIGH
VIP customer	Customer's audience tier is VIP or engagement score is in top percentile	CRITICAL
Escalation keywords	Message contains any keyword from escalateKeywords list in Bot Config	HIGH

---

Creating Custom Rules

Navigate to Settings > Conversations > Escalation or use the API (CRUD /ice/escalation-rules):

1. Name your rule — Give it a clear, descriptive name
2. Set conditions — Define one or more conditions in JSON format. Conditions can match on:
   • sentiment (positive / neutral / negative)
   • urgency (LOW / MEDIUM / HIGH / CRITICAL)
   • intent (question, complaint, purchase, refund, etc.)
   • confidenceScore (numeric threshold)
   • purchaseIntentScore (numeric threshold)
   • channelType (specific platform or channel)
   • messageCount (threads with many back-and-forth messages)
   • crmTags (presence of specific tags)
   • audienceSegment or audienceTier (from the Audience Graph)
3. Set priority — LOW, MEDIUM, HIGH, or CRITICAL
4. Assign — Pick a team member or role
5. Configure notifications — Choose which additional roles get alerted
6. Add tags — Automatically tag escalated threads for tracking
7. Link a workflow — Optionally trigger an automation workflow on escalation

tip

Rules are evaluated in priority order. If multiple rules match, the highest-priority rule wins. Use this to create layered escalation strategies.

---

Escalation Records

When a rule fires, an Escalation record is created:

Field	Description
priority	LOW, MEDIUM, HIGH, or CRITICAL
status	OPEN_ESCALATION → ASSIGNED → IN_PROGRESS → RESOLVED_ESCALATION or DISMISSED
reason	Why this escalation was triggered (rule name + matched condition)
aiSummary	AI-generated summary of the conversation so the agent has instant context
suggestedReply	AI-drafted reply the agent can use or edit
assignedTo	The team member handling this escalation

Escalation Lifecycle

OPEN_ESCALATION → ASSIGNED → IN_PROGRESS → RESOLVED_ESCALATION
                                          → DISMISSED

---

Escalation Queue

Escalated conversations appear in a dedicated queue accessible from Conversations > Escalations:

• Priority indicators — Color-coded urgency badges (🔴 Critical, 🟠 High, 🟡 Medium, 🔵 Low)
• AI summary — One-paragraph summary so agents don't need to read the full thread
• Suggested reply — Ready-to-send AI draft
• Full conversation history — Complete thread with all messages and decision logs
• Assignment controls — Reassign to another member or role
• Quick actions — Resolve or dismiss directly from the queue

---

API Endpoints

Method	Endpoint	Purpose
GET	/ice/escalation-rules	List all escalation rules
POST	/ice/escalation-rules	Create a new rule
PUT	/ice/escalation-rules/:id	Update an existing rule
DELETE	/ice/escalation-rules/:id	Delete a rule
GET	/ice/escalations	List all escalation records
PUT	/ice/escalations/:id/assign	Assign an escalation to a team member
PUT	/ice/escalations/:id/resolve	Resolve an escalation

---

Related Pages

• Unified Inbox — Where escalated threads live alongside all other conversations
• AI Auto-Reply — Configure the bot behavior that feeds into escalation
• Roles & Permissions — Understand which roles can be assigned to escalations
• Segments & Scoring — Use audience segments as escalation conditions