Freshdesk via n8n

This guide connects a WhatsApp line in Spun to Freshdesk with a ready-made n8n workflow. Every WhatsApp conversation becomes one Freshdesk ticket, follow-up messages are added to the ticket as notes on the customer's side of the thread, and public notes your agents add in Freshdesk go back to the customer on WhatsApp.

It builds on Connect a Helpdesk to WhatsApp, which explains the events, signatures and loop guards the workflow relies on. Read that guide first if you plan to change the workflow.

What it does

Direction	What happens
WhatsApp to Freshdesk	The first message of a conversation creates a ticket with the customer as requester. The customer is matched to a Freshdesk contact by phone or mobile number, or a new contact is created for them. The ticket stores the Spun chat id in a custom ticket field and carries the tags spun and whatsapp.
WhatsApp to Freshdesk	Later messages are added to the ticket as public notes on the customer's side of the thread, prefixed with their name and number. A message on a pending or resolved ticket sets it back to open. Media arrives as a link that stays valid for 24 hours.
Spun to Freshdesk	Replies your team sends from the Spun inbox are added to the ticket as private notes, so the agent in Freshdesk sees the whole exchange.
Spun to Freshdesk	Archiving the conversation in Spun closes the ticket. Unarchiving it sets the ticket back to open.
Freshdesk to WhatsApp	A public note by an agent is sent to the customer on WhatsApp. Private notes, the customer's side of the thread and the workflow's own notes are never sent.

Group chats are not supported and are skipped: a group has no phone number, so the workflow cannot link it to a contact or a ticket. One conversation maps to one ticket until that ticket is closed; the next message after a close starts a new ticket whose description names the previous ticket number.

Prerequisites

• A Freshdesk account on the Growth plan or above, so automation rules can call a webhook. On Free and Sprout, WhatsApp messages still become tickets, but agent notes cannot be sent back to WhatsApp.
• A Freshdesk admin who can create automation rules and custom ticket fields.
• An n8n instance that your Freshdesk account and Spun can reach over HTTPS, either n8n Cloud or a self-hosted install. The workflow uses only the nodes that ship with n8n.
• A Spun workspace with a connected WhatsApp line and access to the Webhooks page in Settings.
• A Freshdesk agent for the integration, such as "Spun WhatsApp", whose role may view, create and edit tickets, add notes, and view and create contacts, with access to all tickets. Every change the workflow makes is done with this agent's API key, which keeps the workflow's own writes out of the reply path.

Setup

The workflow file and a step-by-step setup document are in the Spun repository under integrations/helpdesk/freshdesk/. The setup document lists every value with where to find it. In outline:

1. Create the API key credential. Signed in as the integration agent, copy the API key from Profile settings. In n8n, create a Basic Auth credential with the API key as the user and X as the password, and select it on every node whose name starts with FRESHDESK:.
2. Add a "Spun chat id" ticket field. Create a single-line text ticket field (and optionally a "Spun line" field), not required for agents or for closing. Read its API name from the ticket fields API as the setup document shows.
3. Import the workflow into n8n and open the Settings node. Paste your Freshdesk URL, the API name of the chat id field and the id of the integration agent. A group and the "Spun line" field are optional.
4. Choose the reply URL and secret. Replace the placeholder at the end of the Helpdesk reply node's path with a long random string, paste a second long random string into the Settings node as the Freshdesk secret, then activate the workflow.
5. Create the automation rule. In Freshdesk, add a rule on the Ticket Updates tab that runs when an agent adds a note or sends a reply on a ticket tagged spun. Its action triggers a webhook to the workflow's reply URL with the header X-Spun-Secret set to your secret and the body given in the setup document. Two more rules for closed and reopened tickets are optional; see Limits.
6. Create a Spun API key on the Webhooks page under Manage API Keys with the send_message scope. Tick "Close & Reopen Conversations" as well (the manage_conversations scope) if you want a ticket closed in Freshdesk to archive the conversation in Spun. Store the key in an n8n Header Auth credential and select it on the three nodes that call Spun.
7. Subscribe Spun to the workflow. Copy the production URL of the workflow's Spun events node and create a webhook subscription on the Webhooks page for message.inbound, message.outbound, conversation.closed and conversation.reopened, with the payload template set to raw. Paste the signing secret into the Settings node.
8. Send a test message to the line from another phone. The Delivery Log on the Webhooks page shows the event, the n8n execution list shows the run, and a new ticket appears in Freshdesk. Answer it as an agent with a public note and the answer reaches the phone.

Rotate the Freshdesk secret, the signing secret and both API keys whenever someone who had access to the n8n instance leaves.

Answer with public notes

On a WhatsApp ticket, agents answer with Add note and switch the note to public. Notes are private by default, and a private note stays internal. The Reply button sends an email, and a customer the workflow created has no email address, so use public notes for WhatsApp answers.

Check your email notifications

Messages from WhatsApp are added as public notes made by the integration agent. Requester notifications that email the customer when an agent comments on a ticket may then email them a copy of their own message or of an agent's note. Contacts the workflow creates have no email address and receive nothing, but a customer who was already a Freshdesk contact may. During the first test, check the requester notifications under Email Notifications in the admin settings and turn off the ones that would copy WhatsApp messages by email.

Message mapping

