KosmoKrator

productivity

Zoho Desk Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the Zoho Desk KosmoKrator integration.

Lua Namespace

Agents call this integration through app.integrations.zoho_desk.*. Use lua_read_doc("integrations.zoho-desk") inside KosmoKrator to discover the same reference at runtime.

Call Lua from the Headless CLI

Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic Zoho Desk workflow without starting an interactive agent session.

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.zoho_desk.list_tickets({departmentId = "example_departmentId", status = "example_status", priority = "example_priority", from = 1, limit = 1, sortBy = "example_sortBy", sortOrder = "example_sortOrder", search = "example_search"}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("zoho-desk"))' --json
kosmo integrations:lua --eval 'print(docs.read("zoho-desk.list_tickets"))' --json

Workflow file

Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.

workflow.lua 
local zoho_desk = app.integrations.zoho_desk
local result = zoho_desk.list_tickets({departmentId = "example_departmentId", status = "example_status", priority = "example_priority", from = 1, limit = 1, sortBy = "example_sortBy", sortOrder = "example_sortOrder", search = "example_search"})

dump(result)
Run the workflow 
kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json
Namespace note. integrations:lua exposes app.integrations.zoho_desk, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.zoho_desk.default.* or app.integrations.zoho_desk.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need Zoho Desk, use the narrower mcp:lua command.

MCP Lua command 
# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

Zoho Desk — Lua API Reference

list_tickets

List support tickets with optional filters.

Parameters

NameTypeRequiredDescription
departmentIdstringnoFilter by department ID
statusstringnoFilter by status: “Open”, “On Hold”, “Closed”, “Escalated”
prioritystringnoFilter by priority: “High”, “Medium”, “Low”
fromintegernoStarting index for pagination (default: 1)
limitintegernoMax tickets to return (default: 25, max: 200)
sortBystringnoSort field (e.g., “createdTime”, “subject”)
sortOrderstringnoSort direction: “asc” or “desc”
searchstringnoSearch term for subject or description

Example

local result = app.integrations["zoho-desk"].list_tickets({
  status = "Open",
  priority = "High",
  limit = 10
})

for _, ticket in ipairs(result.data or {}) do
  print(ticket.id .. ": " .. ticket.subject .. " [" .. ticket.status .. "]")
end

get_ticket

Get full details of a specific support ticket.

Parameters

NameTypeRequiredDescription
ticketIdstringyesThe ticket ID to retrieve

Example

local result = app.integrations["zoho-desk"].get_ticket({
  ticketId = "123456789"
})

print("Subject: " .. result.subject)
print("Status: " .. result.status)
print("Priority: " .. result.priority)

create_ticket

Create a new support ticket.

Parameters

NameTypeRequiredDescription
subjectstringyesTicket subject line
departmentIdstringyesDepartment ID to assign
descriptionstringnoDetailed description
contactIdstringnoContact ID to associate
emailstringnoContact email (alternative to contactId)
prioritystringnoPriority: “High”, “Medium”, “Low”, “Lowest”
statusstringnoInitial status
channelstringnoChannel: “Email”, “Phone”, “Web”, “Chat”
assigneeIdstringnoAgent ID to assign
teamIdstringnoTeam ID to assign

Example

local result = app.integrations["zoho-desk"].create_ticket({
  subject = "Login issue",
  departmentId = "123456",
  description = "User cannot log in after password reset.",
  priority = "High",
  email = "user@example.com"
})

print("Created ticket: " .. result.id)

update_ticket

Update an existing support ticket.

Parameters

NameTypeRequiredDescription
ticketIdstringyesThe ticket ID to update
subjectstringnoUpdated subject
descriptionstringnoUpdated description
statusstringnoNew status
prioritystringnoNew priority
assigneeIdstringnoReassign to agent
teamIdstringnoReassign to team
departmentIdstringnoMove to department
channelstringnoUpdated channel

Example

local result = app.integrations["zoho-desk"].update_ticket({
  ticketId = "123456789",
  status = "Closed"
})

print("Ticket updated")

list_contacts

List contacts from Zoho Desk.

Parameters

