KosmoKrator

communication

Front Lua API for KosmoKrator Agents

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

7 functions 6 read 1 write Bearer token auth
Submit Front feedback View package source

Lua Namespace

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

Agent-Facing Lua Docs

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

Front — Lua API Reference

list_conversations

List and search conversations in Front.

Parameters

NameTypeRequiredDescription
pageintegernoPage number for pagination (1-based)
limitintegernoResults per page (max 100)
statusstringnoFilter by status: open, archived, assigned, unassigned, starred, snoozed
qstringnoSearch query (subject, content, contact)

Examples

-- List open conversations
local result = app.integrations.front.list_conversations({
  status = "open",
  limit = 10
})

-- Search conversations
local result = app.integrations.front.list_conversations({
  q = "billing",
  limit = 5
})

-- Paginate through all conversations
local result = app.integrations.front.list_conversations({
  page = 2,
  limit = 50
})

get_conversation

Get details of a specific conversation.

Parameters

NameTypeRequiredDescription
idstringyesConversation ID (e.g., "cnv_123abc")

Example

local result = app.integrations.front.get_conversation({
  id = "cnv_123abc"
})
print(result.subject)

list_messages

List all messages in a conversation.

Parameters

NameTypeRequiredDescription
conversation_idstringyesConversation ID (e.g., "cnv_123abc")
limitintegernoResults per page (max 100)
pageintegernoPage number for pagination (1-based)

Example

local result = app.integrations.front.list_messages({
  conversation_id = "cnv_123abc",
  limit = 20
})

for _, msg in ipairs(result._results) do
  print(msg.sender.name .. ": " .. (msg.text or msg.body))
end

send_message

Send a reply to an existing conversation.

Parameters

NameTypeRequiredDescription
conversation_idstringyesConversation ID to reply to
bodystringyesHTML body of the message
textstringnoPlain-text version of the message
toarraynoRecipients: {{"handle" = "[email protected]"}}
ccarraynoCC recipients: {{"handle" = "[email protected]"}}

Example

local result = app.integrations.front.send_message({
  conversation_id = "cnv_123abc",
  body = "<p>Hi there, thanks for your message!</p>",
  text = "Hi there, thanks for your message!",
  to = {{ handle = "[email protected]" }},
  cc = {{ handle = "[email protected]" }}
})

list_contacts

List and search contacts in Front.

Parameters

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

Examples

-- Search contacts
local result = app.integrations.front.list_contacts({
  q = "john",
  limit = 10
})

-- List all contacts (paginated)
local result = app.integrations.front.list_contacts({
  page = 1,
  limit = 100
})

get_contact

Get details of a specific contact.

Parameters

NameTypeRequiredDescription
idstringyesContact ID (e.g., "crd_123abc")

Example

local result = app.integrations.front.get_contact({
  id = "crd_123abc"
})
print(result.name)

get_current_user

Get the authenticated user’s profile.

Parameters

None.

Example

local result = app.integrations.front.get_current_user({})
print(result.first_name .. " " .. result.last_name)
print(result.email)

Multi-Account Usage

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

-- Default account (always works)
app.integrations.front.list_conversations({...})

-- Explicit default (portable across setups)
app.integrations.front.default.list_conversations({...})

-- Named accounts
app.integrations.front.support.list_conversations({...})
app.integrations.front.sales.list_conversations({...})

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

Raw agent markdown 
# Front — Lua API Reference

## list_conversations

List and search conversations in Front.

### 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`, `archived`, `assigned`, `unassigned`, `starred`, `snoozed` |
| `q` | string | no | Search query (subject, content, contact) |

### Examples

```lua
-- List open conversations
local result = app.integrations.front.list_conversations({
  status = "open",
  limit = 10
})

-- Search conversations
local result = app.integrations.front.list_conversations({
  q = "billing",
  limit = 5
})

-- Paginate through all conversations
local result = app.integrations.front.list_conversations({
  page = 2,
  limit = 50
})
```

---

## get_conversation

Get details of a specific conversation.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | Conversation ID (e.g., `"cnv_123abc"`) |

### Example

```lua
local result = app.integrations.front.get_conversation({
  id = "cnv_123abc"
})
print(result.subject)
```

---

## list_messages

List all messages in a conversation.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `conversation_id` | string | yes | Conversation ID (e.g., `"cnv_123abc"`) |
| `limit` | integer | no | Results per page (max 100) |
| `page` | integer | no | Page number for pagination (1-based) |

### Example

