KosmoKrator

productivity

Gorgias Lua API for KosmoKrator Agents

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

Lua Namespace

Agents call this integration through app.integrations.gorgias.*. Use lua_read_doc("integrations.gorgias") 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 Gorgias workflow without starting an interactive agent session.

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.gorgias.list_tickets({page = 1, limit = 1, status = "example_status", q = "example_q"}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("gorgias"))' --json
kosmo integrations:lua --eval 'print(docs.read("gorgias.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 gorgias = app.integrations.gorgias
local result = gorgias.list_tickets({page = 1, limit = 1, status = "example_status", q = "example_q"})

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.gorgias, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.gorgias.default.* or app.integrations.gorgias.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need Gorgias, 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.

Gorgias — Lua API Reference

list_tickets

List and search support tickets in Gorgias.

Parameters

NameTypeRequiredDescription
pageintegernoPage number for pagination (1-based)
limitintegernoResults per page (max 100)
statusstringnoFilter by status: open, closed, spam
qstringnoSearch query (subject, content, customer)

Examples

-- List open tickets
local result = app.integrations.gorgias.list_tickets({
  status = "open",
  limit = 10
})

-- Search tickets
local result = app.integrations.gorgias.list_tickets({
  q = "billing",
  limit = 5
})

-- Paginate through all tickets
local result = app.integrations.gorgias.list_tickets({
  page = 2,
  limit = 50
})

get_ticket

Get details of a specific ticket.

Parameters

NameTypeRequiredDescription
idstringyesTicket ID

Example

local result = app.integrations.gorgias.get_ticket({
  id = "12345"
})
print(result.subject)
print(result.status)

create_ticket

Create a new support ticket.

Parameters

NameTypeRequiredDescription
subjectstringyesTicket subject line
bodystringyesTicket body / message content (HTML supported)
from_emailstringnoSender email address
to_emailstringnoRecipient email address
channelstringnoTicket channel: email, chat, facebook, instagram
prioritystringnoTicket priority: normal, urgent, high, low

Example

local result = app.integrations.gorgias.create_ticket({
  subject = "Order not received",
  body = "<p>Customer reports order #5678 was never delivered.</p>",
  from_email = "customer@example.com",
  to_email = "support@myshop.com",
  channel = "email",
  priority = "high"
})
print("Created ticket: " .. result.id)

list_customers

List and search customers in Gorgias.

Parameters

NameTypeRequiredDescription
pageintegernoPage number for pagination (1-based)
limitintegernoResults per page (max 100)
qstringnoSearch query (name, email, etc.)

Examples

-- Search customers
local result = app.integrations.gorgias.list_customers({
  q = "john",
  limit = 10
})

-- List all customers (paginated)
local result = app.integrations.gorgias.list_customers({
  page = 1,
  limit = 100
})

get_customer

Get details of a specific customer.

Parameters

NameTypeRequiredDescription
idstringyesCustomer ID

Example

local result = app.integrations.gorgias.get_customer({
  id = "67890"
})
print(result.name)
print(result.email)

list_satisfaction_surveys

List satisfaction survey responses.

Parameters

NameTypeRequiredDescription
pageintegernoPage number for pagination (1-based)
limitintegernoResults per page (max 100)
ticket_idstringnoFilter surveys by ticket ID

Examples

-- List all survey responses
local result = app.integrations.gorgias.list_satisfaction_surveys({
  limit = 20
})

-- Surveys for a specific ticket
local result = app.integrations.gorgias.list_satisfaction_surveys({
  ticket_id = "12345"
})

get_current_user

Get the authenticated user’s profile.

Parameters

None.

Example

local result = app.integrations.gorgias.get_current_user({})
print(result.firstname .. " " .. result.lastname)
print(result.email)

Multi-Account Usage

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

-- Default account (always works)
app.integrations.gorgias.list_tickets({...})

-- Explicit default (portable across setups)
app.integrations.gorgias.default.list_tickets({...})

-- Named accounts
app.integrations.gorgias.support.list_tickets({...})
app.integrations.gorgias.sales.list_tickets({...})

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

Raw agent markdown 
# Gorgias — Lua API Reference

## list_tickets

List and search support tickets in Gorgias.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | no | Page number for pagination (1-based) |
| `limit` | integer | no | Results per page (max 100) |
| `status` | string | no | Filter by status: `open`, `closed`, `spam` |
| `q` | string | no | Search query (subject, content, customer) |

### Examples

```lua
-- List open tickets
local result = app.integrations.gorgias.list_tickets({
  status = "open",
  limit = 10
})

-- Search tickets
local result = app.integrations.gorgias.list_tickets({
  q = "billing",
  limit = 5
})

-- Paginate through all tickets
local result = app.integrations.gorgias.list_tickets({
  page = 2,
  limit = 50
})
```

---

## get_ticket

Get details of a specific ticket.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | Ticket ID |

### Example

```lua
local result = app.integrations.gorgias.get_ticket({
  id = "12345"
})
print(result.subject)
print(result.status)
```

---

## create_ticket

