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

# Sentiment Analysis & Escalation

> Detect frustrated users, hand off to humans, and act before conversations go sideways

<Info>
  **Plan availability:** Startup or higher for sentiment analysis. Escalation detection and human takeover require Standard or higher. See [Plans & Billing](/features/settings/plans).
</Info>

## Overview

The Analysis settings page brings together three related features that help you keep an eye on conversations and step in when it matters:

<CardGroup cols={3}>
  <Card title="Sentiment Analysis" icon="face-smile">
    Score each conversation and alert you when the mood turns negative.
  </Card>

  <Card title="Escalation Detection" icon="bell">
    Notice when a user explicitly asks for a human and trigger an alert.
  </Card>

  <Card title="Human Takeover" icon="user-headset">
    Let a teammate jump into the conversation and take over from the AI.
  </Card>
</CardGroup>

You'll find all of these under **Settings > Analysis** for the agent you want to configure.

## Sentiment Analysis

Clarky analyzes the tone of every conversation in the background and assigns a **sentiment score** from 0 (very negative) to 100 (very positive). When a conversation drops below the threshold you set, Clarky raises a **bad sentiment alert** so you can review what went wrong — or reach out before the user churns.

### Enabling Sentiment Analysis

<Steps>
  <Step title="Open Analysis settings">
    Go to **Settings > Analysis** for the agent you want to configure.
  </Step>

  <Step title="Toggle Sentiment Analysis on">
    Use the switch next to **Sentiment Analysis**. It's on by default for most agents.
  </Step>

  <Step title="Adjust the threshold">
    Drag the **Positive Sentiment Threshold** slider to set the score below which a conversation is flagged. The default is **60**, and the slider runs from 1 to 100.
  </Step>

  <Step title="Save your changes">
    Click **Save** at the bottom of the page once you're happy with the values.
  </Step>
</Steps>

### Choosing a Threshold

* **Lower values (around 30–50)** flag only clearly negative conversations. Good if you only want alerts for serious issues.
* **Default (60)** is a balanced starting point — flags conversations that are noticeably frustrated or unsatisfied.
* **Higher values (70–80)** flag anything that isn't clearly positive. Good for high-touch customer success teams who want to follow up on lukewarm conversations.

<Tip>
  You can reset the threshold to the default value of 60 at any time using the **Reset to default** button in the upper-right corner of the section.
</Tip>

### What Happens When a Conversation Is Flagged

When a conversation's sentiment score drops below your threshold:

* It's marked as a **bad sentiment** conversation in the inbox
* A notification can be sent to your team (configured in [Notifications](/features/settings/notifications))
* A `conversation.bad_sentiment` event fires, which can trigger a [webhook](/features/settings/webhooks)

## Escalation Detection

<Info>
  Escalation detection requires the **Standard** plan or higher.
</Info>

Even when an agent is doing its job well, some users specifically want to talk to a human. **Escalation Detection** watches conversations for those moments and raises an alert so a teammate can jump in.

### Enabling Escalation Detection

Toggle the **Escalation Detection** switch on. By default, Clarky uses its built-in rules to recognize phrases like "Can I talk to a human?" or "Is there an agent available?"

When triggered:

* The conversation is flagged in the inbox
* An `conversation.escalation_requested` event fires for [webhooks](/features/settings/webhooks)
* Notifications are sent according to your [Notifications](/features/settings/notifications) preferences

### Custom Detection Rules

If the default rules are too sensitive — or not sensitive enough — you can replace them with your own.

<Steps>
  <Step title="Toggle Custom Detection Rules">
    Inside the Escalation Detection section, switch on **Custom Detection Rules**. The text area pre-fills with Clarky's default rules so you have a starting point.
  </Step>

  <Step title="Edit the rules">
    Update the conditions to match how you want escalations to work. Be explicit — describe the kinds of phrases or situations that should and shouldn't count as a request for a human.
  </Step>

  <Step title="Save">
    Click **Save** to apply your custom rules.
  </Step>
</Steps>

<Tip>
  If you want to go back to the defaults, simply turn the **Custom Detection Rules** toggle off — Clarky will resume using the built-in rules.
</Tip>

### Timeout Message

When a user asks for a human and no teammate responds quickly, you can have Clarky send an automated reassurance message so the user isn't left hanging.

<Steps>
  <Step title="Enable Timeout Message">
    Inside the Escalation Detection section, toggle **Timeout Message** on.
  </Step>

  <Step title="Set the wait time">
    Choose how long Clarky should wait before sending the message. Allowed values are **1 to 10 minutes**.
  </Step>

  <Step title="Write the message">
    Enter the text the agent should send if no human joins in time. A common pattern:

    > I'm sorry we haven't responded yet. We have your contact information and someone will be in touch shortly.
  </Step>

  <Step title="Save">
    Click **Save**. The message is sent automatically as an assistant response when the wait time elapses without a human takeover.
  </Step>
</Steps>

<Note>
  If you clear the message field and save, the timeout feature is automatically disabled — there's no separate "off" state to manage.
</Note>

## Human Takeover

<Info>
  Human takeover requires the **Standard** plan or higher.
</Info>

**Human Takeover** allows a teammate to step into a live conversation and respond as a human, pausing the AI agent. It's the natural pairing for escalation detection — once you know a user wants a human, your team needs a way to step in.

### Enabling Human Takeover

In the Human Takeover section, toggle the **Human Takeover** switch on, then click **Save**.

When enabled:

* Teammates can take over any active conversation from the inbox
* The AI pauses while a human is actively responding
* The user sees messages from the human teammate in the same conversation thread
* Either the human can hand control back to the AI, or the conversation can simply end

<Tip>
  Pair Human Takeover with **Escalation Detection** and a **Timeout Message** for the smoothest workflow: Clarky catches escalation requests, alerts your team, sends a holding message if no one responds in time, and lets a teammate take over the moment they're available.
</Tip>

## Saving Changes

Changes on the Analysis page are batched. A **Save** button only appears when you have unsaved changes — once you click it, the new settings take effect immediately for new conversations.

<Card title="Webhooks for analysis events" icon="webhook" href="/features/settings/webhooks">
  Forward bad sentiment and escalation events to Slack, Zapier, or your own systems.
</Card>

<Card title="Notification preferences" icon="bell" href="/features/settings/notifications">
  Decide which alerts go to your inbox, mobile app, or browser.
</Card>

<Card title="Back to Settings" icon="gear" href="/features/settings/overview">
  Return to Settings overview
</Card>