Connect Freshdesk ticketing

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

A dedicated OpenCX agent with admin privileges

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.

Ticket scope: Global Access (all tickets)

Set the agent’s Scope to Global Access (all tickets) under Admin → Agents → [the OpenCX agent] → Scope. This is separate from the admin role and is not checked at connect time — a restricted-scope admin key verifies fine, then silently fails: OpenCX reads each ticket back from the API, and Freshdesk returns 403 “You are not authorized to perform this action” for any ticket outside the agent’s scope, so those tickets never appear in your inbox.

Auto-handle-all intake → Global Access is required (the AI must read every new ticket).
Assigned-only intake → Global Access is still strongly recommended. “Group Access” works only if the AI agent belongs to every group whose tickets it receives; “Restricted (assigned tickets only)” reads only tickets already assigned to the agent and 403s on anything routed by group or default-group rules.

Permission to create automation rules

Webhook delivery runs through two automation rules you create under Admin → Workflows → Automations. Only Freshdesk admins can create them.

Owner or admin in OpenCX

Required to save integration settings in Settings → Integrations.

Required permissions

The API key inherits the OpenCX agent’s role and scope. The agent must be able to do everything below — granting admin + Global Access scope covers all of it in one step.

Capability	Why OpenCX needs it	Enforced at connect?
Admin role	Read agents (`/agents`) to tell agents from contacts and attribute replies/notes correctly	✅ Yes — non-admin keys are rejected
Global Access ticket scope	Read every ticket the AI must handle (`GET /tickets/{id}`); a narrower scope 403s on out-of-scope tickets	❌ No — verify silently passes, then tickets vanish at runtime
Reply to tickets & add notes	Post AI replies (autopilot) and private drafts (assist mode)	❌ No
Edit ticket properties & assign tickets	Sync tags/status, set the handoff marker field, and route handoffs to an agent or group	❌ No
Read contacts	Resolve the requester’s name/email for the session	❌ No
Create automation rules	Build the two Trigger Webhook rules that push events to OpenCX	❌ No (Freshdesk-side)

Only the admin check runs at connect — ticket scope is not verified. A Global-Access admin is the safe default; anything narrower connects successfully and then silently drops tickets with a 403. If tickets stop appearing, check the agent’s Scope first.

Setup

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.

Open Freshdesk in OpenCX

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

Enter and verify your credentials

Field	Value
Domain	Your Freshdesk domain — for example `yourcompany.freshdesk.com`. Include the full domain, do not prefix with `https://`.
API Key	The 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.

Pick an intake mode

The Auto Handle All Incoming Tickets toggle controls which new tickets the AI picks up.

Auto-handle all incoming tickets (toggle on)

The AI answers every new ticket regardless of assignment. Use this when the AI is the front door to your helpdesk.

Assigned-only (toggle off)

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.

Choose the handoff routing

Choose what OpenCX should do in Freshdesk after the AI hands off to a human.

Routing	What happens	When 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 route	OpenCX 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 agent	OpenCX 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 group	OpenCX 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:

Field	Value
Label	`OpenCX handed off`
Internal/API name	`cf_opencx_handed_off`
Type	Checkbox

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.

Optional: assist-mode footer

If you runon 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.

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.

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",
  "assigneeId": "{{ticket.agent.id}}",
  "groupId": "{{ticket.group.id}}",
  "requesterEmail": "{{ticket.contact.email}}",
  "requesterName": "{{ticket.contact.name}}",
  "requesterPhone": "{{ticket.contact.phone}}"
}

Rule 2 — Ticket Updates tab. Trigger on Agent is changed, Reply is sent, Note is added, and Ticket property changed (Status), and paste Payload 2:

{
  "ticketId": "{{ticket.id}}",
  "triggered_event": "{{Triggered event}}",
  "assigneeId": "{{ticket.agent.id}}",
  "groupId": "{{ticket.group.id}}",
  "requesterEmail": "{{ticket.contact.email}}",
  "requesterName": "{{ticket.contact.name}}",
  "requesterPhone": "{{ticket.contact.phone}}"
}

These optional fields are performance hints, not requirements:

assigneeId / groupId let OpenCX skip tickets that aren’t for the AI agent without an extra API call.
requesterEmail / requesterName / requesterPhone let OpenCX identify the customer without a separate contact lookup.

They’re safe to include even if your Freshdesk plan doesn’t expose a placeholder — unresolved or empty values are ignored, and OpenCX always re-reads the ticket from the API before acting.

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.

Assigned-only intake with a shared queue? If the AI agent receives tickets through Freshdesk’s automatic assignment (round-robin / load-balanced queue) rather than being assigned at creation, the Agent is changed trigger on Rule 2 is what tells OpenCX the ticket is now the AI’s. Without it, newly assigned tickets only surface when a later reply or status change happens. Note that Freshdesk may not fire automation rules for assignments performed by automatic assignment — if auto-assigned tickets still don’t appear, assign the AI agent from a rule that also triggers the webhook, or have that rule fire on creation. Verify with a manual reassignment first: it should produce a ticket in your OpenCX inbox within seconds.

Create a test ticket

Open a ticket as an end user (or use the Freshdesk portal). Within a few seconds:

A new session appears in your OpenCX Inbox — email tickets land on the Email channel, portal/chat tickets on Web, phone tickets on Phone.
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.

Overview

Ticketing Systems

E-commerce

Other Integrations

Connect Freshdesk ticketing

Before you start

Required permissions

Setup

Rotating the API key

Disconnecting

Ticket flow

Troubleshooting

Overview

Human handoff

​Before you start

​Required permissions

​Setup

​Rotating the API key

​Disconnecting

​Related Documentation

Ticket flow

Troubleshooting

Overview

Human handoff

Before you start

Required permissions

Setup

Rotating the API key

Disconnecting

Related Documentation