Zoho Desk Toolkit

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.

warning

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

1. Open an agent or workflow in EKB

   Open the target agent or workflow in EKB and choose Toolkits. Add the Zoho Desk toolkit using the configuration your administrator provided.

2. Set the Zoho Accounts URL

   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.

3. Enable the tools you need

   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.

4. Connect your Zoho account

   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.

5. Test with read actions first

   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.