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

# Hand off AI agent conversations to a human

> Let your AI agent hand a conversation to a human by creating a ticket in Chatbase Helpdesk or your connected helpdesk platform

The **Escalations** Action lets your Chatbase AI agent hand a conversation to a human by creating a support ticket. The ticket goes to the Chatbase Helpdesk or to a connected platform such as Zendesk, Salesforce, Intercom, or Freshdesk, with the customer's details and the conversation, so your team can pick up where the AI agent left off. With Chatbase Helpdesk, Escalations work on every channel except Slack, including the Chat Bubble, Help Page, WhatsApp, Instagram, Messenger, and email. Zendesk Messaging needs Zendesk as the ticket platform, and third-party platforms other than Zendesk can't be used on Slack, WhatsApp, Messenger, Instagram, or Zendesk Messaging.

> [card] Best for:
>
> Issues the AI agent can't resolve and that don't need an answer this second: anything your team can work as a ticket and follow up on.

**Common Use Cases:**

* "I want to speak to a human"
* "Connect me to support"
* "This didn't solve my issue"
* "I need help with my billing"

![The Escalations Action in the Chatbase dashboard](https://mintcdn.com/chatbase/wVAg3bVLww8ng0oL/images/image-1.png?fit=max\&auto=format\&n=wVAg3bVLww8ng0oL\&q=85\&s=5cc7ebcf008c7b877ca9ca9e86dae143)

> [!NOTE]
>
> Escalations open a ticket for asynchronous follow-up. If you'd rather route the customer to a human in real time, use [Chatbase live chat](https://chatbase.co/docs/user-guides/chatbot/actions/chatbase-live-chat.md) instead.

## Before you start

The Action can only create tickets in a platform you have already set up. Only connected platforms appear in the **Ticket Platform** dropdown when you create the Action.

* To use **Chatbase Helpdesk**, click **Helpdesk inbox** in the sidebar and enable it from there.
* To use a third-party platform, go to **Integrations** in the sidebar and connect it.

Supported platforms:

* [Chatbase Helpdesk](https://chatbase.co/docs/user-guides/chatbot/help-desk/help-desk-overview.md)
* [Zendesk](https://chatbase.co/docs/user-guides/integrations/zendesk.md)
* [Salesforce](https://chatbase.co/docs/user-guides/integrations/salesforce.md)
* [Intercom](https://chatbase.co/docs/user-guides/integrations/intercom.md)
* [Zoho Desk](https://chatbase.co/docs/user-guides/integrations/zohodesk.md)
* [Freshdesk](https://chatbase.co/docs/user-guides/integrations/freshdesk.md)
* [HubSpot](https://chatbase.co/docs/user-guides/integrations/hubspot.md)
* [Help Scout](https://chatbase.co/docs/user-guides/integrations/helpscout.md)
* [Gorgias](https://chatbase.co/docs/user-guides/integrations/gorgias.md)
* [Odoo](https://chatbase.co/docs/user-guides/integrations/odoo.md)

## How to create the Action

**1. Navigate to Actions**

Go to your [Chatbase dashboard](https://www.chatbase.co/dashboard/) and select your AI agent. Click **Build > Actions** in the left sidebar.

**2. Create the Action**

Click **Create Action**, then select **Create ticket** under **Escalations**.

**3. Configure General Settings**

**Action name:** A descriptive name that helps the AI agent understand when to trigger the Action, such as `create_ticket`, `create_ticket_refunds`, or `create_ticket_whatsapp`.

**Ticket Platform:** The platform where tickets are created. The options in the next section depend on this choice.

**When to use:** Explain clearly when the AI agent should create a ticket. The field comes prefilled with a default you can edit, and **Reset** restores it:

```text theme={null}
Create a ticket when:
1. The user explicitly asks to submit a complaint or requests support from a human.
2. The user asks a question you don't know the answer to, but confirm before creating the ticket.
```

To restrict the Action to [Procedure](https://chatbase.co/docs/user-guides/chatbot/procedures/procedures-overview.md) steps only, turn on [**Only use in Procedures**](https://chatbase.co/docs/user-guides/chatbot/actions/actions-overview.md#only-use-in-procedures). When it's on, the **When to use** field is hidden, because the AI agent no longer decides when to call the Action.

**4. Configure details collection**

This section changes based on the ticket platform you picked. See [Details collection by platform](#details-collection-by-platform) below.

**5. Add Tags**

With **Chatbase** as the ticket platform, the **Tags** section lets the AI agent tag each ticket it creates. See [Tags](#tags) below, or click **Skip** to leave it empty.

**6. Choose Channels**

With **Chatbase** as the ticket platform, this Action is compatible with every channel except **Slack**. **Zendesk Messaging** is compatible only when the ticket platform is **Zendesk**. With any other third-party platform, such as Salesforce, Intercom, or Freshdesk, **Slack**, **WhatsApp**, **Messenger**, **Instagram**, and **Zendesk Messaging** are incompatible. Toggle it on or off for each configured channel. See [Channels](https://chatbase.co/docs/user-guides/chatbot/actions/actions-overview.md#channels) for what configured, unconfigured, and incompatible mean.

**7. Enable and Test**

Click **Enable** to make the Action available to your AI agent, then test it.

## Details collection by platform

### Chatbase Helpdesk

When the ticket platform is **Chatbase**, you choose how the AI agent collects the customer's details before opening the ticket.

**How should details be collected?** This setting applies to the Chat Bubble and Help Page. Other channels, such as WhatsApp and Instagram, always collect details conversationally.

| Option | What it does |
| - | - |
| **Collect from a form** | The visitor fills out the fields in a widget inside the chat. |
| **Collect conversationally** | The AI agent asks for the details naturally in the conversation. |

**Collect additional details:** The fields collected before the ticket is created, in either mode. **Subject** and **Description** are built in and always collected. In the Chat Bubble and on the Help Page the visitor's email is collected too, and a verified address is used without asking. Click **Add field** to add a [custom field](https://chatbase.co/docs/user-guides/chatbot/help-desk/custom-fields.md), such as a date, a dropdown, a number, or an image. Each field has a type and an optional collection instruction that tells the AI agent how to ask for it. Click a field's **Required** or **Optional** badge, or its gear, to set whether it's required and to [customize its instruction](https://chatbase.co/docs/user-guides/chatbot/help-desk/custom-fields.md#collect-fields-when-creating-tickets) for this Action only. Use the pencil icon to edit a field or the **X** to remove it from this Action.

A required field must be filled before the ticket is created, in either mode. Make it optional to let the ticket go through without it.

With **Collect from a form**, the form opens with the subject and description the AI agent drafted, and with any of your fields the visitor already answered in the conversation. Photos are always uploaded in the form. A boolean field is a yes or no choice and a dropdown lists its options. A ticket carries at most 5 files across image fields and attachments.

![Chatbase Helpdesk details collection](https://mintcdn.com/chatbase/EhvCUQ4ZmSlhciUK/images/escalations-chatbase-helpdesk-details.png?fit=max\&auto=format\&n=EhvCUQ4ZmSlhciUK\&q=85\&s=9aa35631fa687fc6add7c4f3ef92a4ae)

> [!TIP]
>
> Fields are shared across your Helpdesk. Click **Manage fields** to open [Custom fields](https://chatbase.co/docs/user-guides/chatbot/help-desk/custom-fields.md), where you can create and edit them for every Action.

#### Tags

The **Tags** section lets the AI agent label each ticket it creates with tags from your [tag list](https://chatbase.co/docs/user-guides/chatbot/help-desk/tags.md). It sits between **Details collection** and **Channels**.

Click **Add tag** and pick a tag. Then describe when it applies in the **When should the AI use this tag?** box, for example `The customer reports a damaged or missing item`. Every tag needs a description, up to 200 characters.

The AI agent weighs each description on its own and adds every tag that fits, so a ticket can get several tags or none. Tags are added as the ticket is created, before any [triggers](https://chatbase.co/docs/user-guides/chatbot/help-desk/triggers.md) run, so a trigger that checks for a tag already sees them.

If the tag you need doesn't exist yet, type its name and click **Create "name"**. Typing the exact name of an archived tag offers **Restore "name"** instead. Both need permission to manage tags. Without it, ask an admin to add the tag in **Settings → Helpdesk → Tags**.

Changes to the tag list carry over to the Action:

* **Renaming a tag** updates the Action too. You don't need to edit it.
* **Archiving a tag** stops the AI agent from applying it. The tag stays on the Action with an **archived** badge until you restore it or remove it from the Action.

If your AI agent has no tags yet, the section shows **This chatbot has no tags yet.** Click **Manage tags** to create some.

### Zendesk

When the ticket platform is **Zendesk**, you control what goes on the ticket.

**Brand:** The Zendesk brand the ticket will be created under. Select **Default** to use the brand's default value at the time the ticket is created.

**Conversation context:** What the ticket contains.

| Option | What it does |
| - | - |
| **AI summary** | A concise, AI-written summary of the conversation, with a link to the full conversation in Chatbase. |
| **Full conversation** | The literal transcript, with any files the customer sent attached to the ticket. |

**Internal note (optional):** A private note added to the ticket for your team. Use variables in double curly braces to have the AI agent fill in details from the conversation. For example:

```text theme={null}
Reason of contact: {{reason_of_contact}}
Order ID: {{order_id}}
Status: {{status}}
```

**Custom fields (optional):** Chatbase reads the custom fields defined in your Zendesk account and lists them here. Select the ones you want on the ticket, and the AI agent fills them in automatically from the conversation.

![Zendesk details collection](https://mintcdn.com/chatbase/UdeXfRXeavGlAJA1/images/escalations-zendesk-details.png?fit=max\&auto=format\&n=UdeXfRXeavGlAJA1\&q=85\&s=3c544b58c8dbd39b340c7cd5b641bd94)

### Other platforms

Salesforce, Intercom, Zoho Desk, Gorgias, and Odoo have no platform-specific options. Three platforms show extra fields when you pick them:

| Platform | Fields |
| - | - |
| **HubSpot** | **HubSpot pipeline ID (optional)** and **HubSpot pipeline stage ID**. Leave the pipeline ID blank to use your portal's default pipeline. If your portal uses a custom pipeline, set the stage ID to a valid stage in that pipeline. |
| **Help Scout** | **Help Scout mailbox** (required). Tickets created by this Action are sent to this mailbox. To route tickets to different mailboxes, create one Action per mailbox. |
| **Freshdesk** | **Freshdesk ticket type** (optional), sent as the ticket's Type. If your Freshdesk marks Type as required, tickets fail without it. |

Complete these fields, if any, plus the **General** and **Channels** sections, and the AI agent creates the ticket with the customer's details, an AI-written summary of the conversation, and a link to the full conversation in Chatbase.

## How it works

When the Action triggers, the AI agent:

1. Collects any details it still needs from the customer.
2. Creates a ticket in the selected platform.
3. Includes the customer's information and the conversation on the ticket.

Your team continues the conversation from the helpdesk platform.

> [!TIP]
>
> Test the Action by asking your AI agent to speak to a human, and confirm a ticket appears in your chosen platform with the details and conversation attached.

### Handover with Chatbase Helpdesk

When the ticket platform is **Chatbase**, creating a ticket in the Chat Bubble, Help Page, Center Stage, Email, WhatsApp, Messenger, or Instagram hands the conversation to your team, the same way live chat works:

* The AI agent stops replying, and the customer's follow-up messages go to the ticket in the Helpdesk.
* Your team's replies reach the customer in the same chat or thread.
* Closing the ticket hands the conversation back to the AI agent.

In the Chat Bubble, Help Page, and Center Stage, the customer sees a ticket card marked **Submitted**, and a **Ticket** divider shows where your team joins the chat.

On API, Phone and mobile app (SDK) integrations, the AI agent keeps replying after it creates the ticket.

See [Ticket lifecycle](https://chatbase.co/docs/user-guides/chatbot/help-desk/ticket-lifecycle.md) for what happens next.

##### Voice sessions

In a voice session in the Chat Bubble, Help Page, or Center Stage, the AI agent tells the customer their request was submitted and that someone from your team will contact them, then ends the session. With **Collect from a form**, this happens once the customer submits the form. The voice button stays disabled while your team handles the ticket.

##### Phone calls

On a phone call, creating a Chatbase ticket doesn't end the call. The AI agent asks the caller for their email address, since your team's replies are sent there, and attaches their phone number to the ticket automatically. It then stays on the line and keeps helping the caller. If the caller raises another issue later in the same call, the AI agent adds it to the open ticket instead of opening a new one.

### Email handover with Zendesk

On the Email channel with **Zendesk** as the ticket platform, the AI agent handles the email thread on its own until the customer asks to speak to a human. Creating the ticket then hands the conversation over to your team, and the AI agent stops replying to the thread until the ticket is resolved.

| Stage | Who answers the customer in the email thread |
| - | - |
| Until the customer asks to speak to a human | The AI agent |
| While the Zendesk ticket is open | Your team, replying from Zendesk |
| After the ticket is **Solved** or **Closed** | The AI agent again |

What this means in practice:

* **Your team's Zendesk replies reach the customer in the same email thread.** There is no separate thread and no ticket notification for the customer to follow.
* **Customer replies during the handover go to the Zendesk ticket**, not to the AI agent.
* **Resolving the ticket hands the thread back.** Once the ticket is **Solved** or **Closed**, the AI agent answers the customer's next email as usual.

#### Attachments

Attachments work both ways during an email handover:

* **From the customer:** files and inline images the customer sends appear on the Zendesk ticket, up to 10 per email.
* **From your team:** files and inline images an agent adds to a Zendesk reply are sent to the customer as email attachments, up to 10 files and 25 MB per reply. Some file types, such as `.exe`, can't be sent by email.

> [!NOTE]
>
> On other ticket platforms and channels, the AI agent keeps replying after it creates the ticket.

> [!NOTE]
>
> Email handover is on by default for every AI agent and cannot be turned off.

## When should the AI agent escalate?

The **When to use** field decides when the AI agent creates a ticket, so it decides how often customers reach your team. Escalate too eagerly and your team answers questions the AI agent could have handled. Escalate too late and customers get stuck.

Good reasons to escalate:

* **The customer asks for a person.** "I want to speak to a human" should always work.
* **The AI agent can't answer from its content.** Have it confirm with the customer before it opens the ticket, as the default **When to use** does.
* **The request needs something no Action can do.** For example, no [Shopify Action](https://chatbase.co/docs/user-guides/chatbot/actions/shopify-actions.md#limitations) cancels an order or changes the shipping address on one, so those requests belong with your team.
* **The topic needs a person by policy,** such as legal complaints or account security.

Here's a sample **When to use** that adds these rules to the default:

```text theme={null}
Create a ticket when:
1. The customer asks to speak to a person, or to file a complaint.
2. You can't answer the question from your knowledge. Confirm with the customer
   before creating the ticket.
3. The customer wants to cancel an order or change its shipping address.
4. The customer reports a legal issue or a problem accessing their account.

Do not create a ticket for questions you can answer, such as shipping times
or return policy.
```

For a dedicated flow, create a second Escalations Action with its own name and rules, such as `create_ticket_refunds`, or turn on **Only use in Procedures** and call it from a [Procedure](https://chatbase.co/docs/user-guides/chatbot/procedures/procedures-overview.md) step. A Procedure can also branch on `{{agentAvailable}}` to offer [live chat](https://chatbase.co/docs/user-guides/chatbot/actions/chatbase-live-chat.md) when a teammate is available and open a ticket otherwise.

## Limitations

* **The full transcript is only available for Zendesk.** Every other platform receives an AI-written summary of the conversation and a link to the full conversation in Chatbase.
* **The form collection mode applies to the Chat Bubble and Help Page only.** Other channels always collect details conversationally.
* **Tags are available on Chatbase Helpdesk only.** Other ticket platforms don't show the **Tags** section.
* **An Action holds up to 5 tags.** **Add tag** greys out at the limit. Remove a tag to make room for another.

## Best Practices

> [card] Clear Escalation Criteria
>
> Spell out when the AI agent should escalate and when it should keep trying, so customers aren't handed off prematurely or left stuck.

> [card] One Action per Context
>
> Create separate Actions for different contexts, such as `create_ticket_refunds` and `create_ticket_whatsapp`, when they need different rules or fields.

> [card] Collect What Your Team Needs
>
> Add the fields your team would otherwise have to ask for, so the ticket arrives ready to work.

> [card] Require Sparingly
>
> Every required field is another thing the AI agent must extract before it can open the ticket. Mark the rest optional.

## Frequently asked questions

> [accordion] What does the customer see when the AI agent escalates?
>
> It depends on the ticket platform. With **Chatbase Helpdesk**, the AI agent collects the details you set up, from a form in the chat or by asking in the conversation, then creates the ticket and tells the customer that a ticket was opened. On the Chat Bubble, Help Page, Center Stage, Email, WhatsApp, Messenger, and Instagram, the AI agent then stops replying and your team's replies show up live in the same chat. On other ticket platforms and channels, the AI agent keeps replying after it creates the ticket, except on email with Zendesk. See [How it works](#how-it-works).

> [accordion] What happens if no one on my team is available?
>
> The ticket is still created. With Chatbase Helpdesk, assignment follows the [team's assignment settings](https://chatbase.co/docs/user-guides/chatbot/help-desk/assignment-algorithm.md). If no agent is **Available**, the ticket stays unassigned in the **Unassigned** view until someone picks it up, unless the team uses **Balanced** or **Round Robin** assignment with **Assign to next available shift** on, which routes it to the scheduled agent whose [shift](https://chatbase.co/docs/user-guides/chatbot/help-desk/scheduling.md) starts soonest.

> [accordion] What's the difference between Escalations and live chat?
>
> Escalations open a ticket for follow-up and work with Chatbase Helpdesk and third-party helpdesks. [Chatbase live chat](https://chatbase.co/docs/user-guides/chatbot/actions/chatbase-live-chat.md) routes the conversation to a person in the Chatbase Helpdesk in real time. Use live chat for urgent issues when your team is staffed, and Escalations for anything that can wait.

> [accordion] Does the ticket include the full conversation?
>
> Only on Zendesk, when **Conversation context** is set to **Full conversation**. Every other platform receives an AI-written summary of the conversation and a link to the full conversation in Chatbase, along with the customer's details and any fields you collect.
>
> In Chatbase Helpdesk, click **View conversation** on the ticket to see the customer's full chat with the AI agent before the ticket was created.

> [accordion] How does the conversation go back to the AI agent?
>
> With Chatbase Helpdesk, close or cancel the ticket. The AI agent answers the customer's next message, as long as no other ticket on the conversation is still open. See [Handing the conversation back to the AI agent](https://chatbase.co/docs/user-guides/chatbot/help-desk/ticket-lifecycle.md#handing-the-conversation-back-to-the-ai-agent). On email with Zendesk, the AI agent takes the thread back once the ticket is **Solved** or **Closed**.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.