Freshdesk in Agent Builder

The Freshdesk step lets an agent read and change records in your Freshdesk helpdesk as part of a run. It can list the inbox, search for urgent tickets, fetch one ticket and its thread, reply to the customer, or add a private note. Each step does one thing, picked from 52 actions, and hands what Freshdesk sends back to the next step. The same connection also drives the Freshdesk webhook trigger, which starts an agent when a ticket is created or updated.

app.centrus.ai/app/agents/workflow-builder

Agents

Build modular AI workflows with reusable nodes

Urgent tickets digest

1,240 / 10,000 creditsValidateResetRunsSettingsUpdate & Publish

Weekdays at 08:00

Daily at 08:00 · Mon, Tue, Wed, Thu, Fri

Open urgent tickets

Search tickets · priority:4 AND status:2

2

Write the digest

GPT-5.6 Terra

Email the desk

1 action enabled

AI builderMap

1. 1Freshdesk in the Integration group of the Nodes panel.
2. 2The step on the canvas. Its summary shows the action, Search tickets, and the query.
3. 3Connection: the Freshdesk account this agent uses, shown by the name of the agent the API key belongs to.
4. 4Endpoint: the action the step performs, chosen from the full list.
5. 5The action's fields. Here the query asks for urgent open tickets.

Centrus works alongside Freshdesk. Tickets, contacts and companies stay in Freshdesk, and the agent reads and updates them there. A new ticket can raise a job in BigChange, a weekday morning run can email a digest of open urgent tickets, and a finished job can add a private note back on the ticket. Those three agents are under Example agents. To ask about tickets in a conversation rather than in an agent, see Freshdesk in chat. For how every integration is connected, see Integrations overview.

Open the agent in Agent Builder and find Freshdesk in the Integration group of the Nodes panel, under Ostara and above Fixflo. Drag it onto the canvas and connect the step before it to its left-hand side. Until you choose an action, its summary on the canvas reads No endpoint selected.

New ticket

Ticket created

Freshdesk

No endpoint selected

2

1. 1Freshdesk in the Integration group. Drag it onto the canvas.
2. 2The new step. It reads No endpoint selected until you choose an action in its Details panel.

On a phone, Agent Builder shows the canvas only. The Nodes panel is hidden on screens narrower than 768 pixels and the Details panel on screens narrower than 1,024 pixels, so you can follow an agent's steps on a phone but need a tablet or computer to add a Freshdesk step or change its settings.

09:41

Centrus

Agents

Build modular AI workflows with reusable nodes

Chase overdue invoices

Save and Publish

Weekdays at 08:00

Daily at 08:00 · Mon, Tue, Wed, Thu, Fri

Open urgent tickets

Search tickets · priority:4 AND status:2

Write the digest

GPT-5.6 Terra

Email the desk

1 action enabled

The Freshdesk connection belongs to this agent alone. It is separate from the Freshdesk connection in chat, so connecting one does not connect the other. One connection covers every Freshdesk step in the agent and its Freshdesk webhook trigger, so you only connect once per agent.

You need two values: the Subdomain and an API key. The subdomain is the Freshdesk address, for example meridianfm.freshdesk.com, or just meridianfm. Centrus accepts the full address or that label, and stores it in lower case. The key is the agent API key under that agent's Profile settings in Freshdesk. The key is stored on this agent only. If you cannot see Profile settings, ask your Freshdesk administrator for a key.

1. 1Save the agent with Save draft. Until it has been saved once, the Connection section reads Save this workflow as a draft first, then connect the account. and Connect is greyed out.
2. 2Select the Freshdesk step. In the Details panel, open Connection and click Connect.
3. 3In the Connect Freshdesk window, enter the Subdomain and API key, then click Connect.
4. 4Centrus asks Freshdesk who the key belongs to. If Freshdesk accepts it, Connection reads Connected, followed by that agent's name. If Freshdesk returns no name, you see the subdomain instead.

Centrus checks the two values when you click Connect. If either field is empty, nothing is saved and you see Freshdesk subdomain and API key are required. If the address is not a Freshdesk subdomain, or Freshdesk rejects the key, nothing is saved and you see the error. A rejected key comes back as Could not verify Freshdesk credentials. Try the agent with a dry run straight after connecting, as described under Test before it goes live.

