Skip to main content
Chat Escalation lets your AI agent hand off a live chat conversation to a human agent in Freshchat when the situation requires it. The agent determines the right moment to escalate based on conversation context, selects the most appropriate Freshchat channel, and seamlessly transfers the user — 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
  • The Freshchat integration connected in Manage → Connected Apps (see Connected Apps)

​
1. Connect Your Freshchat Account

If you have not already connected Freshchat, follow these steps:
  1. Go to Studio → Manage → Connected Apps.
  2. Find the FreshChat card and click Connect.
  3. Enter your Domain, Chat URL, and API Key.
  4. Optionally, paste a Webhook Public Key (PEM format) if you want SquawkVoice to verify webhook payloads sent from Freshchat.
  5. Click Connect to save. The connection will appear in the Connected Accounts list.

​
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. Navigate to the Handoff section (below the main configuration tabs).
  3. Select the Chat tab.
  4. Under Handoff Platform at the top of the tab, select your Freshchat connection. Add Connection beside it takes you straight to Connected Apps if you have not connected one yet.
Once a connection is selected, SquawkVoice will load the available Freshchat topics associated with that account.
This setting used to live under Chat Configuration → Widget Config → Agent Escalation, which no longer exists. Any connection you had already chosen carries over.
Each channel keeps its own handoff platform, so changing the platform for email or SMS no longer moves chat with it. On the Email tab the platform is decided by the agent’s connected mailbox — see Email Agents.
If you call the assistant handoff setup endpoint directly, move to .../handoff/setup. The older chat-escalation/setup path still works but is deprecated and will be removed.

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

​
3. Sync Topics and Configure Dispositions

Freshchat Topics map to chat dispositions in SquawkVoice — named routing targets that the AI uses when deciding where to escalate. Each disposition represents one topic in your Freshchat account.

​
Sync Topics

Click Refresh from Freshchat to fetch the latest list of topics. Any new topics added in Freshchat will appear here; topics that have been removed will be flagged.
SquawkVoice automatically generates a one-sentence description for each topic using AI (e.g. “When the customer has a billing question that requires account review.”). These descriptions are editable.

​
Edit Descriptions

The description attached to each disposition is the primary signal the AI uses to decide whether to route to that topic. A well-written description should:
  • Start with “When the customer…”
  • Be specific about the type of issue that warrants escalation to this topic
  • Avoid overlapping phrasing with other topic descriptions
Example:
When the customer is requesting a refund or disputing a charge that cannot be resolved automatically.
To edit a description, click the text field next to the topic name, update the content, and save.

​
Remove a Disposition

To stop the AI from routing to a particular topic, click the delete icon next to it. This removes it from the agent’s configuration without deleting the topic 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 in this editor only. Voice still labels the equivalent outcome Caller-Hungup, and data exports and downstream reporting record the stored value — so keep matching on that rather than on the label.

​
4. How the AI Decides to Escalate

During a chat conversation, the AI evaluates whether escalation is appropriate based on:
  • Conversation context — the nature of the user’s query and any unresolved issues
  • Topic descriptions — the agent matches the current situation against each disposition description to identify the best-fit topic
  • Agent guidelines — any explicit escalation rules or thresholds you define in the agent’s guidelines
When the AI determines escalation is warranted, it selects the disposition whose description best matches the context and initiates the handoff.
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 topic disposition.”

​
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 topic with the user’s context and any relevant messages passed as the initial payload.
  3. The conversation becomes visible to human agents in the Freshchat dashboard, where they can pick it up and continue the interaction.
The handoff is logged in the AI Agent’s interaction history, including which channel was selected and the timestamp.

​
How Long a Handoff Lasts

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. The same limits apply to escalated email conversations, which are completed and have their post-conversation actions run.
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 and email reporting.

​
Webhook Verification (Optional)

If Freshchat is configured to send webhook events back to SquawkVoice (for example, to relay agent replies into the chat flow), you can enable payload verification:
  1. In the Freshchat connection settings, paste the Webhook Public Key (PEM format) provided by Freshchat.
  2. SquawkVoice will use this key to verify the signature on every inbound webhook event, rejecting any payloads that cannot be authenticated.
This setting is optional but recommended for production deployments.

​
Best Practices

  • Keep topic descriptions distinct — if two topics have similar descriptions, the AI may route inconsistently. Make each description specific to a clear scenario.
  • Refresh topics after Freshchat changes — if you add, rename, or archive topics in Freshchat, re-sync from the Handoff configuration to keep dispositions up to date.
  • Test escalation in the Live Testing Console — simulate a chat conversation that should trigger escalation and confirm the correct topic is selected before going live.

​
Where to go next

Connected Apps

Manage your Freshchat connection and other third-party integrations.

During-Call Actions

Build flows that call external APIs mid-conversation.