Skip to main content
Chat Escalation lets your AI agent hand off a live chat conversation to a human agent in Freshchat. By default, the agent hands off when the visitor asks to speak to a person, and you can add other triggers in the agent’s guidelines. The agent then picks the Freshchat channel that best fits the conversation and transfers the visitor — all without interrupting the flow of the conversation.

​
Prerequisites

Before configuring chat escalation, make sure you have:
  • A Freshchat account with at least one active channel
  • Access to Admin Settings in Freshworks, to copy your API key and set up a webhook
  • The Freshchat integration connected in Manage → Connected Apps (see Connected Apps)
  • Transfer switched on for the agent. It is on by default. If it has been turned off under Agent Settings → Toggle transfer, the agent’s Handoff card is greyed out and the agent can’t escalate chats (on an agent you’ve published, the switch reaches live chats at your next Publish). See Toggle Transfer

​
1. Connect Your Freshchat Account

If you have not already connected Freshchat, follow these steps:
  1. Go to Manage → Connected Apps. This page isn’t in an account user’s default sidebar, so add it with Customize sidebar, or press Cmd/Ctrl+K and search for it. See Navigating Studio.
  2. Find the Freshchat card and click Connect.
  3. In the Connect Freshchat dialog, enter your Domain (for example yourcompany.myfreshworks.com), Chat URL (for example yourcompany.freshchat.com) and API Key. All three are required. To find your API key, open your Freshworks domain, go to Admin Settings, search for API Settings and copy Your API Key.
  4. Click Connect.
  5. In the Freshchat Webhook dialog, set up the webhook. This step is required, and the dialog can’t be closed until you finish it:
    • Copy the Webhook URL shown (the copy icon beside it does this for you).
    • Click Open webhook settings in Freshworks, enable webhooks there and paste the URL into the Webhook field.
    • In the Authentication section of that page, generate the public key if you haven’t already, then copy it.
    • Paste it into Webhook public key in Studio. It must be in PEM format, starting with -----BEGIN RSA PUBLIC KEY----- and ending with -----END RSA PUBLIC KEY-----.
    • Click Continue, which stays disabled until a key is entered.
  6. In the Describe this connection dialog, write a short description of what the connection is for, then click Save Connection. A description is required.
The Freshchat card then shows how many accounts are connected. Click the count to open Connected Freshchat Accounts. See Webhook Setup for why the webhook step matters.

​
2. Choose the Handoff Platform

Freshchat escalation is configured per AI Agent, and per channel. To activate it:
  1. Open the AI Agent in Studio.
  2. In the Agent section of the agent’s page, click the Handoff card (“Control when and how humans jump in”).
  3. In the drawer that opens, select Chat at the top, beside Voice and Email.
  4. Under Handoff Platform at the top of the tab, open the list and select your Freshchat connection. Each connection is listed as Freshchat — followed by its Chat URL, for example Freshchat — yourcompany.freshchat.com. If you have not connected Freshchat yet, the list is greyed out and shows None with a note that there are no connections.
Add Connection, beside the Handoff Platform heading, is always available. It opens Connected Apps with the Connect Freshchat dialog already open. When you finish connecting (including the webhook and description steps in section 1), Studio brings you back to the agent’s Handoff settings with the new connection selected. Once a connection is selected, Studio shows Agent escalation settings updated and loads the channels enabled in that Freshchat account. See Sync Channels and Configure Outcome Options.
If the agent has been published, publish straight after you choose or change the Handoff Platform. Live chats start escalating through the new connection at once, but the channel list Studio loads from it reaches them only at your next Publish, as do your edits to the outcome options and the Handoff Message. Until then they escalate through the new connection with the previous channel list, and a handoff can fail. See What Waits for Publish.
To turn chat escalation off, select None. Studio shows Agent escalation turned off and clears the Chat outcome options.
This setting used to live under Chat Configuration → Widget Config → Agent Escalation, which no longer exists. Any connection you had already chosen carries over.
When you pick a connection from the Handoff Platform list, each channel keeps its own handoff platform, so changing the platform on the Email tab no longer moves Chat with it. On the Email tab the platform is decided by the agent’s connected mailbox — see Email Agents. Add Connection works differently: when you come back from Connected Apps, the new connection is also linked to the agent’s Email handoff. After using it, check Handoff Platform on the Email tab, especially if the agent’s email runs through a Freshdesk mailbox.