Reusing a connection. If you have already connected Freshdesk on another agent you created, choose that agent under Copy from existing agent. Centrus fills in the two fields from it, and you click Connect to save them on this agent. The list only shows agents you created that are not archived and have a Freshdesk connection, so an agent someone else shared with you never appears. When there are none, the box reads No other agents with this connection.

Sharing and copying the agent. When you share an agent, its Freshdesk connection stays with it, and everyone who runs it uses that connection rather than their own. When you duplicate an agent, the steps are copied but the connection is not, so connect Freshdesk again on the copy. Copy from existing agent makes that quick. For the details, see Share an agent.

Disconnecting. Disconnect removes the credentials from this agent only, including the webhook secret. Its Freshdesk steps and trigger stop working until someone connects it again. Connecting again creates a new secret, so paste that new secret into Freshdesk if a rule there already points at this agent. Other agents keep their own connections. Connecting again without disconnecting first keeps the same secret.

Select the step and open Endpoint in the Details panel. The section's own line reads Choose the Freshdesk action this step should run. Endpoint tool type holds all 52 actions in one list that starts with List tickets. The list has no search box and no headings, so the tables at the end of this guide are the quickest way to find the exact name you need.

Keep Set endpoint fields here. Let AI populate endpoint fields hides the fields so that an AI can fill them, but on a step in the agent's main flow nothing fills them in when the step runs. To have an AI choose the values, attach the step to an AI step as a tool instead, as described below.

Each action then shows its own fields in a box titled with the action's name. The label on a field is the first sentence of its description, and a required field has an asterisk. Where a field has no description, the label is the name Freshdesk uses, with a capital letter, so you will see Body, Email and also Requester_id and To_emails. Search tickets has one required field, labelled Freshdesk search query, for example status:2. That query is Freshdesk's own search language, not the inbox filter on List tickets. Priority 4 is urgent and status 2 is open, so priority:4 AND status:2 is the open urgent tickets in the digest.

To use a value from an earlier step, open Step data references at the top of the Details panel and click a field to copy its reference, then paste it into a text field. Body on Add note is text, so it can hold the job reference from a BigChange step, written {{ steps.integration-bigchange_rest-1791540900000-3.json.reference }}. Freshdesk ticket id is a number field, so a reference pasted into it is turned into a number and lost. Use a fixed ticket id when you are testing one ticket, or attach the step to an AI step as a tool so the AI can supply the id.

Add note is private unless private is set to false. The checkbox is labelled Defaults to true and looks off until you touch it. Leave it untouched for a private note: an untouched note is still private. Switching the checkbox off makes the note visible to the customer. Reply is always visible to the customer, and plain text is sent as HTML. Update conversation can edit a note, and cannot edit a customer reply.

What the step passes on. When the step runs, it passes on what Freshdesk returned as items for the next step. Get ticket passes on one item, the ticket. A list or search passes on one item per record, so four tickets become four items. Later steps reach their fields through Step data references, and an AI step reads all of the items together. To change one record for each item, put the step inside a Loop, described in Conditions, loops and approvals.

As a tool for an AI step. Connect a Freshdesk step to the Tools side of an Intelligence step and its Details panel changes. Instead of one endpoint, Actions lets you choose several, with a search box, and the AI decides when to call each one and fills in the fields itself. The step's summary on the canvas lists up to three actions, then shows the first one and a count if there are more, such as Add note +2.

Job finished

Job status changed

Fetch the job

Get job

Write the note

GPT-5.6 Terra

Note the ticket

Add note, Get ticket, List conversations

1

1. 1The Freshdesk step attached to the Intelligence step as a tool.
2. 2Actions: the Freshdesk actions the AI may call.
3. 3Pause for approval: each call the AI makes waits for someone to approve it in the Runs panel.

Pause for approval appears on every Freshdesk step but only applies to calls an AI makes, so it has no effect on a step in the main flow. To ask someone before a main-flow step changes Freshdesk, put an Approval step in front of it. Do not give an Intelligence step a list or a search, such as List tickets, Search tickets, List contacts or List companies. Centrus warns you, because the whole list would be loaded into the AI. Use the Ingest step for those, as described under Limits and good to know.

The Freshdesk webhook trigger, in the Trigger group of the Nodes panel, starts the agent when Freshdesk reports a ticket you have ticked, such as a ticket being created. It uses the agent's Freshdesk connection, so if a Freshdesk step is already connected, the trigger is too. Setting up, testing and costs for every system are covered in Start an agent from a system alert. This section covers what is particular to Freshdesk.

