KosmoKrator

productivity

Freshchat Lua API for KosmoKrator Agents

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

Lua Namespace

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

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.freshchat.list_conversations({page = 1, per_page = 1, status = "example_status", inbox_id = "example_inbox_id"}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("freshchat"))' --json
kosmo integrations:lua --eval 'print(docs.read("freshchat.list_conversations"))' --json

Workflow file

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

workflow.lua 
local freshchat = app.integrations.freshchat
local result = freshchat.list_conversations({page = 1, per_page = 1, status = "example_status", inbox_id = "example_inbox_id"})

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

MCP-only Lua

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

Freshchat — Lua API Reference

list_conversations

List support conversations with optional filters.

Parameters

NameTypeRequiredDescription
pageintegernoPage number (default: 1)
per_pageintegernoResults per page (default: 50, max: 100)
statusstringnoFilter by status: "new", "open", "pending", "resolved", "closed"
inbox_idstringnoFilter by inbox ID

Examples

-- List open conversations
local result = app.integrations.freshchat.list_conversations({
  status = "open",
  per_page = 20
})

for _, conv in ipairs(result.conversations or {}) do
  print(conv.id .. ": " .. (conv.status or "unknown"))
end
-- Paginate through resolved conversations
local result = app.integrations.freshchat.list_conversations({
  status = "resolved",
  page = 1,
  per_page = 50
})

get_conversation

Get full details of a specific conversation.

Parameters

NameTypeRequiredDescription
idstringyesThe conversation ID

Example

local result = app.integrations.freshchat.get_conversation({
  id = "abc-123-def"
})
print("Status: " .. result.status)
print("Created: " .. result.created_time)

create_conversation

Start a new support conversation.

Parameters

NameTypeRequiredDescription
user_idstringyesID of the user to associate with the conversation
initial_messagestringyesFirst message in the conversation
channel_idstringnoOptional channel ID for routing

Example

local result = app.integrations.freshchat.create_conversation({
  user_id = "user-456",
  initial_message = "I need help with my subscription",
  channel_id = "channel-789"
})
print("Created conversation: " .. result.conversation_id)

list_agents

List support agents with pagination.

Parameters

NameTypeRequiredDescription
pageintegernoPage number (default: 1)
per_pageintegernoResults per page (default: 50)

Example

local result = app.integrations.freshchat.list_agents({
  page = 1,
  per_page = 25
})

for _, agent in ipairs(result.agents or {}) do
  print(agent.first_name .. " (" .. agent.email .. ") - " .. (agent.status or "offline"))
end

get_agent

Get details of a specific agent.

Parameters

NameTypeRequiredDescription
idstringyesThe agent ID

Example

local result = app.integrations.freshchat.get_agent({
  id = "agent-123"
})
print("Agent: " .. result.first_name .. " " .. (result.last_name or ""))
print("Email: " .. result.email)

list_groups

List support groups (teams).

Parameters

NameTypeRequiredDescription
pageintegernoPage number (default: 1)
per_pageintegernoResults per page (default: 50)

Example

local result = app.integrations.freshchat.list_groups({
  page = 1,
  per_page = 50
})

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

get_current_user

Get the currently authenticated user profile.

Parameters

None.

Example

local result = app.integrations.freshchat.get_current_user({})
print("Logged in as: " .. (result.first_name or "") .. " " .. (result.last_name or ""))
print("Email: " .. (result.email or "unknown"))

Multi-Account Usage

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

-- Default account (always works)
app.integrations.freshchat.function_name({...})

-- Explicit default (portable across setups)
app.integrations.freshchat.default.function_name({...})

-- Named accounts
app.integrations.freshchat.work.function_name({...})
app.integrations.freshchat.support.function_name({...})

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

Raw agent markdown 
# Freshchat — Lua API Reference

## list_conversations

List support conversations with optional filters.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | no | Page number (default: 1) |
| `per_page` | integer | no | Results per page (default: 50, max: 100) |
| `status` | string | no | Filter by status: `"new"`, `"open"`, `"pending"`, `"resolved"`, `"closed"` |
| `inbox_id` | string | no | Filter by inbox ID |

### Examples

```lua
-- List open conversations
local result = app.integrations.freshchat.list_conversations({
  status = "open",
  per_page = 20
})

for _, conv in ipairs(result.conversations or {}) do
  print(conv.id .. ": " .. (conv.status or "unknown"))
end
```

```lua
-- Paginate through resolved conversations
local result = app.integrations.freshchat.list_conversations({
  status = "resolved",
  page = 1,
  per_page = 50
})
```

---

## get_conversation

Get full details of a specific conversation.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | The conversation ID |

### Example

```lua
local result = app.integrations.freshchat.get_conversation({
  id = "abc-123-def"
})
print("Status: " .. result.status)
print("Created: " .. result.created_time)
```

---

## create_conversation

