Skip to main content
The Freshdesk integration uses the of a dedicated OpenCX agent to read and write tickets, plus two Freshdesk automation rules that push ticket events back to OpenCX.
Setup takes about 15 minutes. You need admin access in both Freshdesk and your OpenCX organization, and a Freshdesk Growth, Pro, or Enterprise plan — the webhook automation action isn’t available on the free plan.

​
Before you start

Create a dedicated agent in Freshdesk (for example OpenCX AI) and give it admin privileges. The AI posts replies as this agent, so customers see its name on every AI message — don’t reuse a person’s account. Admin is a hard requirement: OpenCX needs it to tell agents and contacts apart at runtime, and verification rejects non-admin API keys.
Webhook delivery runs through two automation rules you create under Admin → Workflows → Automations. Only Freshdesk admins can create them.
Required to save integration settings in Settings → Integrations.

​
Setup

1

Copy the OpenCX agent's API key

Log in to Freshdesk as the dedicated OpenCX agent, open Profile settings, and copy Your API Key.See Freshdesk’s API key guide if the page has moved.
The key is bound to that agent. If the agent is deactivated or loses admin privileges, the integration stops working.
2

Open Freshdesk in OpenCX

In your OpenCX dashboard, go to Settings → Integrations and select Freshdesk.
3

Enter and verify your credentials

FieldValue
DomainYour Freshdesk domain — for example yourcompany.freshdesk.com. Include the full domain, do not prefix with https://.
API KeyThe OpenCX agent’s API key you just copied.
Click Verify. OpenCX calls the Freshdesk API, confirms the key belongs to an admin agent, and shows the connected agent’s name and email so you can confirm it’s the right account. A wrong domain, bad key, or non-admin agent returns an error and nothing persists.
4

Pick an intake mode

The Auto Handle All Incoming Tickets toggle controls which new tickets the AI picks up.
The AI answers every new ticket regardless of assignment. Use this when the AI is the front door to your helpdesk.
The AI only answers new tickets that Freshdesk has assigned to the OpenCX agent, or that land in the Default Group you select. Use this when your existing Freshdesk routing rules decide which tickets go to the AI.
The gate applies to new tickets only — once OpenCX is tracking a ticket, status and replies keep syncing even after handoff.
5

Choose the handoff routing

Choose what OpenCX should do in Freshdesk after the AI hands off to a human.
RoutingWhat happensWhen to use it
Unassign ticket (default)OpenCX removes the OpenCX agent from the ticket and reopens it.Use this when your team works from the unassigned queue or manually triages handoffs.
Let Freshdesk automation routeOpenCX unassigns the ticket and sets the handoff marker field — routing only happens if you have an automation rule keyed on the marker.Use this when routing should stay inside Freshdesk rules and queues.
Assign to a specific agentOpenCX assigns the ticket to the Handoff Agent ID you enter and sets the marker.Use this for a fixed fallback agent or small teams without routing automation.
Assign to a groupOpenCX assigns the ticket to the Handoff Group you select and sets the marker.Use this when a team queue should receive handoffs.
For the marker-based routings, OpenCX sets a custom checkbox ticket field on handoff. Create it in Freshdesk under Admin → Workflows → Ticket fields:
FieldValue
LabelOpenCX handed off
Internal/API namecf_opencx_handed_off
TypeCheckbox
Then select it as the Handoff Marker Field in OpenCX. If you point your automation at the marker, make sure those rules never route marked tickets back to the OpenCX agent.
If a configured handoff target becomes invalid later (agent deleted, group removed), OpenCX never leaves a handed-off ticket assigned to the AI — it falls back to unassigning and setting the marker so your rules can still catch it.
6

Optional: assist-mode footer

If you run on any channel, the AI posts drafts as private notes. The Assist Mode Footer text is appended to each draft so reps can tell AI drafts from human notes at a glance.
7

Save and copy your webhook URL

Click Save. OpenCX validates the credentials again, stores the settings, and displays a Webhook URL unique to your organization, plus the two JSON payloads for the next step.On first connect, OpenCX also runs a one-time backfill: open and pending tickets from the last ~180 days are imported into your inbox as history. The backfill never triggers AI replies on old tickets.
The webhook URL contains a signed token tied to your organization. Anyone with it can post events into your OpenCX pipeline. Treat it like a password.
8

Create the two automation rules in Freshdesk

In Freshdesk, open Admin → Workflows → Automations and create two rules. Both use the action Trigger Webhook with request type POST, encoding JSON, content Advanced, pointing at your OpenCX webhook URL.Rule 1 — Ticket Creation tab. Trigger on ticket creation and paste Payload 1 from the OpenCX dialog:
{ "ticketId": "{{ticket.id}}", "triggered_event": "ticket_created" }
Rule 2 — Ticket Updates tab. Trigger on Reply is sent, Note is added, and Ticket property changed (Status), and paste Payload 2:
{ "ticketId": "{{ticket.id}}", "triggered_event": "{{Triggered event}}" }
Without Rule 1, the AI never sees new tickets. Without Rule 2, customer replies don’t reach the AI and status changes in Freshdesk don’t sync back to OpenCX.
9

Create a test ticket

Open a ticket as an end user (or use the Freshdesk portal). Within a few seconds:
  1. A new session appears in your OpenCX Inbox — email tickets land on the Email channel, portal/chat tickets on Web, phone tickets on Phone.
  2. The AI’s answer appears on the Freshdesk ticket as the OpenCX agent — a public reply in autopilot, a private note in assist mode.
If nothing appears, jump to Troubleshooting.

​
Rotating the API key

If you regenerate the OpenCX agent’s API key in Freshdesk, paste the new key into Settings → Integrations → Freshdesk and save. The saved key is never displayed back — the field is blank on edit and you re-enter it to change credentials. The webhook URL does not change when you rotate the key.

​
Disconnecting

In OpenCX, open the Freshdesk integration and click Disconnect. Then in Freshdesk, delete the two automation rules. Tickets already imported stay in your OpenCX inbox; no new Freshdesk events flow in, and the AI stops posting on tickets.

Ticket flow

How tickets match to sessions, how handoff routes them, how resolutions sync.

Troubleshooting

Verification failing, webhook silent, handoff not routing.

Overview

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

Human handoff

Global handoff rules and office hours.