NameTypeRequiredDescription
fromintegernoStarting index for pagination
limitintegernoMax contacts to return
searchstringnoSearch by name, email, or phone
sortBystringnoSort field
sortOrderstringnoSort direction: “asc” or “desc”

Example

local result = app.integrations["zoho-desk"].list_contacts({
  search = "john",
  limit = 5
})

for _, contact in ipairs(result.data or {}) do
  print(contact.id .. ": " .. contact.firstName .. " " .. (contact.lastName or ""))
end

list_articles

List knowledge base articles.

Parameters

NameTypeRequiredDescription
departmentIdstringnoFilter by department
categoryIdstringnoFilter by category
fromintegernoStarting index for pagination
limitintegernoMax articles to return
searchstringnoSearch by title or content
sortBystringnoSort field
sortOrderstringnoSort direction: “asc” or “desc”

Example

local result = app.integrations["zoho-desk"].list_articles({
  departmentId = "123456",
  search = "password reset",
  limit = 5
})

for _, article in ipairs(result.data or {}) do
  print(article.id .. ": " .. article.title)
end

list_departments

List all support departments.

Parameters

NameTypeRequiredDescription
fromintegernoStarting index for pagination
limitintegernoMax departments to return

Example

local result = app.integrations["zoho-desk"].list_departments({})

for _, dept in ipairs(result.data or {}) do
  print(dept.id .. ": " .. dept.name)
end

get_current_user

Get the currently authenticated user’s profile.

Parameters

None.

Example

local result = app.integrations["zoho-desk"].get_current_user({})

print("Logged in as: " .. result.firstName .. " " .. (result.lastName or ""))
print("Email: " .. (result.emailId or "N/A"))
print("Role: " .. (result.role and result.role.name or "N/A"))

Multi-Account Usage

If you have multiple Zoho Desk accounts configured, use account-specific namespaces:

-- Default account (always works)
app.integrations["zoho-desk"].list_tickets({...})

-- Explicit default (portable across setups)
app.integrations["zoho-desk"].default.list_tickets({...})

-- Named accounts
app.integrations["zoho-desk"].production.list_tickets({...})
app.integrations["zoho-desk"].staging.list_tickets({...})

All functions are identical across accounts — only the credentials differ.

Raw agent markdown 
# Zoho Desk — Lua API Reference

## list_tickets

List support tickets with optional filters.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `departmentId` | string | no | Filter by department ID |
| `status` | string | no | Filter by status: "Open", "On Hold", "Closed", "Escalated" |
| `priority` | string | no | Filter by priority: "High", "Medium", "Low" |
| `from` | integer | no | Starting index for pagination (default: 1) |
| `limit` | integer | no | Max tickets to return (default: 25, max: 200) |
| `sortBy` | string | no | Sort field (e.g., "createdTime", "subject") |
| `sortOrder` | string | no | Sort direction: "asc" or "desc" |
| `search` | string | no | Search term for subject or description |

### Example

```lua
local result = app.integrations["zoho-desk"].list_tickets({
  status = "Open",
  priority = "High",
  limit = 10
})

for _, ticket in ipairs(result.data or {}) do
  print(ticket.id .. ": " .. ticket.subject .. " [" .. ticket.status .. "]")
end
```

---

## get_ticket

Get full details of a specific support ticket.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `ticketId` | string | yes | The ticket ID to retrieve |

### Example

```lua
local result = app.integrations["zoho-desk"].get_ticket({
  ticketId = "123456789"
})

print("Subject: " .. result.subject)
print("Status: " .. result.status)
print("Priority: " .. result.priority)
```

---

## create_ticket

Create a new support ticket.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `subject` | string | yes | Ticket subject line |
| `departmentId` | string | yes | Department ID to assign |
| `description` | string | no | Detailed description |
| `contactId` | string | no | Contact ID to associate |
| `email` | string | no | Contact email (alternative to contactId) |
| `priority` | string | no | Priority: "High", "Medium", "Low", "Lowest" |
| `status` | string | no | Initial status |
| `channel` | string | no | Channel: "Email", "Phone", "Web", "Chat" |
| `assigneeId` | string | no | Agent ID to assign |
| `teamId` | string | no | Team ID to assign |

### Example

