Skip to main content
Before debugging, have this ready:
  • Your Freshchat and the admin email that owns the .
  • A specific OpenCX session ID (from Inbox) or Freshchat conversation ID where the problem shows.
  • The Default Agent Email you saved in the integration settings.
Re-run Test & Save in Settings → Integrations → FreshChat as your first step. Most issues are credential or webhook related.

​
Common scenarios

Fastest path to root cause: open the failing OpenCX session from your Inbox. The session stores the Freshchat conversation URL — one click jumps you to the exact Freshchat thread to compare what OpenCX saw against what Freshchat shows.

​
”Failed to verify credentials” on Test & Save

: wrong domain format, revoked token, or insufficient token permissions. Fix: enter the plain domain (yourcompany.freshchat.com, no https://). Regenerate the token in Freshchat Admin Settings → Integrations & APIs and confirm it has conversation management permissions.

​
Token was rotated in Freshchat and the integration went silent

: token rotated in Freshchat, not updated in OpenCX. Fix: paste the new token into Settings → Integrations → FreshChat and click Test & Save. Then revoke the old token in Freshchat.

​
Customer contacts merging unexpectedly

: same email shared across Freshchat users. Fix: this is expected behavior — see Conversation flow → Channel-specific details. Give each end user a distinct email in Freshchat if you need separate OpenCX contacts.

​
Integration went silent after disconnect and reconnect

: the webhook was removed or its events were unchecked in Freshchat while the integration was disconnected. Fix: open Freshchat Admin Settings → Integrations & APIs → Webhooks and confirm the webhook still exists, its endpoint matches the URL shown in Settings → Integrations → FreshChat, and all four events are checked.

​
AI replies arrive from the wrong agent name

: the Freshchat agent was renamed or the default agent email was pointed at a different person. Fix: rename the agent in Freshchat, or change Default Agent Email in OpenCX settings to the intended agent. Create a dedicated agent (for example OpenCX AI) if you want a stable brand on replies.

​
Handoff marker property is missing

: cf_opencx_handed_off has not been created in Freshchat as an editable checkbox property, or your Freshchat role cannot create conversation properties. Fix: ask a Freshchat admin to create an editable checkbox conversation property named cf_opencx_handed_off, then select it in Settings → Integrations → FreshChat. If you cannot create a new field, select an existing editable custom checkbox property only if your routing rules can safely use it as the handoff marker.

​
Limits & timing

OpenCX does not throttle or queue calls against the Freshchat rate limit. Sustained high-volume chat may hit Freshchat’s per-minute ceiling during peaks — if you expect spikes, contact support to discuss pacing.

Connect Freshchat

Re-verify credentials, webhook events, and routing mode.

Conversation flow

Re-check how chats match to sessions and how handoff lands.

Overview

What the Freshchat integration does and how it fits with your team.

Human handoff

Global handoff rules and office hours.