Menu

Mattering Automations Freshdesk integration

Connect Freshdesk to Mattering Automations: tickets, the filter query language, conversation threads, contacts, companies, the knowledge base, and time entries as workflow steps, authenticated with your account domain plus an agent API key.

The Mattering Automations Freshdesk integration adds your helpdesk to the automation canvas: list and search tickets, read whole conversation threads, create and update tickets, post private notes or public replies, manage contacts and companies, discover the ticket and contact field schemas your account actually uses, log time, read satisfaction ratings, and draft knowledge base articles.

Setup takes a few minutes: copy an agent API key from Freshdesk, attach it with your account domain as a credential in Mattering, and test the connection. One detail catches almost everyone and is covered in full below: the connect form shows generic Username and Password labels, and the username is your Freshdesk domain while the password is the API key.

The safety model is built into the node names. Freshdesk: Reply to Ticket (Emails Requester) sends a real email to the ticket requester the moment it succeeds, and a sent reply cannot be unsent, so it is named for its side effect. Freshdesk: Add Note to Ticket is the safe path for automation commentary: notes are private by default, visible to agents only, and send the requester nothing. Both delete nodes are soft deletes with restore nodes behind them.

Before you start

  • A Freshdesk account on a freshdesk.com domain. The v2 API works only via Freshdesk domains and not via custom CNAMEs, so a vanity support domain cannot be used as the credential's domain value. You also need a plan that includes API access. Freshdesk documents the API key and the API functionality as unavailable on its free tier, and its published rate limit table covers only the paid plans, so plan on a paid plan or the 14 day trial. The trial needs no credit card and is rate limited to 50 calls per minute.
  • An agent account whose Profile Settings page you can open, to copy its API key. Create a dedicated integration agent rather than using a person's key: the key acts as that agent and carries exactly that agent's permissions.
  • Admin privileges on that agent if your automations need the agent list or canned responses. Every Agent API except the currently authenticated agent read requires admin privileges, and the canned response APIs are documented as admin only.
  • A Mattering workspace with access to the Automations app.

Get your Freshdesk domain and API key

Mattering authenticates to Freshdesk with HTTP Basic auth using a personal agent API key, sent to your own account host. That means the credential has two parts, the account domain and the key, and both are stored on one generic credential type whose fields are labeled Username and Password.

Note your account domain. It is the examplecorp in examplecorp.freshdesk.com, the first part of the URL you use to reach your helpdesk. There is no shared API host for v2: every request goes to https://your-domain.freshdesk.com/api/v2, which is why the domain is part of the credential.
Sign in to Freshdesk as the agent the automations should act as, ideally a dedicated integration agent rather than a person.
Open that agent's Profile Settings page and find the API key, shown below the change password section. Copy it.
The field mapping is the one thing to get right: username is the DOMAIN, password is the API KEY. The stored username is not what goes on the wire. Mattering uses the domain only to build your account host, and builds the authorization header itself as base64 of the API key plus a dummy password, which is exactly the convention Freshdesk's own docs specify with curl -u yourapikey:X (the docs note you can use any set of characters as a dummy password). Keeping the key in the password field also means the secret is the part that gets redacted, while the non-secret domain stays readable. Pasting a full helpdesk URL such as https://examplecorp.freshdesk.com/a/tickets into the username field is tolerated: the connector normalizes it down to examplecorp.
An API key acts as its agent, with that agent's permissions and that agent's name on anything it writes. A note or a reply posted through this integration is attributed to the key's agent, so a dedicated integration agent keeps the audit trail honest and lets you revoke access without disturbing a person's login.

Connect Freshdesk to Mattering

In Mattering Automations, open Connectors and click Add Connector.
Choose Freshdesk from the list.
Click Create new credential. Enter your account domain in the Username field and your agent API key in the Password field, then save.
The credential is stored encrypted in Google Secret Manager and never appears in workflow logs.
Click Test Connection. Mattering builds your account host from the domain and calls the currently authenticated agent endpoint, which is the one Agent API that needs no admin privileges, so it works for any agent's key. A success message names the agent the key belongs to.
Click Connect. All 38 Freshdesk nodes appear in your canvas palette.

Verify it works

After connecting, open any automation canvas and check the palette: a Freshdesk section should list the query and action nodes. Drop Freshdesk: Get Current Agent onto the canvas and run a test step. It takes no parameters and is a safe, read-only call, and it exercises both halves of the credential at once, the domain (by resolving your account host) and the key (by authenticating). A successful response is the profile of the agent the key belongs to, so it also confirms which agent your automations will act as.

