Chat Escalation

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. Link the Connection to an AI Agent

Freshchat escalation is configured per AI Agent. To activate it:

1. Open the AI Agent in Studio.
2. Navigate to the Handoff section (below the main configuration tabs).
3. Under Agent Escalation (Chat), select your Freshchat connection from the dropdown.

Once a connection is selected, SquawkVoice will load the available Freshchat topics associated with that account.

---

​

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.

​

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.

---

​

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.

---

​

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.

---

​

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