Connect Freshdesk ticketing

Create a dedicated OpenCX admin agent in Freshdesk, verify its API key, choose intake and handoff routing, and add two automation rules.

The Freshdesk integration uses the API key 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

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

   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.

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

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

6. Optional: additional AI agents

   By default the AI answers as the one connected agent. If different customers should see different names — one support persona per region or brand, say — create a Freshdesk agent for each persona, then tick them under Additional AI agents. The connected agent is always included.

   A ticket assigned to any ticked agent is handled by the AI and answered as that agent: its name on the reply, its own Freshdesk signature. Your Freshdesk assignment rules decide which persona a customer sees, so route each mailbox, group, or product to the matching agent. Reassigning a ticket from one AI agent to another switches the persona on the next reply; assigning it to a person still hands it off.

   Only agents in your Freshdesk account can be ticked. Give each persona agent its own name and signature in Freshdesk — OpenCX reads both from there.

7. Optional: assist-mode footer

   If you run

   assist mode

   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.

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

9. 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. Set Action performed by to Agent or requester (the default, Agent, silently drops customer replies), trigger on Agent is changed, Reply is sent, Note is added, and Ticket property changed (Status), add at least one condition (Freshdesk requires one; Source is any of Email works, but never a group or agent condition, since a new ticket is not assigned yet), 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.

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

Importing your ticket history

Once ticketing is connected, the Freshdesk dialog offers Import from Freshdesk. It brings your existing Freshdesk tickets into OpenCX as sessions, each with the customer’s first message and the full thread of replies and notes, attributed to the agents who wrote them. Closed tickets arrive closed, with their original dates.

Before anything starts, OpenCX checks the saved credentials against your account and shows what it found: how many tickets and contacts there are, whether the OpenCX agent can see every ticket, and whether your account archives old tickets. Fix anything that fails in Freshdesk, save the credentials again, and retry.

A few things to know:

• The import runs in the background and can take days for large accounts, because Freshdesk limits how quickly history can be read. You can close the dialog and check back.
• It never replies to anyone. Imported sessions are history, not new conversations, and nothing is sent to your customers or to Freshdesk.
• Running it again later only adds tickets that are new or changed since the previous run.
• If your Freshdesk plan archives tickets, closed tickets inactive for more than 120 days are not reachable and are not imported. The check tells you when this applies.
• File attachments are listed by name on each message but the files themselves are not copied.

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.

---

Related Documentation

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.