Description
n8n community node for the Zoho Cliq REST API v2.
This node provides complete coverage of the Zoho Cliq API from a single, consistent n8n node. Every resource and every operation in the Zoho Cliq REST API v2 is implemented, tested, and documented. Beyond raw API coverage, the node adds meaningful enhancements that make working with Zoho Cliq in n8n significantly more reliable, more automatable, and more useful for both deterministic workflows and AI-powered agents.
Disclaimer
This project is not affiliated with, endorsed by, or associated with Zoho or Zoho Cliq in any capacity. It is an independent, community-built n8n node created by an individual developer. I cannot provide support for Zoho’s services, APIs, account issues, or platform behavior. For Zoho-specific questions, please refer to Zoho Cliq’s official documentation and Zoho’s support channels.
Table of Contents
- Disclaimer
- Installation
- Credentials
- API Coverage
- Custom Enhancements
- AI Agent Tool Support
- Development
- References
- Credits
- Coding Agent Credits
- License
Installation
Install this package as a standard n8n community node.
n8n Community Nodes UI (Recommended)
1. Open your n8n instance.
2. Navigate to Settings > Community Nodes.
3. Select Install.
4. Enter the package name below.
5. Approve the installation prompt and restart n8n if required.
Package Name – Must Include the scope!
@phil-fetchski/n8n-nodes-zoho-cliq
Credentials
This node uses OAuth2 via the Zoho Cliq OAuth2 API credential type.
Start with the setup guide included in this repository for the exact credential configuration flow used by this node, then use the official Zoho references for underlying OAuth protocol details.
API Coverage
This node implements 100% of the Zoho Cliq REST API v2 surface. Every resource group, every endpoint, and every operation is covered. In addition to the full API surface, the node includes custom helper resources that exist only in this package to solve real workflow problems that the Zoho Cliq API does not address on its own.
Over 160 operations are organized across 25 resources.
Core Messaging and Collaboration
| Resource | Description | Documentation |
| — | — | — |
| Message | Post, edit, delete, retrieve, get, and schedule messages across channels, chats, bots, and users | Operations |
| Thread | Create, reply to, and manage threaded conversations within channels | Operations |
| Reaction | Add, remove, and retrieve emoji reactions on messages | Operations |
| File | Upload, retrieve, and share files into conversations | Operations |
| Channel | Create, update, delete, and manage channel memberships, permissions, and settings | Operations |
| Chat | List, mute, unmute, pin, unpin, and leave direct message and group chat conversations | Operations |
| Bot | Retrieve bot subscribers and trigger bot-initiated calls | Operations |
Organization and Administration
| Resource | Description | Documentation |
| — | — | — |
| User | Look up, list, and manage user profiles and organization members | Operations |
| Team | Create, update, delete, and manage team memberships | Operations |
| Department | Create, update, delete, and manage department memberships | Operations |
| Role | Create, update, delete roles and manage role permissions and user assignments | Operations |
| Designation | Create, list, delete designations and manage designation members | Operations |
| User Field | Retrieve and manage custom user profile fields | Operations |
| User Status | Get, set, and clear user presence and status information | Operations |
| Custom Domain | Add, verify, get, and delete custom domains for the organization | Operations |
| Custom Email | Verify and update organization email configuration | Operations |
| Database | Create, list, and delete Cliq Database storage entries | Operations |
| Widget Map Ticker | Add, update, and delete widget map ticker entries | Operations |
| Bulk Action | Export channel and conversation data for compliance and backup | Operations |
Workflow and Scheduling
| Resource | Description | Documentation |
| — | — | — |
| Event | List events, get calendars, and upload calendar attachments | Operations |
| Reminder | Create and manage reminders | Operations |
| Remote Work | Manage remote work status entries (clock in, clock out, check status) | Operations |
| Calls and Meetings | List call recordings and retrieve recording details | Operations |
Helper Resources
These resources are custom additions that do not map to Zoho Cliq API endpoints. They run locally within the node to solve common workflow problems.
| Resource | Description | Documentation |
| — | — | — |
| Message Component Builder | Build and validate rich Cliq message payloads, card payloads, buttons, slides, tables, charts, graphs, and ACK messages without making API calls | Operations |
| OAuth Helper | Inspect granted scopes, discover scope packs, and validate scope coverage against the connected credential | Operations |
Custom Enhancements
This node is not a thin API wrapper. It includes several purpose-built enhancements that address real limitations in the Zoho Cliq API and improve the experience of building production workflows.
Preflight Validation and Structured Error Handling
The Zoho Cliq API often returns sparse, inconsistent, or unhelpful error responses. This node addresses that with a global preflight validation layer and structured error normalization.
Before any request is sent to the Zoho Cliq API, inputs are validated locally. IDs, email addresses, timestamps, enum values, and required fields are checked against expected formats. When validation fails, the node produces a structured error response with:
CHANNELNOTFOUND, USERNOTFOUND, THREADNOTFOUND, USERIDSNOTTEAMMEMBERS, DEPARTMENTNOTFOUND)These structured error responses are available when the node is configured with Continue On Fail enabled or when AI Error Mode is active. This design allows both deterministic workflows (using If/Switch nodes to branch on error codes) and AI agents (which can read the error output and decide how to recover) to handle failures gracefully instead of halting execution.
Enhanced Output for Sparse API Responses
Several Zoho Cliq API endpoints return only an empty string on success, which makes downstream workflow chaining difficult. For these operations, the node provides an optional Enable Enhanced Output toggle. When enabled, the node constructs a richer output object that includes the mutated item data, the resource and operation names, and a success: true field, giving downstream nodes something meaningful to work with.
Rich Message Payload Builders
The Message Component Builder resource provides local, no-API-call operations for constructing valid Zoho Cliq message payloads with full access to the Cliq message format. This includes:
These builders output valid JSON objects that can be passed directly into message-sending operations, eliminating the need to manually construct complex Cliq message structures.
ACK Message Builder for Bot Conversations
When using Zoho Cliq bots backed by n8n AI Agent workflows (triggered via webhook), there is an inherent delay while the AI agent processes the user’s message. During this delay, the user sees nothing in the Cliq chat, which creates a poor experience.
The Build and Fire ACK Message operation solves this by sending an immediate acknowledgment message to the bot conversation with a configurable loading state. This message appears instantly in the Cliq chat while the AI agent processes the request. Later in the workflow, the acknowledgment message can be edited or replaced with the actual AI response.
The operation includes:
OAuth Helper Operations
Zoho OAuth scope configuration is notoriously difficult to get right, especially when an integration spans messaging, admin, calendar, storage, and remote work operations. The built-in OAuth Helper resource provides operations to:
These operations run directly against the credential without calling any Cliq API endpoints, making them a safe diagnostic tool that can be used in any workflow.
AI Agent Tool Support
Every operation in this node (over 160) is designed to work as an AI tool in n8n agent workflows via usableAsTool: true. Beyond the standard n8n AI tool compatibility, this package includes a complete library of AI Agent Tool Field Guides with per-operation setup instructions for configuring each operation as a tool.
Each guide includes:
$fromAI() expressions with parameter names, descriptions, types, and default valuesThese guides were developed and tested iteratively against a Claude-powered AI agent in n8n to verify that the suggested descriptions and expressions produce reliable, correct tool calls across all operations.
| Resource | AI Tool Field Guide |
| — | — |
| Bot | Guide |
| Bulk Action | Guide |
| Calls and Meetings | Guide |
| Channel | Guide |
| Chat | Guide |
| Custom Domain | Guide |
| Custom Email | Guide |
| Database | Guide |
| Department | Guide |
| Designation | Guide |
| Events | Guide |
| Files | Guide |
| Message | Guide |
| Message Component Builder | Guide |
| OAuth Helper | Guide |
| Reaction | Guide |
| Reminders | Guide |
| Remote Work | Guide |
| Role | Guide |
| Team | Guide |
| Thread | Guide |
| User | Guide |
| User Field | Guide |
| User Status | Guide |
| Widget Map Ticker | Guide |
The master index for all AI tool guides is available at AiAgentToolDescriptions/README.md.
Development
For local development:
pnpm install
pnpm build
pnpm test:unit
pnpm lint
Run a single test:
npx jest tests/path/to/file.test.ts
See CLAUDE.md and AGENTS.md for architecture details and guidance for AI-assisted development.
References
Credits
The ACK Message Builder operation uses animated spinner thumbnails powered by the following open-source projects:
Both projects are excellent. If you find the spinner animations useful, consider starring the svg-spinners repository on GitHub.
Coding Agent Credits
Like most developers over the last several years, I of course use AI agents to assist in writing my code. While coding agents certainly have their upsides, the hype surrounding how easy-breezy it is to vibe code — “where you fully give in to the vibes, embrace exponentials, and forget that the code even exists” (Andrej Karpathy) — is really not the case. Any true developer knows that embracing exponentials and forgetting the code exists will only lead you to a vibe-coded hot pile of garbage. This package took countless hours of working with, guiding, re-guiding, and correcting the coding agents that I worked with, and countless more hours of testing, debugging, and decoding Zoho Cliq’s hot garbage API.
All that being said, I would like to give credit where credit is due. This package was co-developed mostly with ChatGPT Codex 5.3 and ChatGPT 5.4, with a bit of help here and there from Claude Opus 4.6 (always my favorite). This package was painstakingly developed with love and collaboration, but NOT “vibes.” I will say that I am grateful to all three of the coding agents that helped shape this code into what it is. So, a big thank you to my three co-developers: ChatGPT Codex 5.3, ChatGPT 5.4, and Claude Opus 4.6.
You will notice that I have included strict coding agent guidelines for this repo in CLAUDE.md and AGENTS.md, and I strongly suggest that you utilize those documents — at least as a baseline — if you would like to fork or branch this repo and do some coding (or vibing) of your own.
License
MIT
—
