- Your Freshdesk and the email of the dedicated OpenCX agent whose you saved.
- A specific OpenCX session ID (from 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.
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 + Freshdesk assignment rules |
| 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 | [email protected] |
Verification fails with “admin privileges” or a 403
: 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”
: 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
: 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 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
: 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
: the configured handoff agent or group was deleted or is invalid. Fix: reopen Settings → Integrations → Freshdesk 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
: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
: 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
Connect Freshdesk
Re-verify credentials, automation rules, and routing settings.
Ticket flow
Re-check how tickets match to sessions and how handoff lands.
Overview
What the Freshdesk integration does and how it fits with your team.
Human handoff
Global handoff rules and office hours.