- 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.
Common scenarios
| Symptom | Likely cause | Where to check |
|---|---|---|
| AI never replies to any Freshchat chat | Webhook URL not added in Freshchat, or the Message Created event is unchecked | Freshchat Admin Settings → Integrations & APIs → Webhooks |
| AI replies to some chats but not others | Routing mode is Assigned-only and those chats aren’t being assigned to the default agent email | OpenCX FreshChat settings + Freshchat assignment rules |
| Private handoff note missing inside Freshchat | The Default Agent Email no longer resolves to an agent in Freshchat (agent deleted, email changed) | Freshchat Admin Settings → Team |
| Conversations closed in Freshchat stay open in OpenCX | Conversation Resolved or Conversation Closed events unchecked on the webhook | Freshchat Admin Settings → Integrations & APIs → Webhooks |
| None of the above | Open a support request with the session ID, the Freshchat conversation ID, and a short description | [email protected] |
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.Webhook URL regenerated after disconnect and reconnect
: webhook URL in Freshchat is stale. Fix: copy the current URL from Settings → Integrations → FreshChat and update the endpoint on the Freshchat webhook.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.Limits & timing
| Value | |
|---|---|
| Freshchat API call timeout | 10 seconds per call |
| Webhook deduplication window | 24 hours |
| Retry / backoff | None — OpenCX does not retry transient Freshchat failures beyond the single call |
| Freshchat API rate limit | Governed by your Freshchat plan — typical limit is 60 requests per minute |
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.
Related Documentation
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.