Create a new support ticket.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `subject` | string | yes | Ticket subject line |
| `body` | string | yes | Ticket body / message content (HTML supported) |
| `from_email` | string | no | Sender email address |
| `to_email` | string | no | Recipient email address |
| `channel` | string | no | Ticket channel: `email`, `chat`, `facebook`, `instagram` |
| `priority` | string | no | Ticket priority: `normal`, `urgent`, `high`, `low` |

### Example

```lua
local result = app.integrations.gorgias.create_ticket({
  subject = "Order not received",
  body = "<p>Customer reports order #5678 was never delivered.</p>",
  from_email = "customer@example.com",
  to_email = "support@myshop.com",
  channel = "email",
  priority = "high"
})
print("Created ticket: " .. result.id)
```

---

## list_customers

List and search customers in Gorgias.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | no | Page number for pagination (1-based) |
| `limit` | integer | no | Results per page (max 100) |
| `q` | string | no | Search query (name, email, etc.) |

### Examples

```lua
-- Search customers
local result = app.integrations.gorgias.list_customers({
  q = "john",
  limit = 10
})

-- List all customers (paginated)
local result = app.integrations.gorgias.list_customers({
  page = 1,
  limit = 100
})
```

---

## get_customer

Get details of a specific customer.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | Customer ID |

### Example

```lua
local result = app.integrations.gorgias.get_customer({
  id = "67890"
})
print(result.name)
print(result.email)
```

---

## list_satisfaction_surveys

List satisfaction survey responses.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | no | Page number for pagination (1-based) |
| `limit` | integer | no | Results per page (max 100) |
| `ticket_id` | string | no | Filter surveys by ticket ID |

### Examples

```lua
-- List all survey responses
local result = app.integrations.gorgias.list_satisfaction_surveys({
  limit = 20
})

-- Surveys for a specific ticket
local result = app.integrations.gorgias.list_satisfaction_surveys({
  ticket_id = "12345"
})
```

---

## get_current_user

Get the authenticated user's profile.

### Parameters

None.

### Example

```lua
local result = app.integrations.gorgias.get_current_user({})
print(result.firstname .. " " .. result.lastname)
print(result.email)
```

---

## Multi-Account Usage

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

```lua
-- Default account (always works)
app.integrations.gorgias.list_tickets({...})

-- Explicit default (portable across setups)
app.integrations.gorgias.default.list_tickets({...})

-- Named accounts
app.integrations.gorgias.support.list_tickets({...})
app.integrations.gorgias.sales.list_tickets({...})
```

All functions are identical across accounts — only the credentials differ.
Metadata-derived Lua example 
local result = app.integrations.gorgias.list_tickets({page = 1, limit = 1, status = "example_status", q = "example_q"})
print(result)

Functions

list_tickets Read

List and search support tickets in Gorgias. Filter by status or search by keyword. Returns paginated results with ticket IDs, subjects, and metadata.

Lua path
app.integrations.gorgias.list_tickets
Full name
gorgias.gorgias_list_tickets
ParameterTypeRequiredDescription
page integer no Page number for pagination (1-based).
limit integer no Number of tickets per page (max 100).
status string no Filter by ticket status: open, closed, spam.
q string no Search query to filter tickets by subject, content, or customer.
get_ticket Read

Get details of a specific Gorgias ticket by ID, including subject, body, status, assignee, and customer information.

Lua path
app.integrations.gorgias.get_ticket
Full name
gorgias.gorgias_get_ticket
ParameterTypeRequiredDescription
id string yes The ticket ID.
create_ticket Write

Create a new support ticket in Gorgias with a subject and body. Optionally specify sender, recipient, channel, and priority.

Lua path
app.integrations.gorgias.create_ticket
Full name
gorgias.gorgias_create_ticket
ParameterTypeRequiredDescription
subject string yes Ticket subject line.
body string yes Ticket body / message content (HTML supported).
from_email string no Sender email address.
to_email string no Recipient email address.
channel string no Ticket channel: email, chat, facebook, instagram, etc.
priority string no Ticket priority: normal, urgent, high, low.
list_customers Read

List and search customers in Gorgias. Filter by search query covering name, email, and other fields. Returns paginated results.

Lua path
app.integrations.gorgias.list_customers
Full name
gorgias.gorgias_list_customers
ParameterTypeRequiredDescription
page integer no Page number for pagination (1-based).
limit integer no Number of customers per page (max 100).
q string no Search query (name, email, etc.).
get_customer Read

Get details of a specific Gorgias customer by ID, including name, email, and custom fields.

Lua path
app.integrations.gorgias.get_customer
Full name
gorgias.gorgias_get_customer
ParameterTypeRequiredDescription
id string yes The customer ID.
list_satisfaction_surveys Read

List satisfaction survey responses in Gorgias. Optionally filter by ticket ID. Returns paginated results with ratings and feedback.

Lua path
app.integrations.gorgias.list_satisfaction_surveys
Full name
gorgias.gorgias_list_satisfaction_surveys
ParameterTypeRequiredDescription
page integer no Page number for pagination (1-based).
limit integer no Number of surveys per page (max 100).
ticket_id string no Filter surveys by ticket ID.
get_current_user Read

Get the profile of the currently authenticated Gorgias user. Returns name, email, and account details.

Lua path
app.integrations.gorgias.get_current_user
Full name
gorgias.gorgias_get_current_user
ParameterTypeRequiredDescription
No parameters.