New ticket

Ticket created

Raise the job

GPT-5.6 Terra

Create the job

Create job

1. 1Connection, shared with the agent's Freshdesk steps.
2. 2Event types: the events that start a run. Only Ticket created is ticked.
3. 3Set this up in Freshdesk: the steps to follow in Freshdesk, the address, the secret and the rule bodies.
4. 4Simulate webhook: runs the agent once with a sample alert.

Every event it can listen for. There are 3 event types in one group. Tick only the ones the agent needs, because each alert that matches starts a run and each run uses credits. Any ticket delivery matches either a creation or an update. Ticket created matches a creation only. Ticket updated matches an update only. Ticking Any ticket delivery as well as Ticket created still starts one run for a new ticket, not two. Under each label the screen also shows a short code, such as ticket.created.

Who sets it up, and where. The Centrus side is done by anyone who can edit the agent. The Freshdesk side needs an administrator, because the alert is an automation rule whose action is Trigger Webhook. Centrus does not create that rule. Set this up in Freshdesk lists the steps, and the order of the rules in Freshdesk matters:

1. 1Connect Freshdesk on the trigger and save the agent. Copy the Secret. It stays the same if you connect again over this connection. If you click Disconnect first, the next connect creates a new secret, and the rule in Freshdesk must be updated.
2. 2In Freshdesk, go to Admin, then Workflows, then Automations. On Freshdesk Omni, it is Admin Settings, then Configuration and Workflows, then Ticket Automations.
3. 3On the ticket creation tab, add a rule with a condition that matches the tickets you want. The action is Trigger Webhook, POST, JSON, Advanced content. Paste the Callback URL. Paste the Custom headers line as one pair per line, and leave Requires authentication off. The body is the Creation rule body, with kind set to the word created.
4. 4On the ticket updates tab, set the performer to Agent or requester. Add a second rule with System only if an overdue ticket or a mail failure should start an agent. Use the same address, the same header and the Updates rule body, with kind set to the word updated.
5. 5Place each rule where Freshdesk will reach it. If the tab is set to Execute first matching rule, an earlier rule can stop yours running. Move it up, or switch the tab to Execute all matching rules.
6. 6A second agent on the same helpdesk has its own secret, so it needs its own rule, with that secret.

The Callback URL is https://api.centrus.ai/agent-builder-v2/webhooks/freshdesk. Every organisation uses that same address. Centrus tells the agents apart by the secret in the header X-Centrus-Webhook-Secret. Until Freshdesk is connected, the secret box reads Connect Freshdesk to generate the secret. The Custom headers line is that header and the secret, ready to paste. Creation rule body and Updates rule body are the JSON to paste. Each includes the ticket id, kind, subject, description, status, priority, source, the requester's email, the latest public comment and when the ticket changed, filled from Freshdesk's own placeholders. Keep those placeholders. Kind must stay the word created or updated. Status in the body is the number: open is 2, pending is 3, resolved is 4, closed is 5. Priority runs from 1, low, to 4, urgent.

What the trigger hands on. Each alert becomes one item for the next step, with ticket_id, kind (created or updated), subject, description, status, priority, source, requester_email, latest_public_comment and modified_on. The usual next step can read the subject and description straight from the alert, which is enough to raise a BigChange job. For anything else, add Get ticket. Its Freshdesk ticket id field only accepts a number, so attach Get ticket to an Intelligence step as a tool and let the AI pass {{ trigger.json.ticket_id }}, or type a fixed id while you test. An update with no modified_on is dropped, so the updates rule body has to include it. The same delivery is not run twice. A later update, with a new modified time, starts another run.

Simulating an alert. Once the agent is saved, Simulate webhook runs it once for the event type and Ticket id you enter. Ticket updated also needs modified_on, in the form the box shows, or the button stays greyed out and Centrus asks you to Provide modified_on when simulating a ticket update. An empty ticket id asks you to Provide a ticket id to simulate against. Use the id of a real ticket if a later step will fetch it. The simulate itself does not call Freshdesk: it only starts the agent with that ticket id, and empty subject, description and status. Steps after it do call Freshdesk, and write actions change tickets. A simulated alert is a real run rather than a dry run, and the run uses credits. Alerts from Freshdesk only start runs once the agent is published. Simulate webhook and Run now work on a saved draft.