To confirm the rest of the surface, run Freshdesk: List Tickets for the queue and Freshdesk: List Ticket Fields for your account's field definitions. The field list is worth running early regardless: it returns the field names, types, and dropdown choices, including any custom statuses, that the ticket nodes and the filter query language expect. Everything in this verify path is read-only; nothing here writes to a ticket or sends anything to a customer.

Node reference

38 nodes, generated from the connector itself so this reference always matches what ships.

Read and query nodes 24

Freshdesk: Filter Tickets (Query Language)

freshdesk_filter_tickets

Search tickets with Freshdesk's filter query language, for example priority:4 OR priority:3, agent_id:3001 AND status:2, or cf_region:'emea'. Returns 30 results per page and the page number is capped at 10, so at most 300 results are reachable per query (the total count is still exact). New updates take a few minutes to index. Archived tickets are excluded.

Freshdesk: Get Company

freshdesk_get_company

Fetch one company by id, including domains, custom fields, health score, and account tier.

Freshdesk: Get Contact

freshdesk_get_contact

Fetch one contact by id, including custom fields, tags, other_emails, and company links.

Freshdesk: Get Current Agent

freshdesk_get_current_agent

Return the agent the API key belongs to. Needs no configuration, which makes it the connector's credential health check, and it is the one Agent API that does not require admin privileges, so it works for any agent's key. A wrong key returns 401 with Freshdesk's invalid_credentials error code; the response never echoes the API key.

Freshdesk: Get Group

freshdesk_get_group

Fetch one agent group by id, including its member agent ids and escalation settings.

Freshdesk: Get Solution Article

freshdesk_get_solution_article

Fetch one knowledge base article by id, with its full HTML description, status, tags, SEO metadata, and feedback counts.

Freshdesk: Get Ticket

freshdesk_get_ticket

Fetch one ticket by id, with optional embeds for conversations (first ten), requester, company, and stats. Each include costs one extra API credit (conversations costs two); the full thread comes from List Ticket Conversations.

Freshdesk: List Agents

freshdesk_list_agents

List the helpdesk's agents with their contact profiles, group and role ids, and availability. Filter by exact email, mobile, phone, or state (fulltime/occasional). Requires admin privileges on the API key's agent (only Get Current Agent is exempt from that requirement).

Freshdesk: List Canned Response Folders

freshdesk_list_canned_response_folders

List canned response folders with their response counts. The canned response APIs are documented as admin-only, so the API key's agent needs admin privileges.

Freshdesk: List Canned Responses in Folder

freshdesk_list_canned_responses

List the canned responses in a folder WITH their full content (title, plain-text content, and content_html, which may carry Freshdesk placeholders like {{ticket.url}}). Documented admin-only. Useful as reply templates feeding the Reply to Ticket node.

Freshdesk: List Companies

freshdesk_list_companies

List companies with their domains, health score, account tier, renewal date, and custom fields, up to 100 per page.

Freshdesk: List Contact Fields

freshdesk_list_contact_fields

List the account's contact field definitions: default and custom fields with their names (the keys used in a contact's custom_fields), labels, types, and edit permissions. The schema-discovery step before creating or updating contacts.

Freshdesk: List Contacts

freshdesk_list_contacts

List contacts, alphabetical, up to 100 per page. Filter by exact email, phone, mobile, company, state, or updated_since. Unblocked, undeleted contacts are returned by default; state=deleted lists soft-deleted contacts for the Restore Contact node.

Freshdesk: List Groups

freshdesk_list_groups

List agent groups with their member agent ids and escalation settings. Group ids feed ticket assignment (group_id on create/update ticket).

Freshdesk: List Products

freshdesk_list_products

List the account's products (multi-product helpdesks). Product ids feed ticket routing (product_id on create/update ticket).

Freshdesk: List Satisfaction Ratings

freshdesk_list_satisfaction_ratings

List customer satisfaction survey ratings across the helpdesk, with the ticket, agent, and group each rating belongs to. New-survey rating values run from 103 (extremely happy) to -103 (extremely unhappy) on the default_question key; classic surveys use 1 happy, 2 neutral, 3 unhappy.

Freshdesk: List Solution Articles

freshdesk_list_solution_articles

List the articles inside a solution folder, including each article's status (1 draft, 2 published), hit count, and thumbs up/down feedback.

Freshdesk: List Solution Categories

freshdesk_list_solution_categories

List the knowledge base's top-level solution categories. The KB hierarchy is category, then folder, then article; walk down with List Solution Folders.

Freshdesk: List Solution Folders

