zoho-desk

n8n community node for Zoho Desk API integration

Package Information

Released: 11/20/2025
Downloads: 1,408 weekly / 1,408 monthly
Latest Version: 0.3.11
Author: Enthuziastic

Available Nodes

Zoho Desk
No description available

Documentation

n8n-nodes-zoho-desk

Production-ready n8n community node for integrating with Zoho Desk API. Create and manage support tickets with comprehensive field support, dynamic resource loading, and automatic contact creation.

Features

  • Dynamic Department & Team Selection: Dropdown lists automatically fetched from your Zoho Desk account
  • Automatic Contact Creation: Provide email/name and contacts are auto-created or matched
  • Comprehensive Field Support: All ticket fields including custom fields, priority, due dates, and more
  • OAuth2 Authentication: Secure authentication with support for all Zoho data centers
  • Type-Safe & Validated: Full TypeScript implementation with input validation
  • Production-Ready: Comprehensive error handling and user-friendly messages

Installation

Community Node (Recommended)

  1. Go to Settings > Community Nodes in n8n
  2. Search for @enthu/n8n-nodes-zoho-desk
  3. Click Install

Manual Installation

npm install @enthu/n8n-nodes-zoho-desk

Setup

1. Create Zoho Desk OAuth2 Client

  1. Go to Zoho API Console
  2. Click on "Add Client"
  3. Choose "Server-based Applications"
  4. Enter the following details:
    • Client Name: n8n Integration
    • Homepage URL: Your n8n instance URL
    • Authorized Redirect URIs: https://your-n8n-instance.com/rest/oauth2-credential/callback
  5. Click "Create"
  6. Note down your Client ID and Client Secret

2. Get Organization ID

  1. Login to your Zoho Desk account
  2. Go to Setup > Developer Space > API
  3. Copy your Organization ID

3. Configure Credentials in n8n

  1. In n8n, go to Credentials > New
  2. Select Zoho Desk OAuth2 API
  3. Enter:
    • Client ID: From step 1
    • Client Secret: From step 1
    • Organization ID: From step 2
    • Data Center: Select your Zoho data center
  4. Click Connect and authorize the application

Operations

Create Ticket

Creates a new support ticket with automatic contact creation/matching.

Required Fields:

  • Department: Select from dropdown (auto-populated)
  • Subject: Ticket subject line

Contact (optional but recommended):

  • Email OR Last Name (at least one required if providing contact)
  • First Name, Phone, Mobile (optional)
  • If email exists, existing contact is used; otherwise new contact is created

Optional Fields:

  • Description: Detailed ticket description
  • Due Date: Resolution deadline
  • Priority: Low, Medium, or High
  • Team: Select from department's teams (dropdown)
  • Secondary Contacts: Comma-separated contact IDs (e.g., 123456, 789012)
  • Custom Fields: JSON object (e.g., {"cf_modelname": "F3 2017", "cf_phone": "123456"})
  • Account ID, Assignee ID, Category, Channel, Classification, Email, Language, Phone, Product ID, Resolution, Status, Sub Category, Tags

Update Ticket

Updates an existing support ticket.

Required Fields:

  • Ticket ID: Numeric ticket ID to update

Update Fields (all optional):
All fields from create operation can be updated

Usage Examples

Create Ticket with Contact Auto-Creation

{
  "departmentId": "1892000000006907",
  "subject": "Order processing delay",
  "contact": {
    "email": "carol@zylker.com",
    "lastName": "Carol",
    "firstName": "Lucas",
    "phone": "1 888 900 9646"
  },
  "description": "Customer experiencing delays in order processing",
  "dueDate": "2025-12-01T10:00:00.000Z",
  "priority": "High",
  "secondaryContacts": "1892000000042038, 1892000000042042",
  "teamId": "8920000000069071",
  "cf": {
    "cf_modelname": "F3 2017",
    "cf_severitypercentage": "85.0"
  }
}

Update Ticket Status

{
  "ticketId": "1892000000042034",
  "priority": "High",
  "status": "In Progress",
  "description": "Updated with resolution details",
  "assigneeId": "456789123"
}

Field Details

Contact Object

The contact object allows automatic contact creation or matching:

  • If email exists in Zoho Desk → Uses existing contact
  • If email doesn't exist → Creates new contact with provided details
  • Validation: Either email OR lastName must be provided

Custom Fields (cf)

Pass custom fields as a JSON object:

{
  "cf": {
    "cf_fieldname": "value",
    "cf_priority_level": "urgent",
    "cf_product_version": "2.0.1"
  }
}

Secondary Contacts

Provide multiple contact IDs as comma-separated values:

"secondaryContacts": "1892000000042038, 1892000000042042, 1892000000042056"

Empty values are automatically filtered.

Tags

Comma-separated list of tags:

"tags": "urgent, customer-service, billing, escalated"

Validation & Error Handling

The node includes comprehensive validation:

  • ✅ Contact Validation: Ensures either email or lastName is provided
  • ✅ Ticket ID Validation: Validates ticket IDs are numeric
  • ✅ JSON Validation: Safe parsing of custom fields with detailed error messages
  • ✅ Empty String Filtering: Automatically filters empty values from arrays
  • ✅ Clear Error Messages: User-friendly error messages with actionable guidance

API Rate Limits

Zoho Desk API has the following rate limits:

  • 10 requests per second per organization
  • 5000 API calls per day

Rate Limit Handling: When rate limits are exceeded (HTTP 429), the node provides clear error messages with actionable guidance:

  • Suggests reducing the number of items being processed in a single workflow execution
  • Recommends adding delays between workflow runs
  • Works with "Continue On Fail" setting for graceful degradation

Note: The node detects rate limiting but does not automatically retry requests. You should implement retry logic in your workflow if needed.

Supported Zoho Data Centers

  • zoho.com (US)
  • zoho.eu (EU)
  • zoho.in (India)
  • zoho.com.cn (China)
  • zoho.com.au (Australia)
  • zoho.jp (Japan)

Technical Details

TypeScript Type Safety

The node is fully type-safe with TypeScript interfaces:

  • ZohoDeskDepartment - Department structure
  • ZohoDeskTeam - Team structure
  • ZohoDeskListResponse<T> - API response wrapper

Caching

n8n automatically caches dropdown options (departments, teams) after initial load. Data is refreshed when:

  • The node is reopened
  • User manually refreshes the dropdown
  • Parent parameter changes (e.g., changing department reloads teams)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

# Clone the repository
git clone https://github.com/EnthuZiastic/n8n-nodes-zoho-desk.git

# Install dependencies
npm install

# Build the node
npm run build

# Run in development mode
npm run dev

Publishing to npm

# Login to npm (one-time setup)
npm login

# Publish with version bump
npm run publish:minor  # For new features (0.2.0 → 0.3.0)
npm run publish:patch  # For bug fixes (0.2.0 → 0.2.1)
npm run publish:major  # For breaking changes (0.2.0 → 1.0.0)

License

MIT

Support

If you encounter any issues or have questions:

  1. Check the Issues page
  2. Create a new issue if your problem isn't already listed
  3. Contact the maintainer

Changelog

0.2.0 - Production Release

  • Dynamic department and team dropdowns
  • Automatic contact creation/matching
  • Comprehensive field support (description, dueDate, priority, secondaryContacts, custom fields)
  • Full TypeScript type safety
  • Input validation and error handling
  • JSDoc documentation throughout
  • Optimized performance

Resources

Discussion