New ticket

Ticket created

Raise the job

GPT-5.6 Terra

Create the job

Create job

Email the desk

1 action enabled

Ticket to a job raises a BigChange job when someone opens a ticket. New ticket is a Freshdesk webhook with Ticket created ticked, and the creation rule in Freshdesk limited to the tickets you care about, such as repairs for Northgate Housing. The alert already holds the subject, the description and the requester's email, for example ticket 48219, "No heating at Riverside House", from Priya Shah. Raise the job reads that and calls Create the job, a BigChange REST step attached as a tool, so the AI can supply the BigChange contact and site. Email the desk tells Sarah Price the job reference. Each new ticket costs five credits or a little more. BigChange's side of Create job is in BigChange REST in Agent Builder.

Weekdays at 08:00

Daily at 08:00 · Mon, Tue, Wed, Thu, Fri

Open urgent tickets

Search tickets

Write the digest

GPT-5.6 Terra

Email the desk

1 action enabled

Urgent tickets digest emails the desk a summary of open urgent tickets at 08:00 each weekday. Open urgent tickets uses Search tickets with the query priority:4 AND status:2, and passes on one item per ticket. Write the digest reads them together, names the site and how long the ticket has been open, and Email the desk sends the result to John Martin. The search costs 1 credit however many tickets it returns, up to the one page the step asks for. A morning list like this is a schedule, not a Freshdesk alert: hourly rules in Freshdesk cannot call a webhook.

Job finished

Job status changed

Fetch the job

Get job

Write the note

GPT-5.6 Terra

Note the ticket

Add note, Get ticket, List conversations

Note when the job is done adds a private note to the ticket when the visit is finished. Job finished listens for Job status changed, with BigChange's status filter set to the completed statuses. Fetch the job loads the job, including the ticket number written into the job when it was raised. Write the note has the Freshdesk step Note the ticket as a tool, with Add note, Get ticket and List conversations chosen. The AI reads the ticket number from the job and passes it as a number, which a field on the main flow cannot do. Add note stays private. Pause for approval is on, so each note waits for someone to approve it in the Runs panel before it is written.

A dry run is the safe way to try a Freshdesk step. Open Runs in the toolbar, click Run now and choose Dry run (no actions performed). Read actions such as Search tickets, Get ticket and List conversations call Freshdesk for real, so you see real tickets. Write actions, such as Reply, Add note, Create ticket and Delete ticket, are skipped, and the step's summary starts with DRY RUN and says what it would have done, so nothing in Freshdesk changes. Run for real performs every action, including the writes.

{
  "handles": { "main": 4 },
  "items": {
    "main": [
      {
        "id": 48219,
        "subject": "No heating at Riverside House",
        "status": 2,
        "priority": 4,
        "requester_email": "priya.shah@northgatehousing.co.uk"
      }
    ]
  }
}

Open a step in the run to see its output. The panel shows the first 50 items of each output, and later steps still receive all of them. A dry run costs 1 credit for the whole run. A simulated Freshdesk alert is not a dry run, so test write actions with Run now first. For Run now, dry runs and the Runs panel in full, see Test an agent before it goes live.

A Freshdesk step costs 1 automation credit each time it runs successfully, whatever the action and however many tickets it returns. A step that fails costs nothing. When the step is a tool, each call the AI makes costs 1 credit. The Freshdesk webhook trigger is free, but every run it starts costs 1 credit, like any other run.

Inside a Loop, the step is charged on every pass, so a Loop over 40 tickets that adds a note to each one costs 40 credits for that step. A single search is usually cheaper than fetching tickets one at a time. For allowances, limits and how to see what each run cost, see Automation credits and usage limits.

