Sentiment Escalation

The Sentiment Escalation tool monitors the caller’s emotional state throughout the call. When the caller becomes frustrated, angry, or upset for multiple consecutive turns, the agent automatically escalates — transferring to a human, notifying a supervisor, or flagging the call.

How It Works

Caller: "This is ridiculous, I've been trying to fix this for three days!"
Caller: "Nobody at your company seems to care."
Caller: "I want to speak to someone who can actually help."
-> Agent detects sustained negative sentiment
-> Triggers escalate_sentiment tool
-> "I completely understand your frustration. Let me connect you with a supervisor who can help resolve this right away."

The agent continuously rates sentiment on a 1-10 scale. When the score drops below your configured threshold for a set number of consecutive turns, escalation triggers.

Configuration

{
  "sentimentEscalationEnabled": true,
  "sentimentThreshold": 3,
  "sentimentWindowTurns": 3,
  "sentimentEscalationAction": "transfer",
  "sentimentEscalationTarget": "+14155551234",
  "sentimentNotifyWebhook": "https://your-app.com/webhooks/sentiment"
}

Setting	Type	Default	Description
`sentimentEscalationEnabled`	boolean	`false`	Enable sentiment monitoring
`sentimentThreshold`	integer	`3`	Sentiment score (1-10) that triggers escalation
`sentimentWindowTurns`	integer	`3`	Consecutive negative turns before escalating
`sentimentEscalationAction`	string	`flag`	Action: `transfer`, `notify`, or `flag`
`sentimentEscalationTarget`	string	—	Phone number for transfer action
`sentimentNotifyWebhook`	string	—	Webhook URL for notify action

Escalation Actions

Action	Behavior
`transfer`	Transfer the call to the configured phone number via SIP
`notify`	Send a webhook alert to your supervisor dashboard
`flag`	Save sentiment alert to the session for post-call review

LLM Tool

Tool name: escalate_sentiment The agent calls this tool when it detects sustained negative sentiment:

Parameters:
  sentiment_score: integer (1-10, where 1 = extremely negative)
  description: string (brief description of what upset the caller)

Webhook Payload

When using the notify action, the webhook receives:

{
  "event": "sentiment.alert",
  "room_name": "room_abc123",
  "sentiment_score": 2,
  "description": "Caller frustrated about unresolved billing issue for 3 days",
  "action": "notify"
}

Example — Create Agent with Sentiment Escalation

curl -X POST https://api.thinnest.ai/v1/agents \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent with Escalation",
    "model": "gpt-4o",
    "instructions": "You are a customer support agent. Monitor the caller emotional state. If they become frustrated for multiple turns, acknowledge their feelings empathetically before escalating.",
    "voiceEnabled": true,
    "transcriber": { "provider": "deepgram", "model": "nova-2-conversationalai" },
    "voice": { "provider": "deepgram", "voiceId": "aura-2-thalia-en" },
    "sentimentEscalationEnabled": true,
    "sentimentThreshold": 3,
    "sentimentWindowTurns": 3,
    "sentimentEscalationAction": "transfer",
    "sentimentEscalationTarget": "+14155551234"
  }'

Introduction

Getting Started

Voice Agents

Agent Capabilities

Channels

Quality & Oversight

Platform

Sentiment Escalation

Sentiment Escalation

How It Works

Configuration

Escalation Actions

LLM Tool

Webhook Payload

Example — Create Agent with Sentiment Escalation

​Sentiment Escalation

​How It Works

​Configuration

​Escalation Actions

​LLM Tool

​Webhook Payload

​Example — Create Agent with Sentiment Escalation

Sentiment Escalation

How It Works

Configuration

Escalation Actions

LLM Tool

Webhook Payload

Example — Create Agent with Sentiment Escalation