```lua
local result = app.integrations.front.list_messages({
  conversation_id = "cnv_123abc",
  limit = 20
})

for _, msg in ipairs(result._results) do
  print(msg.sender.name .. ": " .. (msg.text or msg.body))
end
```

---

## send_message

Send a reply to an existing conversation.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `conversation_id` | string | yes | Conversation ID to reply to |
| `body` | string | yes | HTML body of the message |
| `text` | string | no | Plain-text version of the message |
| `to` | array | no | Recipients: `{{"handle" = "[email protected]"}}` |
| `cc` | array | no | CC recipients: `{{"handle" = "[email protected]"}}` |

### Example

```lua
local result = app.integrations.front.send_message({
  conversation_id = "cnv_123abc",
  body = "<p>Hi there, thanks for your message!</p>",
  text = "Hi there, thanks for your message!",
  to = {{ handle = "[email protected]" }},
  cc = {{ handle = "[email protected]" }}
})
```

---

## list_contacts

List and search contacts in Front.

### 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 contacts
local result = app.integrations.front.list_contacts({
  q = "john",
  limit = 10
})

-- List all contacts (paginated)
local result = app.integrations.front.list_contacts({
  page = 1,
  limit = 100
})
```

---

## get_contact

Get details of a specific contact.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | Contact ID (e.g., `"crd_123abc"`) |

### Example

```lua
local result = app.integrations.front.get_contact({
  id = "crd_123abc"
})
print(result.name)
```

---

## get_current_user

Get the authenticated user's profile.

### Parameters

None.

### Example

```lua
local result = app.integrations.front.get_current_user({})
print(result.first_name .. " " .. result.last_name)
print(result.email)
```

---

## Multi-Account Usage

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

```lua
-- Default account (always works)
app.integrations.front.list_conversations({...})

-- Explicit default (portable across setups)
app.integrations.front.default.list_conversations({...})

-- Named accounts
app.integrations.front.support.list_conversations({...})
app.integrations.front.sales.list_conversations({...})
```

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

Metadata-Derived Lua Example

local result = app.integrations.front.front_get_contact({
  id = "example_id"
})
print(result)

Functions

front_get_contact

Get details of a specific Front contact by ID, including name, emails, phone numbers, and custom fields.

Operation
Read read
Full name
front.front_get_contact
ParameterTypeRequiredDescription
id string yes The contact ID (e.g., "crd_123abc").

front_get_conversation

Get details of a specific Front conversation by ID, including subject, participants, status, tags, and metadata.

Operation
Read read
Full name
front.front_get_conversation
ParameterTypeRequiredDescription
id string yes The conversation ID (e.g., "cnv_123abc").

front_get_current_user

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

Operation
Read read
Full name
front.front_get_current_user
ParameterTypeRequiredDescription
No parameters.

front_list_contacts

List and search contacts in Front. Search by name, email, or other identifiers. Returns paginated contact details.

Operation
Read read
Full name
front.front_list_contacts
ParameterTypeRequiredDescription
page integer no Page number for pagination (1-based).
limit integer no Number of contacts per page (max 100).
q string no Search query to filter contacts by name, email, or other identifiers.

front_list_conversations

List and search conversations in Front. Filter by status or search by keyword. Returns paginated results with conversation IDs, subjects, and metadata.

Operation
Read read
Full name
front.front_list_conversations
ParameterTypeRequiredDescription
page integer no Page number for pagination (1-based).
limit integer no Number of conversations per page (max 100).
status string no Filter by conversation status: open, archived, assigned, unassigned, starred, snoozed.
q string no Search query to filter conversations by subject, content, or contact.

front_list_messages

List all messages in a Front conversation. Returns paginated message details including sender, body, and timestamps.

Operation
Read read
Full name
front.front_list_messages
ParameterTypeRequiredDescription
conversation_id string yes The conversation ID (e.g., "cnv_123abc").
limit integer no Number of messages per page (max 100).
page integer no Page number for pagination (1-based).

front_send_message

Send a reply message to an existing Front conversation. Supports HTML and plain-text bodies, and explicit TO/CC recipients.

Operation
Write write
Full name
front.front_send_message
ParameterTypeRequiredDescription
conversation_id string yes The conversation ID to reply to (e.g., "cnv_123abc").
body string yes HTML body of the message.
text string no Plain-text version of the message body.
to array no Array of recipient objects, each with a "handle" key. Example: [{"handle": "[email protected]"}].
cc array no Array of CC recipient objects, each with a "handle" key. Example: [{"handle": "[email protected]"}].