• One page at a time. A Freshdesk step asks for a single page of up to 100 records. You cannot set the page count on the step. Search tickets, Search contacts and Search companies will not go past 10 pages even if something asks for more. List conversations stops at 20 pages, ticket time entries at 20, account time entries and satisfaction ratings and agents at 50, contacts and companies at 100, and List tickets at 300. For a longer list, use the Ingest step, described under Large lists. Do not attach a list or a search to an Intelligence step.
• List tickets defaults to 30 days. With no ISO time (the updated-since field), List tickets returns the last 30 days. Put an ISO time in that field for older tickets. The inbox filter is new_and_my_open. The other filters are watching, spam and deleted. That filter is not a search: for urgent open tickets, use Search tickets.
• Status and priority are numbers. On Create ticket, status is 2 open, 3 pending, 4 resolved, 5 closed. Priority is 1 low through 4 urgent. The same numbers come back on a ticket and on an alert.
• Notes, replies and time. Add note is private unless private is false. Reply is visible to the customer. Create time entry writes the time as hours and minutes, such as 01:30, and billable defaults to on. Toggle timer allows one running timer per agent. Delete time entry cannot be restored.
• Deletes. Delete ticket moves a ticket to the trash. Restore ticket brings it back. Soft-delete contact moves a contact to the deleted state and is not a hard wipe. Delete conversation removes that conversation.
• Admin key. Get agent, List agents, Autocomplete agents and List canned folders need an admin API key. Current agent uses the key you connected, and does not.
• Busy periods. If Freshdesk says it is receiving too many requests, Centrus waits for the time Freshdesk asks, between 1 and 30 seconds, tries once more, and then the step fails.
• Per-user integration mode. Freshdesk has no per-user credentials. In per-user mode the Connection section says the step still uses the agent's own connection.
• Number fields. Freshdesk ticket id and the other id fields only take numbers, so they cannot hold a reference to an earlier step. Text fields such as Body, Subject and the search query can. See Choose an action.
• Writing back can start the agent again. A step that updates the ticket you are watching can fire the update rule. Do not write to that ticket from this agent unless a Filter step ignores that write.
• Hourly rules. An hourly rule in Freshdesk cannot call a webhook. Use a schedule for a morning digest, or for tickets that have had no reply for a number of hours.
• Published agents only. Alerts only start runs once the agent is published. Simulate webhook and Run now work on a saved draft.
• Companies by prefix. Autocomplete companies matches the start of the name, not a word in the middle. Use Search companies for a wider search.

• Freshdesk is not connected on this automation. Open the step's Connection section and click Connect. If you have duplicated the agent, the copy needs its own connection. A Freshdesk connection in chat does not count.
• Freshdesk subdomain and API key are required. One of the two fields was empty. Connect does not save until both are filled in.
• Could not verify Freshdesk credentials. Freshdesk rejected the API key, or could not be reached. Check the key under the agent's Profile settings, then try Connect again. Nothing was saved.
• The address was refused. The subdomain may contain only letters, numbers and hyphens. Use meridianfm or meridianfm.freshdesk.com, not a different website. Nothing was saved.
• Stored Freshdesk credentials are incomplete. The saved connection is missing the subdomain or the key. Disconnect, then connect again with both.
• Freshdesk returned 401. The key is no longer accepted. Disconnect and connect again with a current key.
• Freshdesk returned 404. The record does not exist or the id is wrong. Check the ticket id. A number field will not have kept a reference you tried to paste in.
• Freshdesk requires ticket_id. The action needs a ticket id and the field was empty. Type the id, or let an AI pass it by using the step as a tool.
• The step still says No endpoint selected. It has no action yet. Choose one under Endpoint tool type.
• An alert never starts the agent. Check that the agent is published, Freshdesk is connected on the trigger, the event is ticked, and the rule in Freshdesk uses the same Callback URL, the Custom headers line and the right rule body. For Ticket updated, the body must include modified_on. If the tab runs the first matching rule only, an earlier rule may be stopping yours.
• Freshdesk shows a success but nothing runs. Freshdesk can count the delivery as a success even when Centrus turns the event away. Check the header line, that the content is the Advanced JSON from the node, and that the placeholders are still in the body.
• Provide a ticket id to simulate against. Simulate webhook needs a real ticket id. Ticket updated also needs modified_on.
• No other agents with this connection. None of the agents you created has a Freshdesk connection. Enter the two values by hand.
• A field will not take a reference. It is a number field. Use a fixed number, or let an AI fill it by using the step as a tool.
• A list stops at one page. That is the limit for one Freshdesk step. Use Ingest for more.

The Freshdesk step offers 52 actions: 31 read from Freshdesk and 21 change it. Every call goes to https://{subdomain}.freshdesk.com/api/v2, and the path below is added to that. Get ticket on ticket 48219 is GET /tickets/48219.