Spun	Freshdesk
First message.inbound of a conversation	New ticket. Subject "WhatsApp: " followed by the first line of the message text (the caption for media, or the media type such as [image] when there is no caption), cut at 80 characters. Description [WhatsApp] Name (+number): text, the customer as requester, source Chat, status Open, the chat id field set, tags spun and whatsapp, group as configured.
Later message.inbound	Public note on the customer's side of the thread: [WhatsApp] Name (+number): text. A pending or resolved ticket is set back to open.
Message after the ticket was closed	New ticket. Its description ends with "Previous ticket: #" and the closed ticket's number.
Media message	The same note with the file type and size and a link to the file, valid for 24 hours. The caption follows the link.
Media still processing	A note saying the media is still being processed, with a pointer to the conversation in Spun. The link is not sent later.
message.outbound sent from the Spun inbox	Private note: [Sent from Spun] Agent name: text.
message.outbound that the workflow itself sent	Ignored.
conversation.closed	Ticket closed (or resolved, if you choose that status in the Settings node).
conversation.reopened	Ticket set back to open.
Public agent note in Freshdesk	WhatsApp message to the customer, text only. HTML formatting is converted to plain text.
Private note, note on the customer's side, or note by the integration agent	Not sent.
Group chat	Skipped. Groups are not supported: they carry no phone number, so no contact or ticket can be created for them.

Limits

• Closing a ticket in Freshdesk archives the conversation in Spun only when you turn that on. The workflow ships with close_in_spun_when_desk_closes set to false, so closing starts out one-way, from Spun to Freshdesk. To enable the other direction, set it to true in the Settings node, give the API key the manage_conversations scope and add the two optional automation rules from the setup document; the workflow then calls POST /api/integrations/conversations/close and /reopen. Check the first close in the n8n execution list before relying on it.
• Closing can be refused. If a ticket field is required when closing, archiving in Spun leaves the ticket open in Freshdesk and the n8n execution shows the reason.
• A closed ticket stays closed. A message after a close starts a new ticket that names the previous one. If you would rather keep one ticket, set the close status in the Settings node to Resolved: a message on a resolved ticket is added to it and sets it back to open.
• Busy accounts can hit Freshdesk's API limits. Freshdesk limits API calls per minute for the whole account, for example 100 on Growth and 400 on Pro, shared with every other app that uses the API. A new conversation takes up to five calls and a later message two or three. When the limit is reached, the n8n execution fails with the Freshdesk response and can be re-run after a minute. The messages stay in the Spun inbox.
• Media is sent as a link, not as a Freshdesk attachment. The link works for 24 hours. A file that was still processing when the message arrived is reported as pending and is not sent afterwards.
• Answers from Freshdesk are text only. Attachments an agent adds to a note are not forwarded to WhatsApp.
• Answers are picked up through an automation rule. Freshdesk retries a webhook call that fails every 30 minutes, and each note is sent once even when a call arrives twice. Freshdesk sends up to 1,000 webhook calls per hour per account and queues the rest. For a ticket the workflow does not know, for example after the workflow's data was reset, the first call from the rule forwards nothing: it only lets the workflow find the ticket again. Add the note again if it must reach the customer. Later notes on that ticket are forwarded as usual.
• Phone numbers must match exactly. The workflow looks customers up by phone and mobile number in international format, such as +14155550123. A contact whose number was typed in another format is not found, and a second contact is created for the same person; merge them in Freshdesk if that happens. An existing contact that is found is used as it is, without changes, and the workflow never adds an email address.
• Each delivered event uses AI tokens from your Spun plan. When the budget is exhausted, deliveries are skipped and the Delivery Log shows the reason. Top up or raise the budget to resume. How this is metered for helpdesk use is still being reviewed.
• The workflow remembers tickets and contacts in n8n's workflow data, which keeps its API use low. If you reset the workflow or move it to another n8n instance, the next message for each conversation looks the ticket up among the customer's tickets of the last year by the chat id field and continues from there. Deleted tickets and tickets marked as spam are not found that way, so such a conversation starts a new ticket.
• One active ticket per conversation. Splitting a long conversation into several tickets by day is not supported. On a ticket with more than 2,000 notes and replies, new agent notes may not be found; archive the conversation in Spun so the next message starts a new ticket.

Troubleshooting

• The Delivery Log shows 401 from n8n. The Spun signing secret in the Settings node does not match the subscription. Copy it again, or rotate it on the Webhooks page and paste the new value.
• The Delivery Log shows a delivery but no ticket appears. Open the n8n execution. A Freshdesk error body is kept in the item that failed; the most common causes are an API name for the chat id field that does not exist (invalid_field), an integration agent whose role may not create contacts or tickets, or a group id that does not exist.
• An answer from Freshdesk never reaches WhatsApp. Check that the automation rule is active, that the ticket has the spun tag, that the note was public and written by an agent other than the integration agent, and that the X-Spun-Secret header in the rule matches the Freshdesk secret in the Settings node. The n8n execution shows the reason a call was dropped, for example a bad or missing X-Spun-Secret header.
• The customer receives their own message back on WhatsApp. The integration agent's id in the Settings node does not match the agent whose API key the credential uses. Read it again as the setup document shows.
• The customer receives an email copy of their WhatsApp message. A requester notification emails the customer when an agent comments. See "Check your email notifications" above.
• Duplicate tickets for one customer. The previous ticket was closed, so a new ticket is expected. If the first ticket is still open, check that its chat id field still holds the chat id and that it still has the spun tag; the workflow finds existing tickets by both.
• Duplicate contacts for one customer. The existing contact's number is stored in a different format. Merge the contacts in Freshdesk and store the number in international format.
• Deliveries show Skipped: AI token budget exhausted. Top up on the Billing page or raise the budget. Catch up on missed messages with GET /api/integrations/messages once deliveries resume.

For the full list of events, headers, retry rules and loop guards, see Connect a Helpdesk to WhatsApp.