> For the complete documentation index, see [llms.txt](https://help.usejimo.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.usejimo.com/docs/experiences/agent/escalation.md).

# Escalation

Hand a conversation over to your support team when the Agent cannot help, inside the tool your team already uses.

**Dashboard path:** [Agent > Train > Escalation](https://i.usejimo.com/agent/escalation) (`/agent/escalation`)

***

## What is Escalation?

Escalation is the Agent's exit door. When a user asks for a person, tells the Agent its answer is wrong, or gets frustrated, the Agent stops trying and hands the conversation to your support tool. You choose the tool, the moments that trigger the hand-off, and the topics that should never be handled by the Agent at all.

<figure><img src="https://2794860263-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKzAcDWQbK1gKbpra7bkb%2Fuploads%2FoJ1HA3cSNA1XZqEAHKW2%2F02-escalation-flow.svg?alt=media&amp;token=ef96220f-58b8-4628-919e-ac250d533749" alt=""><figcaption></figcaption></figure>

Without Escalation, the only fallback is a sentence in your General Instructions such as "contact support at ...". With Escalation, the hand-off happens inside the chat, with the conversation attached.

<figure><img src="https://2794860263-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKzAcDWQbK1gKbpra7bkb%2Fuploads%2FGIImvs7AaeRmiET6npXJ%2Fimage.png?alt=media&amp;token=714894b1-b532-450b-9887-1480b2cec9b5" alt=""><figcaption></figcaption></figure>

***

## Overview

* **Four destinations:** Intercom, Zendesk, Crisp Chat, or a plain support email.
* **Three built-in triggers:** explicit request, repeated "it didn't work", detected frustration. Each one can be switched on or off.
* **Topics that skip the Agent:** keywords or questions that go straight to support, for example anything about billing or account deletion.
* **Context travels with the user:** a summary of the conversation, the reason for the hand-off and, depending on the tool, the page and the topic are passed to your support tool. Every hand-off is tagged `jimo-handoff` and `jimo-reason-<reason>`, so your team can route it. See the tags and metadata reference below.
* **Escalation analytics:** the number of hand-offs performed, so you can see how often the Agent reaches its limit. Individual conversations are not flagged as escalated in [Analyze](/docs/experiences/agent/analyze.md); use the tags in your support tool to find them.

***

## Use Cases

* 🙋 **Let users reach a human on demand.** A user types "I want to talk to someone": the Agent hands over immediately, whatever the wording.
* 🔁 **Stop the loop.** After the user says twice that the answer did not work, the Agent stops guessing and escalates.
* ⚠️ **Catch frustration early.** A negative tone triggers the hand-off before the user gives up on the chat.
* 🔒 **Keep all three on to start.** After a week, compare the escalation count with the volume of conversations, and read the hand-offs in your support tool (filter on the `jimo-handoff` tag), then loosen or tighten the thresholds.

***

## How to Access

1. **Open the Escalation page:** in the dashboard, go to **Agent > Train > Escalation**. Until a destination is connected, the page shows the **Enable escalation** button. <br>

   <figure><img src="https://2794860263-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKzAcDWQbK1gKbpra7bkb%2Fuploads%2Fk70rm6nHtNU1w52QHdLM%2Fimage.png?alt=media&amp;token=c6a63b61-a07e-481b-ad81-87ad55b69325" alt=""><figcaption></figcaption></figure>
2. **Pick a destination:** click **Enable escalation** and choose **Connect Intercom**, **Connect Zendesk**, **Connect Crisp Chat**, or **Add Support Email**. <br>

   <figure><img src="https://2794860263-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKzAcDWQbK1gKbpra7bkb%2Fuploads%2FB7I4Y7z7LtEppjcJ1c9J%2Fimage.png?alt=media&amp;token=405af4db-c499-4cda-a71a-7885dc2e69b0" alt=""><figcaption></figcaption></figure>
3. **Fill in the connection form** for the tool you picked (details below), then click **Connect and test**. You can also click **Skip for now** to set up triggers first and connect the tool later.&#x20;

   <br>

   <figure><img src="https://2794860263-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKzAcDWQbK1gKbpra7bkb%2Fuploads%2F5UTuK0BpNNxokqO8FYBf%2Fimage.png?alt=media&amp;token=b79dfec8-2205-4098-a517-2980510d5c96" alt="" width="563"><figcaption></figcaption></figure>
4. **Configure triggers and topics:** once a destination exists, the page shows **Escalation Triggers** and **Topics that goes directly to support**. The **Configure** button (top-right) reopens the connection settings. \ <br>

   <figure><img src="https://2794860263-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKzAcDWQbK1gKbpra7bkb%2Fuploads%2FpJFwx8ydFUjtW29ZCnnc%2Fimage.png?alt=media&amp;token=d3a4acd8-ee3f-4a08-92ca-e60d20474021" alt=""><figcaption></figcaption></figure>

***

## Main Features

### Destinations

One destination at a time. The **Escalation Support Tool** selector in the Configuration modal is where you pick it or switch to another one; switching does not touch your triggers and topics.

{% tabs %}
{% tab title="Intercom" %}
**Setup:** OAuth. Clicking **Connect Intercom** opens the Intercom sign-in page. Log in with an Intercom admin account (Google, email and password, or SAML SSO), check the **account region** at the top of the form, and authorize Jimo.&#x20;

<figure><img src="https://2794860263-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKzAcDWQbK1gKbpra7bkb%2Fuploads%2FJK3aQiSF0x7i91UywT9k%2Fimage.png?alt=media&amp;token=db2ed2b4-8b7b-4e4c-bd5e-3a4252d41f0f" alt="" width="371"><figcaption></figcaption></figure>

**What your team receives:** a new conversation in Intercom, created as the user with the conversation summary as its body. Once it exists, Jimo adds an admin-only note (HTML) and two tags: `jimo-handoff` and `jimo-reason-<reason>`. Users identified in Jimo are matched to their Intercom contact.

**Where the user continues:** in your Intercom Messenger. The widget opens the conversation Jimo created; if that creation fails, the widget starts a plain conversation with the summary only, without note or tags.

{% hint style="info" %}
Intercom receives the summary, the note and the tags. It does not receive the page URL, the user's language, or a Jimo conversation id: there are no custom attributes on the Intercom side. Use the tags for routing and the note for context.
{% endhint %}

{% hint style="info" %}
The Intercom sign-in page asks for the account region (US, EU, AU). Pick the region of your Intercom workspace.
{% endhint %}
{% endtab %}

{% tab title="Zendesk" %}
**Setup:** none. Select **Connect Zendesk** and Zendesk becomes the destination immediately. A confirmation reads "Zendesk is already your destination: hand-offs need no setup".&#x20;

<figure><img src="https://2794860263-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKzAcDWQbK1gKbpra7bkb%2Fuploads%2F8p82V2mukphu89v8NIaU%2Fimage.png?alt=media&amp;token=560d7216-aabf-42b3-8210-be40832c55ed" alt=""><figcaption></figcaption></figure>

**What your team receives:** the conversation continues in your Zendesk messaging widget. Before the first message, the widget sets two tags on it, `jimo-handoff` and `jimo-reason-<reason>`.&#x20;

If you have mapped ticket field ids in your Zendesk setup, Jimo also writes the page URL, the raw reason and the topic into those fields.&#x20;

The conversation carries machine-only metadata as well (`jimo_handoff`, `jimo_reason`, `jimo_topic`, `jimo_source_path`, `jimo_language`, `jimo_conversation_id`) that never shows in the agent workspace but is available to your triggers and integrations.

**Where the user continues:** in the Zendesk widget on your page.

{% hint style="warning" %}
The private note is not reliable on Zendesk yet. It can only be written once the ticket has left Zendesk's own AI agent, and that step is currently disabled, so the note often never lands. Rely on the tags and, if you mapped them, the ticket fields.
{% endhint %}
{% endtab %}

{% tab title="Crisp Chat" %}
**Setup:** two levels. Selecting **Connect Crisp Chat** is enough for hand-offs to work. Adding an API token unlocks a **private note** on each hand-off, with the conversation, the page and the topic, so your operators start with context.

1. In Crisp, go to **Settings > Workspace settings > Advanced configuration > API token** and create a token with the **conversation messages** and **sessions** scopes. This is the workspace token: a marketplace plugin token from marketplace.crisp.chat will not work.
2. Back in Jimo, paste your **Website ID**, **Token identifier** and **Token key**.
3. Click **Connect and test**. Jimo checks the token and confirms. **Skip for now** keeps Crisp as the destination without the private notes; you can add the token later from **Configure**.&#x20;

<figure><img src="https://2794860263-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKzAcDWQbK1gKbpra7bkb%2Fuploads%2F6tfaXAoj7bNOu3olWOXh%2Fimage.png?alt=media&amp;token=ae3e2c8c-9396-4e70-bd08-b682780e1d97" alt=""><figcaption></figcaption></figure>

**What your team receives:** a thread titled "Jimo AI escalation" (or "Jimo AI escalation, ") opened as the visitor, with the conversation summary as the first message.&#x20;

Before the message, the widget fills the visitor data shown in the Crisp sidebar: `jimo_handoff` (true), `jimo_reason` (a readable label such as "Asked for a human"), `jimo_topic`, `jimo_page` (origin and path), `jimo_language`. The visitor also gets the `jimo-handoff` segment.

With the API token connected, Jimo adds a note from "Jimo AI" with a clickable link to the page, sets the inbox subject to ", escalated from the AI assistant", merges the same sidebar keys (except language) from the backend, and adds the reason as a second segment, hyphenated (for example `jimo-asked-for-human`).

**Where the user continues:** in your Crisp chatbox.
{% endtab %}

{% tab title="Support Email" %}
**Setup:** one field. Select **Add Support Email**, enter your team's address in **Support email** (for example <support@yourcompany.com>), then click **Enable escalation**.&#x20;

<figure><img src="https://2794860263-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKzAcDWQbK1gKbpra7bkb%2Fuploads%2FjYYzXqmQxebYgMiwdMga%2Fimage.png?alt=media&amp;token=1c0b6bae-e022-4dc5-9050-58f4145190a6" alt=""><figcaption></figcaption></figure>

**What your team receives:** an email at the address you set.&#x20;

Nothing opens in a chat tool.&#x20;

The email contains: the reason for the hand-off and whether the chat auto-opened or showed a card, the time (Paris timezone), the support address, the user's first message (redacted), the topic, the number of failed answers, the frustration level, a short brief (redacted), the user's id, name and email with a link to their Jimo profile, the account name, the page path and URL with browser and OS, a link to your Jimo settings, and the redacted transcript when enabled.&#x20;

Plan, seats and avatar are not sent.

**Where the user continues:** the chat confirms that the request was sent to the support team; the follow-up happens by email.

To change the address later, open **Configure** and click **Change support email**.&#x20;

<figure><img src="https://2794860263-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKzAcDWQbK1gKbpra7bkb%2Fuploads%2Fvo1ldPA1utf5VqFavfM9%2Fimage.png?alt=media&amp;token=14dd0b6c-e8b6-4a57-831c-d7419e0f43cd" alt=""><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}

|                                                 | Intercom           | Zendesk                                      | Crisp Chat                                                        | Support Email                       |
| ----------------------------------------------- | ------------------ | -------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------- |
| **Setup**                                       | OAuth sign-in      | None                                         | Optional API token                                                | One email address                   |
| **Conversation continues in**                   | Intercom Messenger | Zendesk widget                               | Crisp chatbox                                                     | Email, nothing opens in a chat tool |
| **Tags** `jimo-handoff`, `jimo-reason-<reason>` | Yes                | Yes                                          | Segment `jimo-handoff`, reason as a second segment with the token | Not applicable                      |
| **Summary of the conversation**                 | Conversation body  | First message                                | First message                                                     | In the email                        |
| **Note for your agents**                        | Admin-only note    | Rarely lands (see tab)                       | With the API token                                                | Not applicable                      |
| **Page URL**                                    | No                 | Ticket field, if mapped                      | Sidebar `jimo_page`                                               | Yes                                 |
| **Topic**                                       | In the note        | Ticket field, if mapped, and hidden metadata | Sidebar `jimo_topic`, inbox subject with the token                | Yes                                 |
| **User language**                               | No                 | Hidden metadata                              | Sidebar `jimo_language`                                           | Not sent as such                    |

#### Tags and metadata reference

Every hand-off carries a reason, one of four values. It is the second part of the `jimo-reason-<reason>` tag on Intercom and Zendesk, and the readable label in the Crisp sidebar.

| Reason            | Fires when                                                                                   | Crisp label                     |
| ----------------- | -------------------------------------------------------------------------------------------- | ------------------------------- |
| `asked_for_human` | The user asked for a person (trigger "On explicit request")                                  | Asked for a human               |
| `agent_stuck`     | The user said the answer did not work, twice by default (trigger "User says it didn't work") | The AI could not resolve it     |
| `frustration`     | The user's tone degraded (trigger "User shows a clear frustration")                          | The user was getting frustrated |
| `topic_rule`      | The message matched one of your "topics that go directly to support"                         | Matched a topic rule            |

Use the tags to route hand-offs in your support tool: a view or an automation on `jimo-handoff` catches everything the Agent sends you, and `jimo-reason-topic_rule` isolates the topics you chose to keep human.

### Configuration modal

<figure><img src="https://2794860263-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKzAcDWQbK1gKbpra7bkb%2Fuploads%2FXy3aZUUJ0D1Mw2oWYSAT%2Fimage.png?alt=media&amp;token=4c19f9b2-f562-4613-8d00-7b107b207d16" alt=""><figcaption></figcaption></figure>

Open it with **Configure** (top-right). Two settings:

* **Enable Escalation**: master switch. Off, the Agent never hands over, whatever the triggers say. Your destination and rules are kept.
* **Escalation Support Tool**: the active destination. Change it from the dropdown; the tool-specific settings (Crisp token, support email) show underneath.

<figure><img src="https://2794860263-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKzAcDWQbK1gKbpra7bkb%2Fuploads%2Fcnu2PQIVENhryDa0iI9q%2Fimage.png?alt=media&amp;token=fc1175dc-6e7a-46b2-8922-a42f0eefba29" alt=""><figcaption></figcaption></figure>

### Escalation Triggers

Three moments when the Agent hands over. Tick or untick each card.

| Trigger                            | Behaviour                                                                                                                           |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **On explicit request**            | Escalates as soon as the user asks for a person, however they word it. On by default.                                               |
| **User says it didn't work**       | Escalates after 1, 2 or 3 failed answers in a row (default **2**). Click the chip to change the count.                              |
| **User shows a clear frustration** | Escalates when the user's tone degrades. Sensitivity: **subtle**, **slight** (default) or **furious**. Click the chip to change it. |

<figure><img src="https://2794860263-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKzAcDWQbK1gKbpra7bkb%2Fuploads%2Fc7EIcNrfNnCzD6SJTT1Q%2Fimage.png?alt=media&amp;token=1f7d6a8b-0bf3-4d9e-a97a-b00cbdf7b430" alt=""><figcaption></figcaption></figure>

Two more hand-offs happen without a trigger card: a message that matches one of your topics (below), and the Agent's own judgement that it is stuck on a task it cannot finish.

{% hint style="info" %}
Escalation only works when your support tool's chat is loaded on the page (Intercom Messenger, Zendesk widget or Crisp chatbox), or with Support Email, which needs nothing on the page.
{% endhint %}

> **Tip:** keep all three on to start. Review the escalated conversations in Analyze after a week, then loosen or tighten the thresholds.

### Topics that go directly to support

Specific topics or keywords the Agent must never handle. When a user's message matches one, the Agent escalates without attempting an answer.

* Click **+ Add topic** and type a keyword or a full question, for example "How can I change my password?".
* Remove a topic with the **x** on its chip.
* Up to 20 topics per project.

<figure><img src="https://2794860263-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKzAcDWQbK1gKbpra7bkb%2Fuploads%2FO9gE4hQTnK3XfP3RsBhA%2Fimage.png?alt=media&amp;token=cc5aef61-e954-495a-aa66-1aebac2a4eba" alt=""><figcaption></figcaption></figure>

Use this for anything that needs a human decision or touches sensitive data: billing, refunds, account deletion, legal questions.

### What the user sees

When a trigger fires, the Agent posts a hand-off message in the chat with a button to continue with the support team.&#x20;

The user stays in the same window: with Intercom, Zendesk or Crisp the conversation opens in that tool's widget, with the summary already posted. With Support Email nothing opens: the user gets a confirmation that the request has been sent, and your team follows up by email.

<div><figure><img src="https://2794860263-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKzAcDWQbK1gKbpra7bkb%2Fuploads%2FBvE2L0mic5pG4l6DQZcI%2Fimage.png?alt=media&amp;token=6e1c8707-1698-4f92-b9df-c10ded370be1" alt="" width="423"><figcaption></figcaption></figure> <figure><img src="https://2794860263-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKzAcDWQbK1gKbpra7bkb%2Fuploads%2FAxI2P0HIuvVAryd5jHzv%2Fimage.png?alt=media&amp;token=f9317923-96d5-4168-91ec-c5e6d9d986b6" alt="" width="431"><figcaption></figcaption></figure> <figure><img src="https://2794860263-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKzAcDWQbK1gKbpra7bkb%2Fuploads%2FnhmKT8bqApN9kbINn5Rv%2Fimage.png?alt=media&amp;token=0293c845-cad0-4e5e-9ea0-896ac20cc364" alt="" width="419"><figcaption></figcaption></figure> <figure><img src="https://2794860263-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKzAcDWQbK1gKbpra7bkb%2Fuploads%2FsvNXqSdlDTEorPW1jqlo%2Fimage.png?alt=media&amp;token=0735949d-ddb6-4b4e-a6e3-a2456f5a287d" alt=""><figcaption></figcaption></figure></div>

***

## Best Practices

* **Set the destination before going live.** Triggers do nothing while **Enable Escalation** is off or no support tool is selected.
* **Remove the old fallback from your instructions.** If your General Instructions still say "tell the user to email support", delete it so the Agent uses the hand-off instead. See [Chat](/docs/experiences/agent/chat.md).
* **Start the topic list from your tickets.** The questions your team refuses to automate are your first topics.
* **Watch the hand-offs in your support tool.** Filter on `jimo-handoff` and read the reasons: a topic that keeps escalating with `topic_rule` is a deliberate choice, one that escalates with `agent_stuck` is a missing Skill or a missing source. See [Skills](/docs/experiences/agent/skills.md) and [Knowledge](/docs/experiences/agent/knowledge.md).

***

## Related pages

* [Agent overview](/docs/experiences/agent.md)
* [Chat](/docs/experiences/agent/chat.md): General Instructions and the chat widget.
* [Launcher](/docs/experiences/agent/launcher.md): where the Agent is available to your users.
* [Analyze](/docs/experiences/agent/analyze.md): statistics and conversation history.