n8n Zoho Desk Node

A comprehensive n8n community node for Zoho Desk with automatic OAuth2 token refresh handling, supporting Tickets, Contacts, and Comments.

✨ Features

• Automatic Token Refresh: Uses OAuth2 with refresh tokens - no manual token management needed
• Multi-Region Support: Automatically detects and uses the correct Zoho data center (US, EU, IN, AU, CN)
• Combined CRM & Desk Access: Single credential works for both Zoho CRM and Zoho Desk nodes
• Comprehensive Operations:
  • Tickets: Create, Get, Get Many, Update
  • Contacts: Create, Get, Get Many, Search, Update
  • Comments: Add, Get Many

🔐 Authentication Setup

This node uses a custom OAuth2 credential (zohoCRMDeskOAuth2Api) that properly handles refresh tokens and multi-region support.

Step 1: Create OAuth2 App in Zoho API Console

1. Go to Zoho API Console
2. Click ADD CLIENT → Server-based Applications
3. Fill in:

• Client Name: n8n Integration (or your preferred name)
• Homepage URL: https://your-n8n-instance.com
• Authorized Redirect URI: https://your-n8n-instance.com/rest/oauth2-credential/callback

4. Click CREATE
5. Copy the Client ID and Client Secret (you'll need these in n8n)

Step 2: Configure Scopes

When you create the credential in n8n, the default scope is:

ZohoCRM.modules.ALL Desk.tickets.ALL Desk.contacts.ALL Desk.search.READ

Available Zoho Desk Scopes:

• Desk.tickets.ALL - Full access to tickets
• Desk.contacts.ALL - Full access to contacts
• Desk.search.READ - Search across modules
• Desk.settings.ALL - Access to settings and configurations
• Desk.tasks.ALL - Task management
• Desk.basic.READ - Read-only access to basic information

You can customize the scope field in the credential to add or remove permissions as needed.

Step 3: Get Your Organization ID

1. Log in to Zoho Desk
2. Go to Setup (gear icon) → Developer Space → API
3. Copy your Organization ID (looks like: 12345678)
4. You'll enter this as a parameter in each Zoho Desk node

Step 4: Configure Credential in n8n

1. In n8n, go to Credentials → New
2. Search for Zoho CRM & Desk OAuth2 API
3. Fill in:

• Authorization URL: Select your region (e.g., https://accounts.zoho.com/oauth/v2/auth for US)
• Access Token URL: Select matching region (e.g., https://accounts.zoho.com/oauth/v2/token for US)
• Client ID: From Step 1
• Client Secret: From Step 1
• Scope: Default works for most cases, customize if needed

4. Click Connect my account
5. Authorize access in Zoho
6. ✅ Credential is ready to use!

Regional Mapping

Select the same region for both Authorization URL and Access Token URL:

Region	Authorization URL	Access Token URL
US	https://accounts.zoho.com/oauth/v2/auth	https://accounts.zoho.com/oauth/v2/token
EU	https://accounts.zoho.com/oauth/v2/auth	https://accounts.zoho.eu/oauth/v2/token
India	https://accounts.zoho.com/oauth/v2/auth	https://accounts.zoho.in/oauth/v2/token
Australia	https://accounts.zoho.com/oauth/v2/auth	https://accounts.zoho.com.au/oauth/v2/token
China	https://accounts.zoho.com.cn/oauth/v2/auth	https://accounts.zoho.com.cn/oauth/v2/token

Note: The API domain (e.g., https://desk.zoho.com) is automatically detected from the OAuth response - you don't need to configure it manually.

📦 Installation

Option 1: Install from npm (when published)

npm install n8n-nodes-zoho -g

Option 2: Local Development

1. Clone this repository:

git clone <your-repo-url>
cd n8n-nodes-zoho

2. Install dependencies and build:

npm install
npm run build

3. Link to your n8n instance:

npm link

4. In your n8n installation directory:

npm link n8n-nodes-zoho

5. Restart n8n

🚀 Usage Examples

Create a Ticket

Resource: Ticket
Operation: Create
Parameters:

• Organization ID: 12345678
• Subject: Unable to log in
• Contact Email: customer@example.com
• Department ID: 987654321
• Description: Customer reports they cannot access their account
• Additional Fields:
  • Priority: High
  • Status: Open

Search for Contacts

Resource: Contact
Operation: Search
Parameters:

• Organization ID: 12345678
• Search Query: john@example.com
• Limit: 10

Add Comment to Ticket

Resource: Comment
Operation: Add
Parameters:

• Organization ID: 12345678
• Ticket ID: 123456
• Content: Thank you for contacting support. We're looking into this issue.
• Is Public: ✓ (visible to customer)
• Content Type: Plain Text

🔧 How Token Refresh Works

This node uses n8n's built-in OAuth2 framework with requestOAuth2, which provides automatic token refresh:

1. Initial Authorization: When you connect the credential, Zoho returns:

• Access token (valid for ~1 hour)
• Refresh token (long-lived)
• Regional API domain

2. Automatic Refresh: When the access token expires:

• n8n detects the 401 error
• Automatically calls Zoho's token endpoint with the refresh token
• Updates the stored access token
• Retries the original request
• You never see the error or interruption

3. No Manual Intervention: Unlike custom API key implementations, you never need to manually refresh tokens or update credentials.

🤔 Why Not Use the Built-in zohoOAuth2Api?

The built-in Zoho CRM credential (zohoOAuth2Api) has hardcoded scopes for CRM only:

scope: 'ZohoCRM.modules.ALL,ZohoCRM.settings.all,ZohoCRM.users.all'

The scope property is type: 'hidden', so users cannot modify it to add Desk permissions. This is why we created a custom credential that:

• Extends the same OAuth2 framework
• Allows editable scopes
• Defaults to both CRM and Desk permissions
• Uses the exact same token refresh mechanism

🐛 Troubleshooting

"INVALID_OAUTH" or "Authentication failed" errors

Cause: Credentials may be using the wrong region
Fix: Ensure Authorization URL and Access Token URL match your Zoho account region

"Invalid OrgId" error

Cause: Organization ID is incorrect or missing
Fix: Double-check your Organization ID in Zoho Desk Setup → Developer Space → API

"Insufficient scope" or 401 Unauthorized

Cause: OAuth app doesn't have required scopes
Fix: Update the Scope field in your credential to include the necessary permissions (e.g., add Desk.tasks.ALL if you need task access)

Token refresh not happening automatically

Cause: Using httpRequest instead of requestOAuth2
Fix: This should not happen with this node - it's built to use requestOAuth2. If you see this, please file an issue.

"Department ID not found" when creating tickets

Cause: Invalid department ID
Fix: Get valid department IDs from Zoho Desk Setup → Channels & Departments, or use the Zoho Desk API to list departments

📚 API Documentation

• Zoho Desk API Reference
• Zoho OAuth 2.0 Guide
• n8n Community Nodes Documentation

🛠️ Development

Build

npm run build

Type Check

npm run typecheck

Validate

npm test

📝 Publishing to npm

1. Update package.json:

• Bump version
• Update name if needed (must be unique on npm)
• Verify description, author, keywords

2. Build and test:

npm run typecheck
npm run build
npm test

3. Publish:

npm login
npm publish

📄 License

MIT

🤝 Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

🙏 Credits

Built following n8n's community node patterns and inspired by the official Zoho CRM node implementation.

npm login
npm whoami

If your org uses 2FA, npm will ask for OTP during publish.

4) Publish

npm publish

For updates, bump version first:

npm version patch
npm publish

5) Install in n8n

On your n8n host:

npm install n8n-nodes-zoho-desk

Then restart n8n. The new node should appear in the editor.

6) Configure credentials in n8n

In n8n UI:

1. Create credentials using Zoho OAuth2 API.
2. Add Zoho Desk node to a workflow.
3. Set Data Center and Organization ID.
4. Run ticket operations.

Troubleshooting npm publish

• 403 Forbidden when publishing: package name already exists or account lacks rights; change name or publish under the correct npm org/scope.
• 402 Payment Required: scoped package defaults to private; use --access public or keep publishConfig.access = public.
• Missing files after install: confirm files in package.json includes your built dist output and rerun npm pack.