freshdesk_list_solution_folders

List the folders inside a solution category, with each folder's visibility setting and article count.

Freshdesk: List Ticket Conversations

freshdesk_list_ticket_conversations

List a ticket's full conversation thread: replies (source 0) and public or private notes (source 2), oldest first, up to 100 per page. The ticket's original description is not a conversation; it lives on the ticket itself.

Freshdesk: List Ticket Fields

freshdesk_list_ticket_fields

List the account's ticket field definitions: default and custom fields, their names (the keys used in custom_fields and the Filter Tickets query language), labels, types, required flags, and dropdown choices. The schema-discovery step before creating or filtering tickets.

Freshdesk: List Tickets

freshdesk_list_tickets

List tickets, newest first by default (up to 100 per page, 300 pages max). By default only tickets created in the last 30 days that are not deleted or spam are returned; set updated_since for older tickets, or the deleted filter to list soft-deleted tickets for the Restore Ticket node. Each include embed costs two extra API credits.

Freshdesk: List Time Entries

freshdesk_list_time_entries

List time entries logged on tickets across the helpdesk, filterable by company, agent, execution window, and billable flag. time_spent is in hh:mm format.

Freshdesk: Search Contacts by Name

freshdesk_search_contacts

Autocomplete-style contact search by name, case insensitive, matching from the start of each word (john and jonz both find John Jonz; hn does not). Returns id and name pairs; follow with Get Contact for the full record.

Action nodes 14

Freshdesk: Add Note to Ticket

freshdesk_add_ticket_note

Add a note to a ticket. Notes are PRIVATE by default (visible to agents only), which makes this the safe path for automation commentary; it sends nothing to the requester unless you explicitly set private to false (a public note is visible on the customer portal). notify_emails pings specific agents about the note.

Freshdesk: Create Company

freshdesk_create_company

Create a company. Name is required and must be unique (a duplicate returns a duplicate_value error). Contacts whose email matches one of the company's domains are associated with it automatically. Returns 201 with the new company.

Freshdesk: Create Contact

freshdesk_create_contact

Create a contact. Name is required plus at least one identifier: email, phone, mobile, twitter_id, or unique_external_id (email must be unique; a duplicate returns a duplicate_value error). Returns 201 with the new contact. Reversible: contacts can be soft-deleted and restored.

Freshdesk: Create Solution Article

freshdesk_create_solution_article