```lua
local result = app.integrations["zoho-desk"].create_ticket({
  subject = "Login issue",
  departmentId = "123456",
  description = "User cannot log in after password reset.",
  priority = "High",
  email = "user@example.com"
})

print("Created ticket: " .. result.id)
```

---

## update_ticket

Update an existing support ticket.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `ticketId` | string | yes | The ticket ID to update |
| `subject` | string | no | Updated subject |
| `description` | string | no | Updated description |
| `status` | string | no | New status |
| `priority` | string | no | New priority |
| `assigneeId` | string | no | Reassign to agent |
| `teamId` | string | no | Reassign to team |
| `departmentId` | string | no | Move to department |
| `channel` | string | no | Updated channel |

### Example

```lua
local result = app.integrations["zoho-desk"].update_ticket({
  ticketId = "123456789",
  status = "Closed"
})

print("Ticket updated")
```

---

## list_contacts

List contacts from Zoho Desk.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `from` | integer | no | Starting index for pagination |
| `limit` | integer | no | Max contacts to return |
| `search` | string | no | Search by name, email, or phone |
| `sortBy` | string | no | Sort field |
| `sortOrder` | string | no | Sort direction: "asc" or "desc" |

### Example

```lua
local result = app.integrations["zoho-desk"].list_contacts({
  search = "john",
  limit = 5
})

for _, contact in ipairs(result.data or {}) do
  print(contact.id .. ": " .. contact.firstName .. " " .. (contact.lastName or ""))
end
```

---

## list_articles

List knowledge base articles.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `departmentId` | string | no | Filter by department |
| `categoryId` | string | no | Filter by category |
| `from` | integer | no | Starting index for pagination |
| `limit` | integer | no | Max articles to return |
| `search` | string | no | Search by title or content |
| `sortBy` | string | no | Sort field |
| `sortOrder` | string | no | Sort direction: "asc" or "desc" |

### Example

```lua
local result = app.integrations["zoho-desk"].list_articles({
  departmentId = "123456",
  search = "password reset",
  limit = 5
})

for _, article in ipairs(result.data or {}) do
  print(article.id .. ": " .. article.title)
end
```

---

## list_departments

List all support departments.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `from` | integer | no | Starting index for pagination |
| `limit` | integer | no | Max departments to return |

### Example

```lua
local result = app.integrations["zoho-desk"].list_departments({})

for _, dept in ipairs(result.data or {}) do
  print(dept.id .. ": " .. dept.name)
end
```

---

## get_current_user

Get the currently authenticated user's profile.

### Parameters

None.

### Example

```lua
local result = app.integrations["zoho-desk"].get_current_user({})

print("Logged in as: " .. result.firstName .. " " .. (result.lastName or ""))
print("Email: " .. (result.emailId or "N/A"))
print("Role: " .. (result.role and result.role.name or "N/A"))
```

---

## Multi-Account Usage

If you have multiple Zoho Desk accounts configured, use account-specific namespaces:

```lua
-- Default account (always works)
app.integrations["zoho-desk"].list_tickets({...})

-- Explicit default (portable across setups)
app.integrations["zoho-desk"].default.list_tickets({...})

-- Named accounts
app.integrations["zoho-desk"].production.list_tickets({...})
app.integrations["zoho-desk"].staging.list_tickets({...})
```

All functions are identical across accounts — only the credentials differ.
Metadata-derived Lua example 
local result = app.integrations.zoho_desk.list_tickets({departmentId = "example_departmentId", status = "example_status", priority = "example_priority", from = 1, limit = 1, sortBy = "example_sortBy", sortOrder = "example_sortOrder", search = "example_search"})
print(result)

Functions

list_tickets Read

List support tickets from Zoho Desk. Supports filtering by department, status, priority, and other criteria. Returns ticket IDs, subjects, statuses, and basic details.

Lua path
app.integrations.zoho_desk.list_tickets
Full name
zoho-desk.zohodesk_list_tickets
ParameterTypeRequiredDescription
departmentId string no Filter by department ID.
status string no Filter by status (e.g., "Open", "On Hold", "Closed", "Escalated").
priority string no Filter by priority (e.g., "High", "Medium", "Low").
from integer no Starting index for pagination (default: 1).
limit integer no Maximum number of tickets to return (default: 25, max: 200).
sortBy string no Sort field (e.g., "createdTime", "subject", "priority").
sortOrder string no Sort direction: "asc" or "desc".
search string no Search term to filter tickets by subject or description.
get_ticket Read

