Skip to main content

​
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"
}
SettingTypeDefaultDescription
sentimentEscalationEnabledbooleanfalseEnable sentiment monitoring
sentimentThresholdinteger3Sentiment score (1-10) that triggers escalation
sentimentWindowTurnsinteger3Consecutive negative turns before escalating
sentimentEscalationActionstringflagAction: transfer, notify, or flag
sentimentEscalationTargetstring—Phone number for transfer action
sentimentNotifyWebhookstring—Webhook URL for notify action

​
Escalation Actions

ActionBehavior
transferTransfer the call to the configured phone number via SIP
notifySend a webhook alert to your supervisor dashboard
flagSave 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"
  }'