> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thinnest.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sentiment Escalation

> Automatically detect negative caller sentiment and escalate to a human agent, notify a supervisor, or flag for review.

# 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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

```bash theme={null}
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"
  }'
```