; }; 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 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**. 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. 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](https://platform.open.cx/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 Log in to Freshdesk **as the dedicated OpenCX agent**, open **Profile settings**, and copy **Your API Key**. See [Freshdesk's API key guide](https://support.freshdesk.com/en/support/solutions/articles/215517) 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. In your OpenCX dashboard, go to [**Settings → Integrations**](https://platform.open.cx/settings/integrations) and select **Freshdesk**. | 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. 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. 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. 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. 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. 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: ```json theme={"dark"} { "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: ```json theme={"dark"} { "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. 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](https://platform.open.cx/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](/integrations/freshdesk/troubleshooting). ## Rotating the API key If you regenerate the OpenCX agent's API key in Freshdesk, paste the new key into [Settings → Integrations → Freshdesk](https://platform.open.cx/settings/integrations) 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 How tickets match to sessions, how handoff routes them, how resolutions sync. Verification failing, webhook silent, handoff not routing. What the Freshdesk integration does and how it fits with your team. Global handoff rules and office hours.