​
The Handoff Message

The Chat tab also carries a Handoff Message — the copy the widget shows a visitor as they are connected to a person. Chat previously used fixed wording for this. Fill in the default message, plus one box for each language configured on the agent. Variables can be inserted, so the message can name the customer or quote their reference. Leave it blank to keep the standard wording. On an agent you’ve published, a change reaches live chats at your next Publish.

​
3. Sync Channels and Configure Outcome Options

The channels enabled in your Freshchat account appear as outcome options on the Chat tab. Each outcome is a named routing target that the AI uses when deciding where to escalate, and it represents one Freshchat channel. Freshchat may call these channels topics in its own admin screens. On an agent you’ve published, the outcome list and every edit to it, including a sync, are saved to the draft and reach live chats at your next Publish.

​
Sync Channels

Choosing a connection under Handoff Platform syncs its channels straight away, so the Outcome options list on the Chat tab is already filled in the first time you look. Until you choose a connection, the tab shows No handoff platform selected instead of the list. To pull in changes you make in Freshchat later, click Sync from Freshchat at the top right of Outcome options, then confirm in the Sync from Freshchat dialog. The dialog warns that saved outcomes for channels that are now disabled or missing in Freshchat will be removed from the list. A sync reads the Freshchat connection chosen under Handoff Platform on the Chat tab, and Studio confirms it with Chat dispositions synced. A sync replaces the Chat list with the channels that are currently enabled in Freshchat. The Email tab’s list isn’t touched.
  • Newly enabled channels are added.
  • Channels that are disabled or no longer in Freshchat are removed from the list.
  • Every description is generated again. Descriptions you edited are replaced, and any outcome you deleted comes back.
If Freshchat returns no enabled channels, the list ends up empty and Studio shows No enabled channels found.
SquawkVoice automatically generates a one-sentence description for each channel using AI (e.g. “When the customer has a billing question that requires account review.”). You can edit these descriptions, but each sync writes new ones.

​
Edit Descriptions

The description attached to each outcome is the primary signal the AI uses to choose which channel to route the chat to. A well-written description should:
  • Start with “When the customer…”
  • Be specific about the type of issue that warrants escalation to this channel
  • Avoid overlapping phrasing with other outcome descriptions
  • Stay under 200 characters, because only the first 200 characters of each description are read
Example:
When the customer is requesting a refund or disputing a charge that cannot be resolved automatically.
To edit a description, click its Description cell in the table, change the text, then press Enter or click away to apply it. Press Esc to cancel. A description can’t be left empty. Outcome names come from Freshchat and can’t be changed here. Changes save automatically. Edit descriptions after you sync, because a later sync generates them again.

​
Remove an Outcome

To stop the AI from routing to a particular channel, click the delete icon (X) next to its outcome. This removes it from the agent’s configuration without deleting the channel in Freshchat. The next sync brings it back if the channel is still enabled in Freshchat.

​
Automatic Outcomes

The outcome options table on the Chat tab lists two automatic outcomes at the top, as read-only rows you cannot edit or remove:
User Abandoned is the display name for chat. You’ll see it in this editor, and as User-Abandoned (with a hyphen) in Chat History and Chat Analytics. Voice screens still label the equivalent outcome Caller-Hungup, and data exports and downstream reporting record the stored value, Caller-Hungup — so keep matching on that rather than on the label. The exception is a chat where the visitor never wrote anything: it is stored and listed as User Abandoned, with a space, in Chat History and in exports.

​
4. How the AI Decides to Escalate

Out of the box, the agent is told to hand off only when the visitor asks to speak to a human, an agent or a customer service representative. To have it escalate in other situations, say so in the agent’s guidelines. Once the agent decides to escalate, two things steer where the chat goes:
  • Outcome descriptions — the agent matches the current situation against each outcome’s description to identify the best-fit channel
  • Agent guidelines — any explicit escalation rules you define, such as which outcome to use for a given request
The agent initiates the handoff with the outcome whose description best matches the conversation. If it doesn’t pick one of your outcomes, the chat goes to the first channel in the list, the first row below Contained and User Abandoned. Keep the descriptions clear and distinct. On an agent you’ve published, edits to the guidelines reach live chats at your next Publish, like the outcome descriptions.
For precise control over escalation behaviour, include explicit instructions in your agent guidelines — for example: “If the customer asks to speak to a billing agent, immediately escalate using the Billing outcome.”

