n8n-nodes-zoho-desk

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

Features

• Full CRUD Operations: Create, Read, Update, Delete for Tickets, Contacts, and Accounts
• Dynamic Dropdowns: Department & Team selection auto-populated from your Zoho Desk account
• Automatic Contact Creation: Provide email/name and contacts are auto-created or matched
• Pagination Support: "Return All" toggle to fetch all records automatically
• Comprehensive Field Support: All 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
• Fully Tested: 17 integration tests covering all operations

Supported Operations

Resource	Operations
Ticket	Create, Get, List, Update, Delete, Add Comment, List Threads
Contact	Create, Get, List, Update, Delete
Account	Create, Get, List, Update, Delete

Installation

Community Node (Recommended)

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

Manual Installation

npm install 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

Ticket 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

Primary Fields:

• Priority: Low, Medium, or High (default: Medium)
• Classification: Question, Problem, Request, Others (default: Question)
• Due Date: Resolution deadline
• Description: Detailed ticket description
• Team: Select from department's teams (dropdown)

Contact (optional):

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

Additional Fields:

• Account ID, Assignee ID, Category, Channel, Custom Fields, Email, Language, Phone, Product ID, Resolution, Secondary Contacts, Status, Sub Category

Get Ticket

Retrieves a single ticket by ID.

List Tickets

Lists all tickets with optional filters.

• Return All: Toggle to fetch all tickets (with automatic pagination)
• Limit: Maximum number of results (when Return All is off)
• Filters: Department ID, Assignee ID, Status

Update Ticket

Updates an existing ticket. All fields are optional.

Delete Ticket

Moves a ticket to trash.

Add Comment

Adds a comment to a ticket.

• Content: Comment text
• Is Public: Whether visible to customers or internal only

List Threads

Lists all conversations/threads on a ticket.

Contact Operations

Create Contact

Required Fields:

• Last Name
• Email

Additional Fields:

• First Name, Phone, Mobile, Account ID, Twitter, Facebook, Type, Description, Custom Fields

Get / List / Update / Delete Contact

Standard CRUD operations with pagination support for List.

Account Operations

Create Account

Required Fields:

• Account Name

Additional Fields:

• Website, Phone, Fax, Industry, Description, Code, City, Country, State, Street, Zip, Custom Fields

Get / List / Update / Delete Account

Standard CRUD operations with pagination support for List.

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",
  "classification": "Problem",
  "teamId": "8920000000069071"
}

Create Contact

{
  "lastName": "Smith",
  "email": "john.smith@example.com",
  "firstName": "John",
  "phone": "+1-555-123-4567",
  "description": "VIP Customer"
}

Create Account

{
  "accountName": "Acme Corporation",
  "website": "https://acme.example.com",
  "industry": "Technology",
  "phone": "+1-555-000-0000",
  "city": "San Francisco",
  "country": "USA"
}

List All Tickets with Filters

{
  "returnAll": true,
  "filters": {
    "status": "Open",
    "departmentId": "1892000000006907"
  }
}

Field Details

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"

Validation & Error Handling

The node includes comprehensive validation:

• Contact Validation: Ensures either email or lastName is provided
• ID Validation: Validates IDs are numeric with proper length
• JSON Validation: Safe parsing of custom fields with detailed error messages
• Email Validation: RFC 5322 compliant email validation
• 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

The node detects rate limiting (HTTP 429) and provides clear error messages.

Supported Zoho Data Centers

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

Development

Setup

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

# Install dependencies
npm install

# Build the node
npm run build

# Run in development mode
npm run dev

# Run linting
npm run lint

# Run tests
npm run test:integration

Testing

The project includes comprehensive integration tests that run against the real Zoho Desk API:

# Create .env.test with your credentials
ZOHO_DESK_ACCESS_TOKEN=your_token
ZOHO_DESK_REFRESH_TOKEN=your_refresh_token
ZOHO_DESK_CLIENT_ID=your_client_id
ZOHO_DESK_CLIENT_SECRET=your_client_secret
ZOHO_DESK_ORG_ID=your_org_id
ZOHO_DESK_DATACENTER=com

# Run tests
npm run test:integration

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

Changelog

1.0.0 - Major Release

• New Resources: Contact and Account with full CRUD operations
• New Ticket Operations: Get, List, Delete, Add Comment, List Threads
• Pagination: "Return All" toggle with automatic page fetching
• Integration Tests: 17 comprehensive tests for all operations
• Lint Compliance: Full n8n linting rules compliance
• Bug Fixes: Proper error handling with NodeOperationError/ApplicationError

Previous Versions (as @enthu/n8n-nodes-zoho-desk)

• 0.3.x - Ticket create/update operations
• 0.2.x - Dynamic dropdowns, contact auto-creation
• 0.1.x - Initial release

Resources

• Zoho Desk API Documentation
• n8n Documentation
• n8n Community Nodes
• GitHub Repository
• npm Package