> ## 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 Freshchat

> Connect Freshchat so your AI agent can hand live conversations over to human agents

The Chatbase Freshchat integration lets your AI agent hand a live conversation over to a human agent in Freshchat, Freshworks' live chat platform. It's for teams that staff a Freshchat inbox and want the AI agent to answer routine questions, then pass the customer to a person in real time without leaving the chat window. The handoff runs on the Chat Bubble, Center Stage, and Help Page.

> [card] What you can do:
>
> Let the AI handle routine questions, and hand the customer to a live Freshchat agent when the issue needs a person.

**Availability:** Freshchat needs the Chatbase Basic plan or higher. Freshchat isn't available on [HIPAA-compliant](https://chatbase.co/docs/user-guides/workspace/hipaa-compliance.md) accounts.

## Before you start

* A Chatbase account on the Basic plan or higher, with an AI agent
* Your Freshchat **Chat URL** and **API key**, from the API Tokens screen in Freshchat (see step 1 below)

## How to connect Freshchat

**1. Get your chat URL and API key from Freshchat**

In Freshchat, go to **Admin > Configure > API Tokens**, then copy the **chat URL** and **API key** shown there.

If your chat is part of Freshsales Suite, go to **Settings > Admin Settings > Website Tracking and APIs > API Settings** instead.

**2. Connect Freshchat in Chatbase**