​
5. What Happens During Escalation

When an escalation is triggered:
  1. The AI identifies (or creates) the Freshchat user record for the current chat participant, matching on a reference identifier where available.
  2. A new conversation is created under the selected Freshchat channel. It opens with a short note: Handoff: User requested to speak with a human agent.
  3. The conversation becomes visible to human agents in the Freshchat dashboard, where they can pick it up and continue the interaction.
  4. The full chat transcript follows as a Chat Transcription message, then an AI-written Summary is added when it is ready, so the human agent has the context behind the handoff.
The handoff is logged in the AI Agent’s interaction history, including which channel was selected and the timestamp.

​
What the visitor sees

  • While the handoff is set up: Connecting you to a live agent for further assistance…, or your Handoff Message if you have set one.
  • Once a person picks the conversation up: Connected to and the agent’s first name, for example Connected to Sam., or Connected to a live agent. if the name isn’t available.
  • If the connection can’t be made: We cannot connect you to an agent at the moment. The AI then carries on with the chat.
  • When the human agent resolves the conversation in Freshchat: The agent has closed this conversation. The chat ends, and the AI does not take it back.
The “connecting” and “connected” messages the visitor sees appear in the transcript once, as a system notice, and don’t count toward the chat’s Message Count.

​
How Long a Handoff Lasts

Before a handoff, a chat the AI is handling ends after 24 hours with no message from the visitor or the AI, as long as the visitor’s page stays open. This can’t be changed, and the visitor sees the agent’s closing message rather than the inactivity message below. If the visitor closes the page or leaves, the chat is held for about 10 minutes and then ended if they haven’t come back. See When a Chat Ends. If a handoff fails and the AI carries on with the chat, that 24-hour clock starts again. Once the handoff starts, the 24-hour clock stops and the limits below take over. Waiting for an agent to pick the conversation up counts toward them. A conversation handed to a human does not stay open indefinitely. SquawkVoice closes it when either limit is reached: When either lapses, the visitor sees “This conversation has ended due to inactivity.”, the conversation in Freshchat is closed so your agents stop accumulating stale threads, and the AI does not take the conversation back. Escalated email conversations work differently: they have no inactivity limit and stay open until resolved. SquawkVoice only follows the person’s work while the Freshdesk ticket keeps getting replies, though. After about 72 hours with no reply on the ticket it stops tracking the handoff, and the conversation stays Escalated until a supervisor selects Resolve in email history. See The conversation stays open.
There is no Studio setting for this. Expect conversations that previously sat open — including any your team deliberately parked overnight — to start appearing as timed-out endings in your chat reporting.

​
Webhook Setup

The Freshchat webhook and its public key are required. Studio asks for both while you connect Freshchat (step 5 in Connect Your Freshchat Account). Freshchat uses the webhook to send events back to SquawkVoice once a chat has been handed over — for example, relaying a human agent’s replies into the chat, and telling SquawkVoice when the agent resolves the conversation. SquawkVoice uses the public key to verify the signature on every inbound webhook event, rejecting any payload that cannot be authenticated. A connection without the webhook and key can’t be used for escalation. The visitor is told the connection couldn’t be made, and the AI carries on with the chat.

​
Best Practices

  • Keep outcome descriptions distinct — if two outcomes have similar descriptions, the AI may route inconsistently. Make each description specific to a clear scenario, and keep it under 200 characters. If the AI doesn’t pick one of your outcomes, the chat goes to the first channel in the list.
  • Sync after Freshchat changes, then re-check your descriptions — if you add, rename, or disable channels in Freshchat, click Sync from Freshchat on the Chat tab to bring the list up to date. A sync generates every description again and brings back any outcome you deleted, so make your edits afterwards. On a published agent, Publish once you are done, because live chats keep the previous list until you do.
  • Test escalation with the Chat button — click Chat in the agent’s header to open a test chat, ask for a person, and confirm the chat goes to the right channel before going live. The test chat uses your latest draft, so on an agent you’ve published, Publish first and then try a real chat on your site.

​
Where to go next

Connected Apps

Manage your Freshchat connection and other third-party integrations.

In-conversation Actions

Build flows that call external APIs mid-conversation.