> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Freshchat troubleshooting

> Debug Freshchat credentials, webhook events, routing mode, handoff notes, and resolution sync.

Before debugging, have this ready:

* Your Freshchat <Tooltip tip="The subdomain of your Freshchat workspace — the yourcompany part of yourcompany.freshchat.com.">domain</Tooltip> and the admin email that owns the <Tooltip tip="The API access token generated under Admin Settings → Integrations & APIs. Bound to the admin that created it.">API token</Tooltip>.
* A specific OpenCX session ID (from [Inbox](https://platform.open.cx/inbox)) or Freshchat conversation ID where the problem shows.
* The **Default Agent Email** you saved in the integration settings.

<Tip>
  Re-run **Test & Save** in [Settings →
  Integrations](https://platform.open.cx/settings/integrations) → FreshChat as
  your first step. Most issues are credential or webhook related.
</Tip>

## Common scenarios

| Symptom                                                     | Likely cause                                                                                                                                            | Where to check                                                                                                 |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| AI never replies to any Freshchat chat                      | Webhook URL not added in Freshchat, or the **Message Create** 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](https://platform.open.cx/settings/integrations) + Freshchat assignment rules       |
| Assigned-only mode never picks up chats, even when assigned | **Conversation Assignment** event unchecked on the webhook — OpenCX never hears about the assignment                                                    | Freshchat **Admin Settings → Integrations & APIs → Webhooks**                                                  |
| 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**                                                                            |
| Saved handoff marker says "not found in Freshchat"          | The selected marker property does not exist as an editable checkbox property in Freshchat, or your role can view but not create conversation properties | Freshchat **Admin Settings → Conversation properties**; ask a Freshchat admin to create `cf_opencx_handed_off` |
| Conversations resolved in Freshchat stay open in OpenCX     | **Conversation Resolution** event 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                                                      | [support@open.cx](mailto:support@open.cx)                                                                      |

<Info>
  **Fastest path to root cause:** open the failing OpenCX session from your
  [Inbox](https://platform.open.cx/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.
</Info>

### **"Failed to verify credentials" on Test & Save**

<Tooltip tip="Usually caused by including https:// in the domain, a token the admin revoked, or a token without conversation management permissions.">
  Likely cause
</Tooltip>

: 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](https://support.freshchat.com/en/support/solutions/articles/50000000306-freshchat-apis) and confirm it has conversation management permissions.

### **Token was rotated in Freshchat and the integration went silent**

<Tooltip tip="Freshchat tokens do not auto-propagate. OpenCX keeps using the old token until you paste the new one and re-save.">
  Likely cause
</Tooltip>

: token rotated in Freshchat, not updated in OpenCX.

**Fix:** paste the new token into [Settings → Integrations → FreshChat](https://platform.open.cx/settings/integrations) and click **Test & Save**. Then revoke the old token in Freshchat.

### **Customer contacts merging unexpectedly**

<Tooltip tip="OpenCX maps one contact per email. Two Freshchat users with the same email share one OpenCX contact — by design.">
  Likely cause
</Tooltip>

: same email shared across Freshchat users.

**Fix:** this is expected behavior — see [Conversation flow → Channel-specific details](/integrations/freshchat/conversations#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**

<Tooltip tip="The webhook URL is stable for your organization — reconnecting does not change it. What usually breaks is the webhook itself being deleted or edited in Freshchat during cleanup.">
  Likely cause
</Tooltip>

: 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](https://platform.open.cx/settings/integrations), and all four events are checked.

### **AI replies arrive from the wrong agent name**

<Tooltip tip="The AI posts Freshchat messages as the agent whose email matches Default Agent Email. Changing the agent's name in Freshchat changes what the customer sees.">
  Likely cause
</Tooltip>

: 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](https://platform.open.cx/settings/integrations) 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**

<Tooltip tip="The Freshchat automation and support group handoff strategies need an editable custom checkbox property that OpenCX can set before Freshchat routing or assignment runs. Direct agent assignment does not use the marker.">
  Likely cause
</Tooltip>

: `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](https://platform.open.cx/settings/integrations). 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

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

<Note>
  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.
</Note>

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Connect Freshchat" icon="plug" href="/integrations/freshchat/connect">
    Re-verify credentials, webhook events, and routing mode.
  </Card>

  <Card title="Conversation flow" icon="diagram-project" href="/integrations/freshchat/conversations">
    Re-check how chats match to sessions and how handoff lands.
  </Card>

  <Card title="Overview" icon="comment" href="/integrations/freshchat/overview">
    What the Freshchat integration does and how it fits with your team.
  </Card>

  <Card title="Human handoff" icon="user-group" href="/handoff/introduction">
    Global handoff rules and office hours.
  </Card>
</CardGroup>