> ## Documentation Index
> Fetch the complete documentation index at: https://ai-kb.automationanywhere.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Zoho Desk Toolkit
> Connect Zoho Desk to EKB agents and workflows to manage tickets, contacts, agents, and help-center articles.
The Zoho Desk toolkit connects a Zoho Desk account to EKB using OAuth and lets agents and workflows list and search tickets, read ticket conversations, look up contacts and agents, search help-center articles, create and update tickets, send customer replies, and add internal comments. The toolkit runs with the connected user's Zoho Desk permissions.
## Prerequisites
* An active Zoho Desk account with access to the organizations, departments, and tickets you intend to use.
* The Zoho Accounts URL for your datacenter (`https://accounts.zoho.com` for US, `https://accounts.zoho.eu` for EU, `https://accounts.zoho.in` for IN).
* An EKB project where you can configure an agent or workflow.
* Your EKB administrator must have configured a Zoho API Console client (Client ID and Client Secret) before you can connect.
Create Ticket, Update Ticket, and Send Reply always require confirmation before running. Review the confirmation card carefully — do not send a customer reply until the content is approved. Never include Client IDs, Client Secrets, or access tokens in workflow inputs, prompts, screenshots, or documentation.
## Setup
Open the target agent or workflow in EKB and choose **Toolkits**. Add the **Zoho Desk** toolkit using the configuration your administrator provided.
Set the Zoho Accounts URL to the datacenter where your Desk account is hosted — for example `https://accounts.zoho.com` for US, `https://accounts.zoho.eu` for EU, or `https://accounts.zoho.in` for IN. Leave Organization ID empty unless your administrator provided a specific one.
Enable only the tools required for your use case. Start with read-only discovery actions: **Get Organizations**, **Get Departments**, **List Tickets**, **Get Ticket**, and **Search Articles**.
In a published agent chat, use the Zoho Desk **Connect** card. The OAuth popup must open Zoho Accounts (not an internal login page). Complete the Zoho consent screen to authorize the connection.
Run **Get Organizations**, then **List Tickets** to confirm access. Read a known test ticket and its conversation before attempting any write actions.
## Available tools
### Discovery
| Tool | Description |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Get Organizations** | Lists Desk organizations and returns the org ID required by every other action. Call this first when org context is missing. |
| **Get Departments** | Lists departments used as routing targets when creating or triaging tickets. |
| **Get Agents** | Lists or searches agents for assignment and escalation. Returns agent IDs for use in create and update actions. |
### Tickets
| Tool | Description |
| --------------------------- | ------------------------------------------------------------------------------ |
| **List Tickets** | Lists tickets filtered by status, department, assignee, priority, and channel. |
| **Get Ticket** | Returns full ticket detail including contact, assignee, and department. |
| **Search Tickets** | Free-text search across subject, description, email, and ticket number. |
| **Get Ticket Conversation** | Returns threads and comments so you can review history before replying. |
### Contacts and Knowledge Base
| Tool | Description |
| ------------------- | --------------------------------------------------------------------------------------------------- |
| **Get Contacts** | Looks up contacts by email, phone, or name. Returns contact IDs for use in ticket creation. |
| **Search Articles** | Searches the Desk help center. Use this before drafting a customer reply to cite official articles. |
### Create and Update
| Tool | Description |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| **Create Ticket** | Creates a support ticket. Requires a subject, department ID, and either a contact ID or requester email. Requires confirmation. |
| **Update Ticket** | Updates status, priority, assignee, category, due date, department, or description on an existing ticket. Requires confirmation. |
| **Send Ticket Reply** | Sends a customer-facing email reply on a ticket. Requires confirmation. |
| **Add Internal Comment** | Adds an agent-only note to a ticket. Not sent to the customer unless `is_public` is set to true. |
### Advanced
| Tool | Description |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Custom API Call** | Calls any Zoho Desk v1 endpoint the connected token can reach. Keep disabled unless an administrator has approved a specific endpoint. |
## Use cases
* List open unassigned tickets in a department and surface a summary to a support lead, without changing anything.
* Get a ticket and its full conversation, then draft a reply that cites a matching help-center article.
* Create a ticket from an inbound request, look up the requester's contact record, and assign it to the right agent.
* Escalate a ticket by updating its status and priority, and adding an internal comment explaining the reason.
* Check for articles related to a customer's question before a reply is drafted, so the response cites official documentation.
## Troubleshooting
| Symptom | Likely cause | Fix |
| ------------------------------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Connect card shown / "not connected" | The Zoho OAuth connection has not been completed. | Complete Zoho OAuth from the chat Connect card, then retry. |
| `access_token` or API key headers missing | The Connect popup opened an internal EKB login URL instead of Zoho Accounts. | Reconnect so the popup opens the correct Zoho Accounts URL (`accounts.zoho.com`, `.eu`, or `.in`). Ask your administrator to verify the OAuth configuration if this recurs. |
| `orgId is required` | The org ID has not been resolved yet. | Call **Get Organizations** first, or ask your administrator to set the Organization ID on the toolkit configuration. |
| Invalid contact / no contact for this email | The requester email has no matching Desk contact, or an invalid contact ID was used. | Run **Get Contacts** to look up the requester, or provide a real email so Desk can create the contact inline with the ticket. |
| Validation error on department or assignee | A display name was used instead of a Desk ID. | Run **Get Departments** or **Get Agents** and use the returned `id` values — not names. |
| Redirect URI mismatch | The redirect URI in the Zoho API Console does not exactly match the one configured in EKB. | Ask your administrator to copy the toolkit's Authorized Redirect URI into the Zoho API Console exactly (`localhost` and `127.0.0.1` are treated as different values). |
| Wrong region or Accounts URL | The Accounts URL is set to the wrong Zoho datacenter. | Ask your administrator to set the Zoho Accounts URL to the correct datacenter for your Desk account. |
| Scope or permission error | The Zoho API Console client is missing required scopes. | Ask your administrator to add `Desk.tickets.ALL`, `Desk.contacts.READ`, `Desk.basic.READ`, `Desk.settings.READ`, `Desk.search.READ`, and `Desk.articles.READ`. |
| Create Ticket fails after confirmation | The confirmation card contained null fields from an outdated tool call. | Start a new tool call rather than confirming an old card. Ensure `contact_id` or `email` is provided. |