Skip to main content
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.

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 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.
  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 for how to configure it.
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 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.
  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: 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.

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

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.
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.
The key is wrong or no longer valid. Copy the current key from the API Tokens screen in Freshchat and try again.
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.
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.
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.
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.
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

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.
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 Action.
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.
No. Freshchat live chat works on the Chat Bubble, Center Stage, and Help Page only. On other channels, use the Escalations Action to open a ticket.
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.
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

Freshchat live chat

Configure when your AI agent hands customers over to Freshchat.

Escalations Action

Prefer an asynchronous handoff? Open a ticket instead of routing the customer to a live agent.