Create a knowledge base article in a folder. Status 1 saves it as a draft (this node's default, the safe path); status 2 publishes it to the portal immediately, subject to the folder's visibility. Returns 201 with the new article.

Freshdesk: Create Ticket

freshdesk_create_ticket

Create a ticket. Identify the requester by email, requester_id, phone, or unique_external_id (one is required); an unknown email or phone creates a new contact automatically. Returns 201 with the new ticket. Helpdesk notification rules may email the requester about the new ticket. Reversible: a created ticket can be soft-deleted and restored.

Freshdesk: Create Time Entry

freshdesk_create_time_entry

Log time on a ticket. ALWAYS set time_spent (hh:mm) for a plain log entry: if time_spent and timer_running are both omitted, Freshdesk starts a RUNNING TIMER instead, and starting a timer stops any other timer that agent has running. Returns 201 with the new entry.

Freshdesk: Delete Contact

freshdesk_delete_contact

DESTRUCTIVE: soft-delete a contact (the docs title this endpoint Soft Delete a Contact). The contact is recoverable with Restore Contact and shows up under List Contacts with state=deleted. The separate hard-delete endpoint, which also destroys the contact's tickets permanently, is deliberately not offered by this connector.

Freshdesk: Delete Ticket

freshdesk_delete_ticket

DESTRUCTIVE: soft-delete a ticket. Per the docs the ticket is recoverable: list it with the deleted filter on List Tickets and bring it back with Restore Ticket (no scrub timer is documented). Permanent deletion (emptying trash) only exists in the UI and the bulk endpoints, which this connector deliberately does not offer.

Freshdesk: Reply to Ticket (Emails Requester)

freshdesk_reply_to_ticket

SENDS A REAL EMAIL: post a public reply on a ticket, which Freshdesk immediately emails to the ticket requester (plus any cc/bcc). A sent reply cannot be unsent, so point automations at tickets you intend to answer; for internal collaboration use Add Note to Ticket (private by default) instead. When testing, use a scratch ticket whose requester is your own address.

Freshdesk: Restore Contact

freshdesk_restore_contact

Restore a soft-deleted contact. Find deleted contacts with List Contacts using state=deleted. Returns 204 on success.

Freshdesk: Restore Ticket

freshdesk_restore_ticket

Restore a soft-deleted ticket back to the account. Find deleted tickets with List Tickets using the deleted filter. Returns 204 on success.

Freshdesk: Update Company

freshdesk_update_company

Update a company. Only the fields you fill are sent, so partial updates are safe. The domains array replaces the existing domain list when provided.

Freshdesk: Update Contact

freshdesk_update_contact

Update a contact. Only the fields you fill are sent, so partial updates are safe. Note that a contact who has been converted to an agent can no longer have name, phone, mobile, or job title changed through this API.

Freshdesk: Update Ticket

freshdesk_update_ticket

Update a ticket: change status (2 Open, 3 Pending, 4 Resolved, 5 Closed), reassign (responder_id / group_id), set priority, replace tags, or edit subject and description. Only the fields you fill are sent. Updating description rewrites the ticket's original description, not the conversation; replies and notes are separate nodes. Subject and description cannot be updated on outbound-email tickets.

Using the integration

On the automation canvas

Freshdesk nodes chain with every other node: a scheduled Freshdesk: List Tickets sweep can open a task in Mattering Productivity for anything aging past a threshold, a low score from Freshdesk: List Satisfaction Ratings can start a follow up, and Freshdesk: List Ticket Conversations can feed a thread into a summarizer whose output goes back as a private note. Freshdesk: List Groups and Freshdesk: List Agents supply the ids that assignment on Freshdesk: Update Ticket needs, Freshdesk: Get Group and Freshdesk: Get Company resolve a single id into its full record, and Freshdesk: List Time Entries feeds billing or capacity reporting straight into a Mattering database.

From AI assistants over MCP

Every node speaks MCP, the open protocol for connecting AI assistants to tools. Claude, ChatGPT, and Matter can search the queue, read a thread, and look up the contact behind an email address through the same nodes your workflows use. The 24 read nodes are the safest surface to hand an agent, because none of them change a ticket or send anything; if you want an assistant to write, Freshdesk: Add Note to Ticket is the node to give it first.

Replies email the customer, notes do not

This is the distinction to internalize before pointing any automation at a live queue. Freshdesk: Reply to Ticket (Emails Requester) posts a public reply and Freshdesk immediately emails it to the ticket requester plus any cc or bcc; there is no undo, a sent reply cannot be unsent. Freshdesk: Add Note to Ticket sends nothing to the requester: notes default to private and are visible to agents only, and notify_emails pings specific agents rather than customers. Setting private to false turns a note into a public note that is visible on the customer portal, which is a deliberate choice rather than an accident. When you do test the reply node, use a scratch ticket whose requester is your own email address, so the only person who receives the test is you. One related Freshdesk behavior worth knowing: Freshdesk: Create Ticket can itself generate a customer email if your helpdesk's own notification rules are configured to send one, which is a setting in Freshdesk rather than something the integration controls.

Finding tickets: the 30 day default and the filter query language

Freshdesk: List Tickets returns only tickets created in the last 30 days unless you set updated_since, and it caps at 300 pages, which is 30,000 tickets. That default is behind most reports of missing history. For real searching, Freshdesk: Filter Tickets (Query Language) takes expressions such as priority:4 OR priority:3, agent_id:3001 AND status:2, or cf_region:'emea'. Enter the bare expression, because the integration adds the double quotes the API requires. The expression is limited to 512 characters, results come 30 per page, and the page number is capped at 10, so at most 300 results are reachable per query although the reported total stays exact. New updates take a few minutes to be indexed, and archived tickets are excluded. Custom fields are queried by name with the cf_ prefix and string values in single quotes; Freshdesk: List Ticket Fields tells you what those names are.

Ticket enums are numbers

Freshdesk models ticket properties as integers, which trips up nearly every first workflow. Status is 2 Open, 3 Pending, 4 Resolved, 5 Closed. Priority is 1 Low, 2 Medium, 3 High, 4 Urgent. Source is 1 Email, 2 Portal, 3 Phone, 7 Chat, 9 Feedback Widget, 10 Outbound Email. Accounts can define custom statuses with their own numbers, so these fields are left as free integers rather than fixed dropdowns; run Freshdesk: List Ticket Fields to read the real choices for your account, and Freshdesk: List Contact Fields before writing contact custom fields. Two more shape notes: write bodies are flat, with no resource wrapper around them, and pagination is page plus per_page with a default of 30 and a maximum of 100, where a per_page above 100 returns an error rather than being clamped.

Soft deletes, restore loops, and what is not built

Both deletes here are soft deletes and both recovery loops ship. Freshdesk: Delete Ticket removes a ticket from the queue; find it again with the deleted filter on Freshdesk: List Tickets, which is how deleted tickets are listed (there is no separate deleted tickets endpoint, the filter is the list), and bring it back with Freshdesk: Restore Ticket. Freshdesk: Delete Contact behaves the same way: deleted contacts are listed by Freshdesk: List Contacts with state set to deleted, and Freshdesk: Restore Contact reverses it. Both delete nodes are still flagged destructive, because emptying the trash in the Freshdesk interface can make a deletion permanent outside the API. The contact hard delete endpoint, which also destroys all of that contact's tickets and cannot be undone, is deliberately not offered here, and neither are ticket merge, the archive family, attachment deletion, or the bulk endpoints.

Troubleshooting

Test Connection fails with a 401 and an invalid_credentials error
The API key is wrong, was revoked, or picked up stray whitespace when pasted, or the domain points at a different Freshdesk account than the key. Re-copy the key from the agent's Profile Settings page (below the change password section) and confirm the domain is the same account. Remember the mapping while you check: the username field holds the domain, the password field holds the key. If the two are swapped, this is the error you get.
The connection test says to store the domain as the username
The credential is missing one of its two parts. Freshdesk needs both the account domain and the API key, so a single opaque secret is not enough to build a request. Open the credential and confirm the username field holds the domain (the examplecorp in examplecorp.freshdesk.com) and the password field holds the API key. A pasted full URL in the username is fine, because it is normalized down to the domain, but an empty field is not.
Nothing connects and your helpdesk lives on a custom domain
The v2 API works only via freshdesk.com domains, not via custom CNAMEs. If your team reaches the helpdesk at a vanity address such as support.yourcompany.com, that hostname will not authenticate. Use the underlying Freshdesk domain instead: sign in to the admin area and look at the freshdesk.com URL your account actually resolves to, and store that first part as the username.
A node returns 403 access_denied although Test Connection passed
The key belongs to a non admin agent and the node needs admin privileges. Every Agent API except the currently authenticated agent read requires admin, and the canned response APIs are documented as admin only, so Freshdesk: List Agents, Freshdesk: List Canned Response Folders, and Freshdesk: List Canned Responses in Folder can fail this way while everything else works. That is expected behavior, not a broken connector. Either grant the integration agent admin privileges or drop those nodes from the workflow. The connection test passes regardless because it only reads the key's own agent record, which needs no admin.
Older tickets are missing from the results
Freshdesk: List Tickets returns only the last 30 days unless updated_since is set, which is the single most common surprise on this integration. Set updated_since to the point in time you actually want, and remember the list caps at 300 pages of up to 100 tickets. Also check per_page: a value above 100 returns an error rather than being clamped down.
A filter query returns fewer results than the total it reports, or misses a ticket that just changed
Both are documented limits of Freshdesk: Filter Tickets (Query Language) rather than faults. Results come 30 per page and the page number is capped at 10, so at most 300 results can be paged through even when the reported total is larger; narrow the query (by date, group, or status) to get under the ceiling. New updates take a few minutes to be indexed for this search, so a ticket changed seconds ago may not match yet. Archived tickets are excluded entirely. The query itself is limited to 512 characters, and custom fields must be referenced by name with the cf_ prefix with string values in single quotes.
A time entry started a running timer instead of logging time
That is the documented behavior of Freshdesk: Create Time Entry when neither time_spent nor timer_running is supplied: Freshdesk starts a running timer, and starting a timer stops whatever other timer that agent had running. For plain logging, always set time_spent in hh:mm format, or pass timer_running as false explicitly. If a stray timer is already running, stop it from the Freshdesk interface, because timer toggling is not part of this integration.
Nodes start failing with 429 responses
Rate limits are per minute and account wide, and even invalid requests count against them. Freshdesk documents 50 calls per minute for trial accounts, and for current plans Growth 100, Pro 400, and Enterprise 700 (older plans are Blossom 100, Garden 200, Estate 400, Forest 700), with per endpoint sub caps on top of the account budget. Include embeds cost extra credits, two per include on the ticket list, one on a single ticket view, and two for conversations, so a loop that embeds everything burns the budget faster than the call count suggests. Every response carries X-RateLimit-Total, X-RateLimit-Remaining, and X-RateLimit-Used-CurrentRequest, and a 429 carries a Retry-After value in seconds. There is no automatic retry inside the integration, so add a wait step and back off, or slow the schedule down.

Freshdesk is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.

Start Free Explore our Products