Zoho Desk via n8n

This guide connects a WhatsApp line in Spun to Zoho Desk with a ready-made n8n workflow. Every WhatsApp conversation becomes one Zoho Desk ticket, follow-up messages are added as comments, and public agent replies in Zoho Desk 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 Zoho Desk	The first message of a conversation creates a ticket in your chosen department, linked to a Zoho Desk contact found or created by phone number. The ticket stores the Spun chat id in a custom field.
WhatsApp to Zoho Desk	Later messages are added to the open ticket as public comments, prefixed with the sender's name and number. Media arrives as a link that stays valid for 24 hours.
Spun to Zoho Desk	Replies your team sends from the Spun inbox are added to the ticket as private notes, so the agent in Zoho Desk sees the whole exchange.
Spun to Zoho Desk	Archiving the conversation in Spun closes the ticket. Unarchiving it reopens the ticket.
Zoho Desk to WhatsApp	A public comment by an agent is sent to the customer on WhatsApp. Private notes 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 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.

Prerequisites

• A Zoho Desk plan that includes webhooks. Zoho offers them on Professional and Enterprise.
• An n8n instance that your Zoho Desk 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 Zoho Desk agent for the integration. Comments the workflow adds appear under the agent whose login authorised it, so a dedicated agent such as "WhatsApp (Spun)" keeps the ticket history readable and keeps the workflow's own comments out of the reply path.

Setup

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

1. Create a Zoho API client. In the Zoho API console, create a self client and copy its client id and secret. In n8n, create an OAuth2 credential with Zoho's authorisation and token URLs for your data centre and the scopes listed in the setup document.
2. Find your Zoho identifiers. The organisation id, the department that should receive WhatsApp tickets, and the id of the integration agent.
3. Add two custom fields to the ticket layout of that department: one for the Spun chat id (required) and one for the Spun line (optional). Copy the API names Zoho generates for them; the workflow needs the API names, not the labels.
4. Import the workflow into n8n and open the Settings node. Paste the Zoho values, choose the ticket channel value and the status label your portal uses for open tickets, and generate a random id that Zoho will use to ignore the workflow's own changes.
5. 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 Zoho Desk to archive the conversation in Spun; see Limits. Store the key in an n8n Header Auth credential and select it on the three nodes that call Spun.
6. Subscribe Spun to the workflow. Activate the workflow, copy the production URL of its 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.
7. Create the Zoho Desk webhook. In Zoho Desk, under Developer Space, create a webhook that points at the workflow's reply URL and subscribes to new ticket comments in your department, ignoring the source id you generated in step 4. Paste the webhook id 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 Zoho Desk. Reply to it as an agent and the reply reaches the phone.

Rotate the signing secret and the API key on the Webhooks page whenever someone who had access to the n8n instance leaves.

Message mapping

Spun	Zoho Desk
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 with the message, channel as configured, contact matched or created by phone, chat id in the custom field.
Later message.inbound	Public comment on the open ticket: [WhatsApp] Name (+number): text.
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 note: [Sent from Spun] Agent name: text.
message.outbound that the workflow itself sent	Ignored.
conversation.closed	Ticket closed in Zoho Desk.
conversation.reopened	Ticket status set back to the open label.
Public agent comment in Zoho Desk	WhatsApp message to the customer, text only. HTML formatting is converted to plain text.
Private note or comment 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 Zoho Desk 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 Zoho Desk. To enable the other direction, set it to true in the Settings node, give the API key the manage_conversations scope ("Close & Reopen Conversations" under Manage API Keys) and subscribe the Zoho Desk webhook to ticket updates as the setup document describes; the workflow then calls POST /api/integrations/conversations/close and /reopen. Check the first close in the n8n execution list before relying on it. If you would rather keep closing one-way, apply a label in Spun when your team needs to see the ticket state there.
• Media is sent as a link, not as a Zoho 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 Zoho Desk are text only. Attachments an agent adds to a comment are not forwarded to WhatsApp.
• 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, so it stays well within Zoho'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 Zoho Desk by the custom field and continues from there.
• One active ticket per conversation. A message that arrives after the ticket was closed starts a new ticket. Splitting a long conversation into several tickets by day is not supported.

Troubleshooting

• The Delivery Log shows 401 from n8n. The 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 Zoho error body is kept in the item that failed; the most common causes are a custom field API name that does not match, a field that is not on the department's layout, or a channel value that your portal does not list.
• A reply from Zoho Desk never reaches WhatsApp. Check the Zoho Desk webhook is enabled and subscribed to ticket comments for the right department, that the comment was public, and that it was not written by the integration agent. The n8n execution shows the reason a reply was filtered.
• The customer receives their own message back. The integration agent id in the Settings node does not match the agent who authorised the credential, or the ignore source id was not set on the Zoho Desk webhook.
• Duplicate tickets for one customer. The previous ticket was closed, so a new one is expected. If the first ticket is still open, check that the chat id custom field is filled; the workflow finds existing tickets by it.
• 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.