How to connect Zendesk 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 Zendesk from the dashboard, then start a fresh chat if the runtime still has the old tool catalog loaded.

Zendesk 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 Zendesk 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.

The engines and Zendesk's own support teach the cause order here, and this card now follows it. First check the OAuth grant: the connection must carry the scopes the failing tool needs, and if the grant was made with fewer scopes, reconnecting from the dashboard and approving the consent screen again is the fix. Second, the connected user's role: agent-vs-end-user decides what Zendesk lets through, and a connected account without agent rights fails actions that reads succeed on. Only then look at the argument: an invented or placeholder ticket or organization id returns a permission-shaped error even with perfect scopes, because Zendesk hides what you cannot see. State which of the three you checked before touching anything else.

Ask the agent to diagnose it:

Call zendesk_get_about_me and zendesk_get_account_settings. Tell me which Zendesk user this connection acts as and which plan the account is on, then quote the exact error from the failed call. Do not retry the call yet.

Zendesk rate-limits per plan at 200 to 2500 requests per minute, and an agent enumerating a large organization is exactly the shape that meets the limit: count, then list, then walk, one call at a time. A 429 is the API saying the minute is spent, so retrying immediately is wasted traffic. Change the shape of the work instead: ask for one ticket or a counted list, have the agent say what it intends to enumerate before it starts, and let a sweep run across turns rather than in one burst.

Ask the agent to diagnose it:

Tell me how many Zendesk calls you have made in the last minute and what you were enumerating. Quote any rate-limit header or 429 text from the last response. Do not call Zendesk again until I reply.

Start the way Google's answer for this symptom starts: ask the agent to list all the Zendesk tools it has access to in a fresh chat. Tool schemas load on demand in this setup, so a fresh chat plus a forced list normally resolves the case where the catalog had not hydrated yet; wait-and-retry is the fallback, and reconnect from the dashboard is the last step if tools are still absent. If most tools work and a single name fails, the name is wrong rather than missing, and the error lists the closest real ones. What does not apply is the usual advice for this symptom, which assumes a local MCP server declared in a client config file with env-var auth; there is no local server here.

Ask the agent to diagnose it:

List every Zendesk tool you currently have access to. If the list is empty, say so plainly and I will reconnect. If the list is full, tell me which tool creates a ticket and use that exact name on the next call.

Try reconnecting Zendesk 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 Zendesk: link your Zendesk account once in the browser and Hermes Agent can call the Zendesk API through 452 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 Zendesk 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 Zendesk 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 Zendesk working from chat.

Because Zendesk is actively killing API keys. Per Zendesk's own deprecation, accounts created after 2026-07-28 cannot use API tokens at all, unused tokens are deactivated after 30 days, and all API tokens stop working on 2027-04-30 in favor of OAuth. Any setup that generates, stores, and refreshes a Zendesk token has a hard expiry date. A hosted OAuth connection signs in through Zendesk's consent screen and has no token file anywhere, so none of the three deprecation rules apply to it. This is the reason the page promises no API keys rather than merely preferring them.

The tools cover the ticket surface and the administration around it: creating tickets and creating many at once, applying macros, autocompleting users, counting organizations and custom object records, reading account settings and the connected user, previews, and the export and app-inspection tools. Ticket creation and macro application are the writes that land in front of customers and colleagues, so those are the ones to say explicitly before letting the agent proceed. The read side is where agents earn their keep: an agent that can count organizations, list deleted users, and read account settings answers staffing and hygiene questions without anyone opening Zendesk.

Separate, deliberately. Zendesk's native AI agents live in Admin Center, are configured with click-to-connect steps, and operate inside Zendesk's own product. This integration is the external-agent route: Hermes is the agent, and Zendesk is one of the accounts it can touch from chat. That distinction matters because searches for "Zendesk AI agent without API key" are answered by Zendesk's native agents, which work fine when you want a bot on your help desk but do nothing for an agent that works across your other connected apps.

The mechanics of this connection are the answer: the OAuth grant is scoped to what the tool table on this page shows, there is no API key or token file to leak because none exists, and revoking from the ClawLink dashboard cuts access immediately. The searcher-level advice engines give is least privilege and draft mode, and both apply here: connect an account that only sees the support surface the agent should work on, and have the agent draft replies for approval before it sends them.

Zendesk documents plan-based limits: 200, 400, 700, or 2500 requests per minute depending on plan, with a 429 response past the allowance and a High Volume add-on for the top tiers. An agent that walks a large organization ticket by ticket is the traffic shape that meets them. Ask for one ticket or a counted list rather than a full sweep, and treat a 429 as a stop-and-wait signal rather than a retry trigger.

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.