How to connect Zoho Desk to Hermes Agent

Pairing is a two-step handshake: run hermes clawlink begin, approve the link in your browser, then run hermes clawlink finish. If you ran finish before approving, or the approval link expired, run hermes clawlink begin again to get a fresh link. Confirm the plugin was installed with --enable, then verify with hermes clawlink test.

Reconnect Zoho Desk from the dashboard, then start a fresh chat if the runtime still has the old tool catalog loaded.

Zoho Desk tool schemas load on demand the first time a tool runs and are cached after that, so this error usually clears on its own: wait a few seconds and retry the same request. If every Zoho Desk call keeps failing with it in a fresh chat, reconnect from the dashboard, and contact support if it still persists — that pattern points to a configuration problem on our side, not something you can fix by reconnecting again.

Two usual causes. The connected account may not have access to the specific workspace, inbox, store, or project in the request — check that first. If access looks right, the agent may have sent a placeholder value (like "YOUR_ID" or an example id from documentation) instead of a real one: ask it to run a list or search tool first, then retry the action with a real id from those results. Most failures at this stage are one of these two, not ClawLink bugs.

Check the id type before anything else: this is the 18-digit float64 trap. When the agent emits a ticket_id as a bare JSON number, the value rounds before reaching Zoho and the provider answers 404 URL_NOT_FOUND, an error that reads like a permissions or not-found problem but is pure ID precision. The tools affected are the id-typed ones: zoho_desk_get_ticket, zoho_desk_get_ticket_resolution, zoho_desk_get_ticket_latest_thread, zoho_desk_get_ticket_thread, and zoho_desk_list_ticket_conversations. The same call with the id as a quoted string succeeds. The fix is deploy-side and already live, but on a fresh session ask the agent to quote ids as strings in its calls.

Ask the agent to diagnose it:

Call zoho_desk_list_tickets and show me the exact ticket ids it returns. Then retry the failed call using one of those ids as a quoted string, and tell me whether it succeeds. Do not change anything about scopes or departments yet.

The taught cause order for Zoho Desk is scopes, departments, then tiers: the OAuth grant must carry the scope the failing tool needs (the pattern is ZohoDesk.tickets.READ for ticket reads), the connected user must belong to the department the ticket is in, and the user's license tier must include the feature being called. The top organic answer for this symptom is a community thread about a 403 on tickets in a new department, which is the department case. After scopes and departments are ruled out, check the argument: a placeholder or invented ticket, contact, or department id returns the same permission-shaped error because Zoho hides what the account cannot see. Reconnecting from the dashboard re-issues the grant if a permission changed after the connection was made.

Ask the agent to diagnose it:

Call zoho_desk_list_organizations and zoho_desk_get_agent, then list the departments you can see with zoho_desk_list_departments. Tell me which user, org, and departments this connection can reach, then quote the exact error from the failed call. Do not retry it yet.

The fix search results teach for this symptom lives inside Zoho's own MCP Console: log in, Tools, Add Tools, check Zoho Desk. That fixes their server's catalog, not this one. Here, if Hermes shows no Zoho Desk tools at all, confirm the plugin was installed with --enable, that both pairing commands ran, and that Zoho Desk shows as connected in the dashboard, then start a fresh chat. If most tools work and a single name fails, the name is wrong rather than missing, and the error lists the closest real ones. One timing case is unique to this setup: schemas load on demand, so the opening Zoho Desk call in a fresh session can arrive before the catalog and needs one retry.

Ask the agent to diagnose it:

List the Zoho Desk tools you actually have access to. If there are none, say so plainly. If there are, tell me which one lists tickets and use that exact name.

Try reconnecting Zoho Desk and complete the consent flow in the same browser session. Partial OAuth approvals or switching accounts mid-flow can leave the connection incomplete.

Yes. ClawLink is the fastest way to connect Hermes to Zoho Desk: link your Zoho Desk account once in the browser and Hermes Agent can call the Zoho Desk API through 23 ready-made tools — no custom code or token handling.

Install the plugin with hermes plugins install ClawLink-HQ/hermes-plugin --enable, then pair once: run hermes clawlink begin, approve the link in your browser, and run hermes clawlink finish. Connect Zoho Desk in the dashboard and Hermes can use it from the next message — no config files or API keys to manage.

About two minutes. Sign in, click Connect next to Zoho Desk in the dashboard, authenticate, and Hermes Agent can use it from the next chat message.

The alternative to ClawLink is usually manual OAuth app setup plus your own token handling, permission troubleshooting, and tool plumbing for Hermes Agent. That is fine if you want to build and maintain the integration yourself. Most teams just want Zoho Desk working from chat.

No, and the Self Client tutorial is exactly what this page removes. That route is what search results teach: register a client in the Zoho console, generate authorization codes, then run the refresh-token dance, permanently, because Zoho Desk no longer supports the old permanent auth tokens. The hosted connection owns the OAuth app, so you approve Zoho's consent screen once and the refresh cycle runs server-side. Nothing is registered by you, no code is generated, and no token file exists on your machine.

The ticket surface and the org structure around it: list and get tickets, read ticket threads, the latest thread, and resolutions, list ticket conversations, create tickets with subject, description, department, and requester details, and read contacts, departments, teams, roles, organizations, and agents. The reads are broad enough to answer most support questions without writing. The writes are creating tickets and updating tasks, plus the admin-shaped department logo upload; ticket creation lands in your help desk, so it is the action to say explicitly before the agent proceeds.

This is the trap this page discovered in production and it is worth reading carefully: Zoho Desk ticket ids are 18 digits, and when an agent passes one as a bare JSON number, the number gets rounded to a float before it reaches Zoho, which then answers with a 404 URL_NOT_FOUND. The same call with the id as a quoted string succeeds. The failure looks like a permissions or not-found problem, which is why every diagnostic you find will point at scopes, departments, or license tiers, and none of them will fix it. If a ticket call 404s on a healthy connection, check that the agent sent the id as a string, not a number.

The mechanics: the OAuth token lives server-side, the tool table on this page is the complete set of operations the agent can invoke, and revoking from the dashboard cuts access immediately. The permission levers are Zoho's own: scopes like ZohoDesk.tickets.READ, department restrictions, and license tiers decide what a connected account can touch, so connect an account whose department and license match the surface the agent should work on. For customer-visible writes like ticket creation, keep a draft-and-approve step in the prompt.

Zoho allocates API credits to organizations and answers calls beyond the allowance with 429, and the taught lesson is that these limits are a manual-app problem: a self-hosted integration consumes the org's credits on every call it makes. A 429 means the allowance window is spent, so the correct response is to wait it out rather than retry in a loop, and to shape agent work so a sweep happens across turns instead of in one burst.

Pairing is a two-step handshake: run hermes clawlink begin, approve the link in your browser, then run hermes clawlink finish. If you ran finish before approving, or the approval link expired, run hermes clawlink begin again to get a fresh link. Confirm the plugin was installed with --enable, then verify with hermes clawlink test.