1. Navigate to your Chatbase [dashboard](https://www.chatbase.co/dashboard/).
2. Click the AI agent you want to enable live chat for.
3. Navigate to **Integrations**.
4. On the **Freshchat** card, click **Connect**.
5. Enter your **Chat URL**, for example `https://yourcompany.freshchat.com`, and your **API Key**.
6. Click **Submit**.

Once connected, the card shows **Connected**.

**3. Create the Freshchat live chat Action**

Navigate to **Build > Actions**, click **Create Action**, then select **Freshchat live chat**. See [Freshchat live chat](https://chatbase.co/docs/user-guides/chatbot/actions/freshchat-live-chat.md) for how to configure it.

> [!TIP]
>
> Test the integration by asking your AI agent to speak to a human, and confirm the conversation reaches a live agent in Freshchat.

The connection belongs to this AI agent only. Each AI agent connects to one Freshchat account, so repeat these steps on every AI agent that should hand off to Freshchat.

### Chat URL format

The **Chat URL** field accepts your Freshchat address in a few forms:

* `https://` is optional. Chatbase adds it if you leave it out.
* A trailing slash or path is ignored. Only the hostname is kept.
* `http://` addresses are rejected.
* The address must end in `.freshchat.com` or `.myfreshworks.com`, for example `yourcompany.freshchat.com` or `yourcompany.myfreshworks.com`.

## How the handoff works

When the AI agent decides the customer needs a person, it calls the [Freshchat live chat](https://chatbase.co/docs/user-guides/chatbot/actions/freshchat-live-chat.md) Action. It needs the customer's email first, so it asks for one unless it already knows it, for example because the customer is signed in.

### What the customer sees

1. **Before the handoff**, the customer sees the AI agent's own message about connecting them to a person.
2. **While waiting**, a spinner shows **Waiting for support agent to join**.
3. **When the first agent replies**, a divider reads **\<agent name> connected**, with the agent's Freshchat avatar. If the name isn't known, it reads **Live agent connected**. Each group of agent replies shows the agent's name and the time.
4. **When the agent resolves the chat**, an **AI Resumed** divider appears and the AI agent answers the customer's next message.

These messages appear in the widget's language. Agent replies don't stream as they're typed: the chat checks for new replies every few seconds, so each one appears shortly after the agent sends it. Links and files the agent sends reach the customer, but Freshchat private notes and private messages don't.

Chatbase doesn't check whether anyone is online or whether you're inside business hours. The conversation opens in Freshchat either way, and the customer keeps seeing **Waiting for support agent to join** until an agent replies or resolves the chat. There's no timeout. The customer can end the chat themselves, which resolves the Freshchat conversation. Away or bot messages that Freshchat posts into the conversation may also reach the customer.

### Example flow

For example, a customer on the Chat Bubble writes "My account is locked and I need to talk to someone."

1. The AI agent asks for their email, and the customer replies [jane@example.com](mailto:jane@example.com).
2. The AI agent hands off, and the customer sees **Waiting for support agent to join**.
3. In Freshchat, a new conversation opens in the channel set on the Action, with the conversation details and the chat so far.
4. An agent named Sam replies. The customer sees **Sam connected** and Sam's reply in the same chat window.
5. Sam unlocks the account and resolves the conversation in Freshchat. The customer sees **AI Resumed**, and the AI agent answers their next question.

### What the Freshchat agent receives

Each handoff creates a new Freshchat user with the customer's name, email, and, when the contact has one, phone number. The conversation opens with status **New** in the channel chosen in the Action's **Freshchat channel** dropdown. Chatbase doesn't set a group or assignee, so Freshchat's own assignment rules usually decide who picks it up.

The conversation starts with a message containing the Chatbase conversation ID, an AI-written title, and a link to the conversation in your Chatbase dashboard. What follows depends on the Action's **Conversation context** setting:

| Conversation context | What the Freshchat agent sees |
| - | - |
| **Full conversation** (default) | The whole chat so far, posted as messages starting with "Visitor:" and "Bot:". Files the customer sent are uploaded to Freshchat. |
| **AI summary** | An AI-written summary in the opening message, written from the customer's point of view. Only the messages that carried files are posted, as "Visitor:" followed by the file name, with the file attached. |

After the handoff, the customer's new messages and attachments are forwarded to Freshchat as they're sent. Agent replies are also saved in Chatbase, so you can read them in the conversation in [Activity](https://chatbase.co/docs/user-guides/chatbot/activity.md).

### How the conversation returns to the AI agent

The AI agent takes over again when the agent resolves the conversation in Freshchat. What happens next depends on the Action:

* **By default**, the customer sees **AI Resumed** and keeps chatting with the AI agent in the same conversation.
* **With End the conversation when the agent resolves it checked**, the conversation ends instead, and the customer starts a new one. If **Ask the user to rate the chat after the agent resolves it** is also on, the customer sees the [satisfaction survey](https://chatbase.co/docs/user-guides/chatbot/actions/freshchat-live-chat.md#satisfaction-survey) first.

The chat also returns to the AI agent straight away if Freshchat stops accepting the API key or the integration is removed.

## Limitations

* **The live chat Action runs on three channels only:** **Chat Bubble**, **Center Stage**, and **Help Page**. It isn't available on WhatsApp, Instagram, Messenger, email, or phone. See [Channels](https://chatbase.co/docs/user-guides/chatbot/actions/actions-overview.md#channels) for what configured, unconfigured, and incompatible mean.
* **Not available on HIPAA-compliant accounts.** The **Connect** button is disabled there.
* **No availability check.** The handoff happens even when no agent is online, and the customer waits until someone replies.
* **One Freshchat account per AI agent.**

## Troubleshooting

> [accordion] Connecting shows "Invalid chat URL."
>
> The address doesn't point to your Freshchat account. Copy the chat URL again from **Admin > Configure > API Tokens** in Freshchat. It must end in `.freshchat.com` or `.myfreshworks.com`.

> [accordion] The Chat URL field says "Enter your Freshchat URL"
>
> The address isn't in a format Chatbase accepts. Use an `https://` address, or no scheme at all, ending in `.freshchat.com` or `.myfreshworks.com`. See [Chat URL format](#chat-url-format).

> [accordion] Connecting shows "Freshchat rejected the API key. Check the key and try again."
>
> The key is wrong or no longer valid. Copy the current key from the API Tokens screen in Freshchat and try again.

> [accordion] Connecting shows that Freshchat refused the API key with 403 Forbidden
>
> Freshchat recognized the key but refused it, so it may lack the permissions this integration needs. Check the key in Freshchat, or generate a new one, and try again.

> [accordion] Connecting shows "Failed to connect to Freshchat" or a rate limiting message
>
> For **Failed to connect to Freshchat. Please check your chat URL.**, check the address for typos. For **Freshchat is rate limiting requests. Try again in a few minutes.**, wait a few minutes before you try again.

> [accordion] The Freshchat card says it no longer accepts the saved API key
>
> The key was revoked or regenerated in Freshchat, so chats can't be handed off. Click **Reconnect** on the card and enter a current key. Any conversation that was with an agent when Freshchat stopped accepting the key goes back to the AI agent.

> [accordion] The customer waits but no agent joins
>
> Check that someone in Freshchat is watching the channel set in the Action's **Freshchat channel** dropdown. The dropdown lists every Freshchat topic, including ones hidden from your Freshchat messenger, and preselects the first one, so make sure it's the channel your team works.

> [accordion] The AI agent never hands off
>
> Check that the **Freshchat live chat** Action is enabled, turned on for the channel you're testing, and that its **When to use** covers the request. If you saved changes, click **Publish** so the live AI agent uses them. Remember that the Action doesn't run on WhatsApp, Instagram, Messenger, email, or phone.

## Frequently asked questions

> [accordion] Does the Freshchat agent see what the customer already told the AI agent?
>
> Yes. With **Conversation context** set to **Full conversation**, the default, the agent sees the whole chat. With **AI summary**, the agent gets an AI-written summary. Either way, the conversation includes a link to the full chat in Chatbase.

> [accordion] What happens if no one is available in Freshchat?
>
> The conversation still opens in Freshchat, and the customer sees **Waiting for support agent to join** until an agent replies. Chatbase doesn't check agent status or business hours. To open a ticket instead when nobody can answer, use the [Escalations](https://chatbase.co/docs/user-guides/chatbot/actions/escalate-to-human.md) Action.

> [accordion] How does the customer get back to the AI agent?
>
> When the agent resolves the conversation in Freshchat, an **AI Resumed** divider appears and the AI agent answers again. If the Action ends the conversation on resolve, the customer starts a new conversation instead.

> [accordion] Can Freshchat take over conversations on WhatsApp or Instagram?
>
> No. Freshchat live chat works on the Chat Bubble, Center Stage, and Help Page only. On other channels, use the [Escalations](https://chatbase.co/docs/user-guides/chatbot/actions/escalate-to-human.md) Action to open a ticket.

> [accordion] Do I need admin access in Freshchat?
>
> Chatbase only needs the chat URL and an API key. You get both from the API Tokens screen, so you need whatever access Freshchat requires to open that screen.

> [accordion] Which Freshchat channel do handed-off conversations land in?
>
> The one you pick in the Action's **Freshchat channel** dropdown. New live chats open there with status **New**, and Freshchat's assignment rules take it from there.

## Next steps

> [card] [Freshchat live chat](https://chatbase.co/docs/user-guides/chatbot/actions/freshchat-live-chat.md)
>
> Configure when your AI agent hands customers over to Freshchat.

> [card] [Escalations Action](https://chatbase.co/docs/user-guides/chatbot/actions/escalate-to-human.md)
>
> Prefer an asynchronous handoff? Open a ticket instead of routing the customer to a live agent.


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