Start a new support conversation.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `user_id` | string | yes | ID of the user to associate with the conversation |
| `initial_message` | string | yes | First message in the conversation |
| `channel_id` | string | no | Optional channel ID for routing |

### Example

```lua
local result = app.integrations.freshchat.create_conversation({
  user_id = "user-456",
  initial_message = "I need help with my subscription",
  channel_id = "channel-789"
})
print("Created conversation: " .. result.conversation_id)
```

---

## list_agents

List support agents with pagination.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | no | Page number (default: 1) |
| `per_page` | integer | no | Results per page (default: 50) |

### Example

```lua
local result = app.integrations.freshchat.list_agents({
  page = 1,
  per_page = 25
})

for _, agent in ipairs(result.agents or {}) do
  print(agent.first_name .. " (" .. agent.email .. ") - " .. (agent.status or "offline"))
end
```

---

## get_agent

Get details of a specific agent.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | The agent ID |

### Example

```lua
local result = app.integrations.freshchat.get_agent({
  id = "agent-123"
})
print("Agent: " .. result.first_name .. " " .. (result.last_name or ""))
print("Email: " .. result.email)
```

---

## list_groups

List support groups (teams).

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | no | Page number (default: 1) |
| `per_page` | integer | no | Results per page (default: 50) |

### Example

```lua
local result = app.integrations.freshchat.list_groups({
  page = 1,
  per_page = 50
})

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

---

## get_current_user

Get the currently authenticated user profile.

### Parameters

None.

### Example

```lua
local result = app.integrations.freshchat.get_current_user({})
print("Logged in as: " .. (result.first_name or "") .. " " .. (result.last_name or ""))
print("Email: " .. (result.email or "unknown"))
```

---

## Multi-Account Usage

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

```lua
-- Default account (always works)
app.integrations.freshchat.function_name({...})

-- Explicit default (portable across setups)
app.integrations.freshchat.default.function_name({...})

-- Named accounts
app.integrations.freshchat.work.function_name({...})
app.integrations.freshchat.support.function_name({...})
```

All functions are identical across accounts — only the credentials differ.
Metadata-derived Lua example 
local result = app.integrations.freshchat.list_conversations({page = 1, per_page = 1, status = "example_status", inbox_id = "example_inbox_id"})
print(result)

Functions

list_conversations Read

List support conversations from Freshchat. Returns paginated results with optional filters for status and inbox. Use this to find recent or unresolved conversations.

Lua path
app.integrations.freshchat.list_conversations
Full name
freshchat.freshchat_list_conversations
ParameterTypeRequiredDescription
page integer no Page number for pagination (default: 1).
per_page integer no Number of conversations per page (default: 50, max: 100).
status string no Filter by conversation status. Possible values: "new", "open", "pending", "resolved", "closed".
inbox_id string no Filter conversations belonging to a specific inbox by its ID.
get_conversation Read

Get full details of a specific Freshchat conversation by ID, including messages, participants, and metadata.

Lua path
app.integrations.freshchat.get_conversation
Full name
freshchat.freshchat_get_conversation
ParameterTypeRequiredDescription
id string yes The conversation ID.
create_conversation Write

Create a new Freshchat conversation. Specify the user ID, an initial message, and optionally a channel ID. The conversation will be started with the provided message.

Lua path
app.integrations.freshchat.create_conversation
Full name
freshchat.freshchat_create_conversation
ParameterTypeRequiredDescription
user_id string yes The ID of the user to associate with the conversation.
initial_message string yes The first message to send in the conversation.
channel_id string no Optional channel ID to associate the conversation with a specific channel.
list_agents Read

List support agents in Freshchat. Returns paginated results with agent details such as name, email, and availability status.

Lua path
app.integrations.freshchat.list_agents
Full name
freshchat.freshchat_list_agents
ParameterTypeRequiredDescription
page integer no Page number for pagination (default: 1).
per_page integer no Number of agents per page (default: 50, max: 100).
get_agent Read

Get details of a specific Freshchat agent by ID, including name, email, availability, and assigned conversations.

Lua path
app.integrations.freshchat.get_agent
Full name
freshchat.freshchat_get_agent
ParameterTypeRequiredDescription
id string yes The agent ID.
list_groups Read

List support groups (teams) in Freshchat. Groups organize agents into teams for routing conversations.

Lua path
app.integrations.freshchat.list_groups
Full name
freshchat.freshchat_list_groups
ParameterTypeRequiredDescription
page integer no Page number for pagination (default: 1).
per_page integer no Number of groups per page (default: 50, max: 100).
get_current_user Read

Get the profile of the currently authenticated Freshchat user. Useful for verifying credentials and identifying the connected account.

Lua path
app.integrations.freshchat.get_current_user
Full name
freshchat.freshchat_get_current_user
ParameterTypeRequiredDescription
No parameters.