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

# Freshdesk ticketing troubleshooting

> Debug Freshdesk credentials, automation rules, intake gating, handoff routing, marker fields, and resolution sync.

Before debugging, have this ready:

* Your Freshdesk <Tooltip tip="The yourcompany part of yourcompany.freshdesk.com.">domain</Tooltip> and the email of the dedicated OpenCX agent whose <Tooltip tip="The API key from Profile settings → Your API Key of the OpenCX agent. Must belong to an admin.">API key</Tooltip> you saved.
* A specific OpenCX session ID (from [Inbox](https://platform.open.cx/inbox)) or Freshdesk ticket ID where the problem shows.
* Your intake mode (**Auto Handle All Incoming Tickets** on/off) and configured **Default Group**, if any.

<Tip>
  Re-run **Verify** in [Settings →
  Integrations](https://platform.open.cx/settings/integrations) → Freshdesk as
  your first step. Most issues are credential or automation-rule related.
</Tip>

## Common scenarios

| Symptom                                                                                                    | Likely cause                                                                                                                                                                                 | Where to check                                                                                                                                                                                                   |
| ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AI never replies to any ticket                                                                             | Automation rules missing, or Rule 1 (Ticket Creation) doesn't fire the webhook                                                                                                               | Freshdesk **Admin → Workflows → Automations** — check both rules and their activity logs                                                                                                                         |
| AI replies to new tickets but not to customer follow-ups                                                   | Rule 2 (Ticket Updates) missing, or its events don't include **Reply is sent**                                                                                                               | Freshdesk **Admin → Workflows → Automations** → Ticket Updates rule                                                                                                                                              |
| AI replies to some tickets but not others                                                                  | Intake mode is assigned-only and those tickets aren't assigned to the OpenCX agent or in the default group                                                                                   | OpenCX [Freshdesk settings](https://platform.open.cx/settings/integrations) + Freshdesk assignment rules                                                                                                         |
| Tickets silently never appear and don't error in OpenCX (Freshdesk returns 403 "not authorized")           | The OpenCX agent's **ticket scope** is too narrow (Group or Restricted), so OpenCX can't read those tickets back from the API                                                                | Freshdesk **Admin → Agents → \[OpenCX agent] → Scope** — set to **Global Access**. Not checked at connect, so a restricted admin key looks connected but drops tickets                                           |
| Tickets assigned to the AI agent (via a queue) never appear; only ones that later get a reply or update do | Rule 2 (Ticket Updates) doesn't include **Agent is changed**, so the assignment itself never reaches OpenCX — or Freshdesk isn't firing automations for *automatic* (round-robin) assignment | Freshdesk **Admin → Workflows → Automations** → add **Agent is changed** to the Ticket Updates rule. If auto-assigned tickets still don't appear, assign the AI agent from a rule that also triggers the webhook |
| Handed-off tickets aren't routed by your automation                                                        | Marker field doesn't exist in Freshdesk, or your rules don't match it                                                                                                                        | Freshdesk **Admin → Workflows → Ticket fields** — create `cf_opencx_handed_off` as a checkbox                                                                                                                    |
| Tickets resolved in Freshdesk stay open in OpenCX                                                          | Rule 2 doesn't include **Ticket property changed (Status)**                                                                                                                                  | Freshdesk **Admin → Workflows → Automations** → Ticket Updates rule                                                                                                                                              |
| None of the above                                                                                          | Open a support request with the session ID, the Freshdesk ticket ID, and a short description                                                                                                 | [support@open.cx](mailto:support@open.cx)                                                                                                                                                                        |

### **Verification fails with "admin privileges" or a 403**

<Tooltip tip="OpenCX requires the API key of an admin agent — it needs the agents API to tell agents and contacts apart. Non-admin keys are rejected at verification.">
  Likely cause
</Tooltip>

: the API key belongs to a non-admin agent.

**Fix:** in Freshdesk, give the dedicated OpenCX agent the **admin** role (or copy the key from an admin agent's profile), then re-run **Verify**. The dialog shows the connected agent's name and email — confirm it's the dedicated OpenCX agent, not a person.

### **Verification fails with "failed to verify credentials"**

<Tooltip tip="Usually caused by including https:// in the domain, a typo in the subdomain, or a regenerated key that was never updated in OpenCX.">
  Likely cause
</Tooltip>

: wrong domain format or stale API key.

**Fix:** enter the plain domain (`yourcompany.freshdesk.com`, no `https://`) and re-copy the key from the OpenCX agent's **Profile settings → Your API Key**. Saved settings never display the key back — re-enter it whenever you change credentials.

### **Webhook rule exists but nothing reaches OpenCX**

<Tooltip tip="The Trigger Webhook action must be POST + JSON + Advanced content with the exact payload from the OpenCX dialog. A mangled payload delivers events OpenCX can't parse.">
  Likely cause
</Tooltip>

: payload edited by hand, or webhook URL stale after a disconnect/reconnect.

**Fix:** copy the current webhook URL and both payloads from [Settings → Integrations → Freshdesk](https://platform.open.cx/settings/integrations) and paste them verbatim into the automation rules. Check the rule's activity log in Freshdesk to confirm it fires. Also note: the webhook action requires a **Growth, Pro, or Enterprise** Freshdesk plan.

### **AI answered a ticket your team should own**

<Tooltip tip="With Auto Handle All Incoming Tickets on, the AI picks up every new ticket regardless of assignment.">
  Likely cause
</Tooltip>

: intake mode is auto-handle-all.

**Fix:** turn **Auto Handle All Incoming Tickets** off and route AI tickets explicitly — assign them to the OpenCX agent or move them into the configured **Default Group** with your Freshdesk rules. The gate only applies to new tickets; tickets the AI already picked up keep syncing.

### **Handoff left the ticket unassigned instead of going to your agent/group**

<Tooltip tip="If the configured handoff agent or group no longer exists, OpenCX falls back to unassigning and setting the marker — it never leaves a handed-off ticket on the AI.">
  Likely cause
</Tooltip>

: the configured handoff agent or group was deleted or is invalid.

**Fix:** reopen [Settings → Integrations → Freshdesk](https://platform.open.cx/settings/integrations) and re-select a valid **Handoff Agent ID** or **Handoff Group**. The fallback is by design — treat unexpected unassigned+marked tickets as a signal the target needs fixing.

### **Marker field warning on save**

<Tooltip tip="OpenCX warns (but does not block) when the selected handoff marker field doesn't exist as a ticket field in Freshdesk.">
  Likely cause
</Tooltip>

: `cf_opencx_handed_off` (or your selected field) hasn't been created in
Freshdesk.

**Fix:** create a **checkbox** ticket field under **Admin → Workflows → Ticket fields** with the API name matching your selection, then save again. Until it exists, handoff still routes — the marker is simply skipped, so automation rules keyed on it won't fire.

### **Customer replies appear in OpenCX but the AI stopped answering**

<Tooltip tip="Once a ticket is assigned to a human, OpenCX marks the session handed off and the AI stays silent — assignment is the on/off switch.">
  Likely cause
</Tooltip>

: the ticket is assigned to a human agent.

**Fix:** this is expected after handoff. To put the AI back on the ticket, reassign it to the OpenCX agent in Freshdesk — the AI resumes on the next customer message.

## Limits & timing

|                              | Value                                                                                                                               |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Webhook delivery retries** | Handled by Freshdesk — failed deliveries are retried automatically per Freshdesk's webhook policy                                   |
| **Rate limiting**            | OpenCX respects Freshdesk 429 responses and retries up to 3 times with backoff; trial Freshdesk accounts have low per-minute quotas |
| **Attachment size**          | 20 MB total per reply or note (Freshdesk limit)                                                                                     |
| **Backfill window**          | \~180 days of open/pending tickets, imported once on first connect                                                                  |

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Connect Freshdesk" icon="plug" href="/integrations/freshdesk/connect">
    Re-verify credentials, automation rules, and routing settings.
  </Card>

  <Card title="Ticket flow" icon="diagram-project" href="/integrations/freshdesk/tickets">
    Re-check how tickets match to sessions and how handoff lands.
  </Card>

  <Card title="Overview" icon="ticket" href="/integrations/freshdesk/overview">
    What the Freshdesk 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>