Get full details of a specific support ticket by its ID, including subject, description, status, priority, assignee, contact info, and custom fields.

Lua path
app.integrations.zoho_desk.get_ticket
Full name
zoho-desk.zohodesk_get_ticket
ParameterTypeRequiredDescription
ticketId string yes The ticket ID to retrieve.
create_ticket Write

Create a new support ticket in Zoho Desk. Requires at least a subject and department ID. Optionally include a contact ID, description, priority, and other ticket fields.

Lua path
app.integrations.zoho_desk.create_ticket
Full name
zoho-desk.zohodesk_create_ticket
ParameterTypeRequiredDescription
subject string yes The ticket subject line.
departmentId string yes The department ID to assign the ticket to. Use zohodesk_list_departments to find available departments.
description string no Detailed description of the issue or request.
contactId string no Contact ID to associate with the ticket.
email string no Email address of the contact (alternative to contactId).
priority string no Ticket priority: "High", "Medium", "Low", or "Lowest".
status string no Initial status (default depends on department settings).
channel string no Ticket channel (e.g., "Email", "Phone", "Web", "Chat").
assigneeId string no Agent ID to assign the ticket to.
teamId string no Team ID to assign the ticket to.
update_ticket Write

Update an existing support ticket in Zoho Desk. Provide the ticket ID and the fields to update (e.g., status, priority, assignee, subject, description).

Lua path
app.integrations.zoho_desk.update_ticket
Full name
zoho-desk.zohodesk_update_ticket
ParameterTypeRequiredDescription
ticketId string yes The ticket ID to update.
subject string no Updated ticket subject.
description string no Updated ticket description.
status string no New status (e.g., "Open", "On Hold", "Closed", "Escalated").
priority string no New priority (e.g., "High", "Medium", "Low").
assigneeId string no Agent ID to reassign the ticket to.
teamId string no Team ID to reassign the ticket to.
departmentId string no Move ticket to a different department.
channel string no Updated channel (e.g., "Email", "Phone", "Web").
list_contacts Read

List contacts from Zoho Desk. Supports filtering by name, email, and search terms. Returns contact IDs, names, emails, and phone numbers.

Lua path
app.integrations.zoho_desk.list_contacts
Full name
zoho-desk.zohodesk_list_contacts
ParameterTypeRequiredDescription
from integer no Starting index for pagination (default: 1).
limit integer no Maximum number of contacts to return (default: 25, max: 200).
search string no Search term to filter contacts by name, email, or phone.
sortBy string no Sort field (e.g., "firstName", "createdTime").
sortOrder string no Sort direction: "asc" or "desc".
list_articles Read

List knowledge base articles from Zoho Desk. Supports filtering by department, category, and search terms. Returns article IDs, titles, summaries, and categories.

Lua path
app.integrations.zoho_desk.list_articles
Full name
zoho-desk.zohodesk_list_articles
ParameterTypeRequiredDescription
departmentId string no Filter by department ID.
categoryId string no Filter by article category ID.
from integer no Starting index for pagination (default: 1).
limit integer no Maximum number of articles to return (default: 25, max: 200).
search string no Search term to filter articles by title or content.
sortBy string no Sort field (e.g., "title", "modifiedTime").
sortOrder string no Sort direction: "asc" or "desc".
list_departments Read

List all departments configured in Zoho Desk. Returns department IDs, names, descriptions, and visibility settings. Department IDs are needed when creating tickets.

Lua path
app.integrations.zoho_desk.list_departments
Full name
zoho-desk.zohodesk_list_departments
ParameterTypeRequiredDescription
from integer no Starting index for pagination (default: 1).
limit integer no Maximum number of departments to return (default: 25).
get_current_user Read

Get the profile of the currently authenticated Zoho Desk user. Returns user ID, name, email, role, and other profile information.

Lua path
app.integrations.zoho_desk.get_current_user
Full name
zoho-desk.zohodesk_get_current_user
ParameterTypeRequiredDescription
No parameters.