Zendesk via n8n

This guide connects a WhatsApp line in Spun to Zendesk with a ready-made n8n workflow. Every WhatsApp conversation becomes one Zendesk ticket, follow-up messages are added as comments from the customer, and public agent replies in Zendesk 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 Zendesk	The first message of a conversation creates a ticket with the customer as requester. The customer is matched to a Zendesk user by phone number, or a new end user is created for them. The ticket stores the Spun chat id in its external id and carries the tag spun.
WhatsApp to Zendesk	Later messages are added to the open ticket as public comments from the customer, prefixed with their name and number. A message on a solved ticket sets it back to open. Media arrives as a link that stays valid for 24 hours.
Spun to Zendesk	Replies your team sends from the Spun inbox are added to the ticket as private comments, so the agent in Zendesk sees the whole exchange.
Spun to Zendesk	Archiving the conversation in Spun solves the ticket. Unarchiving it sets the ticket back to open.
Zendesk to WhatsApp	A public comment by an agent is sent to the customer on WhatsApp. Private comments, the customer's own comments and the workflow's own comments 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 user or a ticket. One conversation maps to one ticket until that ticket is closed; the next message after a close starts a follow-up ticket linked to the closed one.

Prerequisites

• A Zendesk account with an admin who can create webhooks, triggers and an OAuth client.
• An n8n instance that your Zendesk 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 Zendesk agent for the integration, such as "Spun WhatsApp", who is an admin or has a role that may manage end users. Every change the workflow makes is done as this agent, 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/zendesk/. The setup document lists every value with where to find it. In outline:

1. Create an OAuth client. Signed in as the integration agent, add an OAuth client in Admin Center under Apps and integrations, APIs. In n8n, create an OAuth2 credential with the client credentials grant, your Zendesk token URL and the scopes listed in the setup document. The setup document also describes an API token fallback.
2. Import the workflow into n8n and open the Settings node. Paste your Zendesk URL and the user id of the integration agent. A group, a brand and a "Spun line" ticket field are optional.
3. Choose the reply URL. Replace the placeholder at the end of the Helpdesk reply node's path with a long random string, then activate the workflow.
4. Create the Zendesk webhook in Admin Center under Apps and integrations, Webhooks, connected to triggers, pointing at the workflow's reply URL. Reveal its signing secret and paste it into the Settings node.
5. Create the reply trigger. It fires when a ticket tagged spun gets a public comment that was not made through the API, and calls the webhook with the body given in the setup document. Two more triggers for solved 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 solved in Zendesk 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 Zendesk. Reply to it as an agent with a public comment and the reply reaches the phone.

The Test webhook button in Zendesk signs its requests with a fixed test secret, so the workflow rejects them. Test with a real comment instead.

Rotate the signing secrets and the API key whenever someone who had access to the n8n instance leaves.

Check your notification triggers

Messages from WhatsApp are added as comments from the customer, but Zendesk records the change as made by the integration agent. Notification triggers that email the requester when an agent updates a ticket may then email the customer a copy of their own message. Customers the workflow creates have no email address and receive nothing, but a customer who was already a Zendesk user may. Add the condition Update via is not Web service (API) to every trigger that emails the requester.

Message mapping

Spun	Zendesk
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. First comment from the customer, external id set to the chat id, tags spun and whatsapp, group and brand as configured.
Later message.inbound	Public comment from the customer on the open ticket: [WhatsApp] Name (+number): text.
Message after the ticket was closed	New follow-up ticket linked to the closed one.
Media message	The same comment 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 comment 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 comment: [Sent from Spun] Agent name: text.
message.outbound that the workflow itself sent	Ignored.
conversation.closed	Ticket solved.
conversation.reopened	Ticket set back to open.
Public agent comment in Zendesk	WhatsApp message to the customer, text only. HTML formatting is converted to plain text.
Private comment, customer comment, or comment by the integration agent	Not sent.
Group chat	Skipped. Groups are not supported: they carry no phone number, so no user or ticket can be created for them.

Limits

• Solving a ticket in Zendesk 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 Zendesk. 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 triggers 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.
• Solving can be refused. If your account requires an assignee before a ticket is solved, archiving in Spun leaves the ticket open in Zendesk and the n8n execution shows the reason.
• Busy conversations can hit Zendesk's update limit. Zendesk accepts 30 updates per ticket in 10 minutes from one user, and every comment the workflow adds comes from the integration agent. When a customer sends more than that in a short burst, the extra messages are not added to the ticket; the n8n execution fails with the Zendesk response and can be re-run after a few minutes. The messages stay in the Spun inbox. Zendesk also limits new users to five per minute per agent.
• Media is sent as a link, not as a Zendesk 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.
• Replies from Zendesk are text only. Attachments an agent adds to a comment are not forwarded to WhatsApp.
• Replies are picked up through a trigger. Zendesk delivers each trigger call on a best-effort basis, so a reply can occasionally be delivered twice (the workflow sends it once) or not at all. Replies written through other API integrations are not forwarded, because the trigger leaves out every change made through the API. A reply is forwarded only if the trigger call arrives within 15 minutes of the comment (reply_window_minutes).
• The workflow never adds an email address to a Zendesk user. It looks customers up by its own external id and by phone number, and an existing Zendesk user found by phone is used as it is, without changes.
• 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 users in n8n's workflow data, so it stays well within Zendesk's API limits. If you reset the workflow or move it to another n8n instance, the next message for each conversation looks the ticket up in Zendesk by its external id and continues from there. Tickets that Zendesk has already archived 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. A ticket can hold at most 5,000 comments.

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 Zendesk error body is kept in the item that failed; the most common causes are a credential without the users:write scope, an integration agent who may not manage end users, or a group, brand or field id that does not exist.
• A reply from Zendesk never reaches WhatsApp. Check that the trigger is active, that the ticket has the spun tag, that the comment was public and written by an agent, and that the webhook's signing secret in the Settings node is current. The n8n execution shows the reason a reply was dropped, for example a signature that did not match.
• The customer receives their own message back on WhatsApp. The integration agent's user id in the Settings node does not match the user the credential acts as, or the reply trigger is missing the condition "Update via is not Web service (API)".
• The customer receives an email copy of their WhatsApp message. A notification trigger emails the requester on updates made through the API. See "Check your notification triggers" above.
• Duplicate tickets for one customer. The previous ticket was closed, so a follow-up is expected. If the first ticket is still open, check that its external id still holds the chat id and that it still has the spun tag; the workflow finds existing tickets by both.
• 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.