KosmoKrator

productivity

Telnyx Lua API for KosmoKrator Agents

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

Lua Namespace

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

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.telnyx.list_phone_numbers({page_size = 1, page_number = 1, filter_phone_number = "example_filter_phone_number", filter_status = "example_filter_status"}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("telnyx"))' --json
kosmo integrations:lua --eval 'print(docs.read("telnyx.list_phone_numbers"))' --json

Workflow file

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

workflow.lua 
local telnyx = app.integrations.telnyx
local result = telnyx.list_phone_numbers({page_size = 1, page_number = 1, filter_phone_number = "example_filter_phone_number", filter_status = "example_filter_status"})

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

MCP-only Lua

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

Telnyx — Lua API Reference

list_phone_numbers

List phone numbers on your Telnyx account.

Parameters

NameTypeRequiredDescription
page_sizeintegernoResults per page (default: 20, max: 250)
page_numberintegernoPage number (starts at 1)
filter_phone_numberstringnoFilter by E.164 number (e.g., "+12345678900")
filter_statusstringnoFilter by status: active, deleted, purchase_pending, purchase_failed, port_pending, port_failed

Example

local result = app.integrations.telnyx.list_phone_numbers({
  page_size = 10,
  filter_status = "active"
})

for _, pn in ipairs(result.data) do
  print(pn.phone_number .. " (" .. pn.status .. ")")
end

get_phone_number

Get details for a specific phone number.

Parameters

NameTypeRequiredDescription
phone_number_idstringyesTelnyx phone number ID

Example

local result = app.integrations.telnyx.get_phone_number({
  phone_number_id = "1293384265029123456"
})

print(result.data.phone_number)  -- "+12345678900"
print(result.data.status)        -- "active"

list_messages

List SMS and MMS messages sent and received.

Parameters

NameTypeRequiredDescription
page_sizeintegernoResults per page (default: 20, max: 250)
page_numberintegernoPage number (starts at 1)
directionstringnoinbound or outbound
filter_sourcestringnoSource phone number (E.164)
filter_destinationstringnoDestination phone number (E.164)
filter_statusstringnoqueued, sending, sent, delivered, undeliverable, expired

Example

local result = app.integrations.telnyx.list_messages({
  direction = "outbound",
  page_size = 50
})

for _, msg in ipairs(result.data) do
  print(msg.from .. " -> " .. msg.to .. ": " .. msg.text)
end

send_sms

Send an SMS or MMS message.

Parameters

NameTypeRequiredDescription
fromstringyesSender phone number (E.164, must be on your account)
tostringyesDestination phone number (E.164)
textstringyesMessage body
subjectstringnoSubject (for MMS)
media_urlsarraynoURLs of media attachments for MMS
use_mmsbooleannoSet to true to send as MMS

Example

local result = app.integrations.telnyx.send_sms({
  from = "+12345678900",
  to = "+19876543210",
  text = "Hello from Telnyx!"
})

print("Message ID: " .. result.data.id)
print("Status: " .. result.data.status)

list_calls

List voice calls on the account.

Parameters

NameTypeRequiredDescription
page_sizeintegernoResults per page (default: 20, max: 250)
page_numberintegernoPage number (starts at 1)
filter_statusstringnoinitiating, ringing, in-progress, no-answer, completed, failed, busy, timeout

Example

local result = app.integrations.telnyx.list_calls({
  filter_status = "completed",
  page_size = 20
})

for _, call in ipairs(result.data) do
  print("Call: " .. call.call_session_id .. " - " .. call.status)
end

get_call

Get details for a specific call.

Parameters

NameTypeRequiredDescription
call_session_idstringyesCall session ID

Example

local result = app.integrations.telnyx.get_call({
  call_session_id = "0ccc7b54-4e3a-4fa1-8c3f-5d2e3f4g5h6i"
})

print("Status: " .. result.data.status)
print("Duration: " .. result.data.duration .. "s")

list_call_records

List call recordings.

Parameters

NameTypeRequiredDescription
page_sizeintegernoResults per page (default: 20, max: 250)
page_numberintegernoPage number (starts at 1)
filter_call_session_idstringnoFilter by call session ID
filter_conference_idstringnoFilter by conference ID

Example

local result = app.integrations.telnyx.list_call_records({
  filter_call_session_id = "0ccc7b54-4e3a-4fa1-8c3f-5d2e3f4g5h6i"
})

for _, rec in ipairs(result.data) do
  print("Recording: " .. rec.id .. " - " .. rec.duration .. "s")
  print("Download: " .. rec.download_urls[1])
end

Multi-Account Usage

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

-- Default account
app.integrations.telnyx.send_sms({ from = "+1...", to = "+1...", text = "Hi" })

-- Named accounts
app.integrations.telnyx.work.send_sms({ from = "+1...", to = "+1...", text = "Hi" })
app.integrations.telnyx.personal.send_sms({ from = "+1...", to = "+1...", text = "Hi" })

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

Raw agent markdown 
# Telnyx — Lua API Reference

## list_phone_numbers

List phone numbers on your Telnyx account.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page_size` | integer | no | Results per page (default: 20, max: 250) |
| `page_number` | integer | no | Page number (starts at 1) |
| `filter_phone_number` | string | no | Filter by E.164 number (e.g., `"+12345678900"`) |
| `filter_status` | string | no | Filter by status: `active`, `deleted`, `purchase_pending`, `purchase_failed`, `port_pending`, `port_failed` |

### Example

```lua
local result = app.integrations.telnyx.list_phone_numbers({
  page_size = 10,
  filter_status = "active"
})

for _, pn in ipairs(result.data) do
  print(pn.phone_number .. " (" .. pn.status .. ")")
end
```

---

## get_phone_number

Get details for a specific phone number.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `phone_number_id` | string | yes | Telnyx phone number ID |

### Example

```lua
local result = app.integrations.telnyx.get_phone_number({
  phone_number_id = "1293384265029123456"
})

print(result.data.phone_number)  -- "+12345678900"
print(result.data.status)        -- "active"
```

---

## list_messages

List SMS and MMS messages sent and received.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page_size` | integer | no | Results per page (default: 20, max: 250) |
| `page_number` | integer | no | Page number (starts at 1) |
| `direction` | string | no | `inbound` or `outbound` |
| `filter_source` | string | no | Source phone number (E.164) |
| `filter_destination` | string | no | Destination phone number (E.164) |
| `filter_status` | string | no | `queued`, `sending`, `sent`, `delivered`, `undeliverable`, `expired` |

### Example

```lua
local result = app.integrations.telnyx.list_messages({
  direction = "outbound",
  page_size = 50
})

for _, msg in ipairs(result.data) do
  print(msg.from .. " -> " .. msg.to .. ": " .. msg.text)
end
```

---

## send_sms

Send an SMS or MMS message.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `from` | string | yes | Sender phone number (E.164, must be on your account) |
| `to` | string | yes | Destination phone number (E.164) |
| `text` | string | yes | Message body |
| `subject` | string | no | Subject (for MMS) |
| `media_urls` | array | no | URLs of media attachments for MMS |
| `use_mms` | boolean | no | Set to `true` to send as MMS |

### Example

```lua
local result = app.integrations.telnyx.send_sms({
  from = "+12345678900",
  to = "+19876543210",
  text = "Hello from Telnyx!"
})

print("Message ID: " .. result.data.id)
print("Status: " .. result.data.status)
```

---

## list_calls

List voice calls on the account.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page_size` | integer | no | Results per page (default: 20, max: 250) |
| `page_number` | integer | no | Page number (starts at 1) |
| `filter_status` | string | no | `initiating`, `ringing`, `in-progress`, `no-answer`, `completed`, `failed`, `busy`, `timeout` |

### Example

```lua
local result = app.integrations.telnyx.list_calls({
  filter_status = "completed",
  page_size = 20
})

for _, call in ipairs(result.data) do
  print("Call: " .. call.call_session_id .. " - " .. call.status)
end
```

---

## get_call

Get details for a specific call.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `call_session_id` | string | yes | Call session ID |

### Example

```lua
local result = app.integrations.telnyx.get_call({
  call_session_id = "0ccc7b54-4e3a-4fa1-8c3f-5d2e3f4g5h6i"
})

print("Status: " .. result.data.status)
print("Duration: " .. result.data.duration .. "s")
```

---

## list_call_records

List call recordings.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page_size` | integer | no | Results per page (default: 20, max: 250) |
| `page_number` | integer | no | Page number (starts at 1) |
| `filter_call_session_id` | string | no | Filter by call session ID |
| `filter_conference_id` | string | no | Filter by conference ID |

### Example

```lua
local result = app.integrations.telnyx.list_call_records({
  filter_call_session_id = "0ccc7b54-4e3a-4fa1-8c3f-5d2e3f4g5h6i"
})

for _, rec in ipairs(result.data) do
  print("Recording: " .. rec.id .. " - " .. rec.duration .. "s")
  print("Download: " .. rec.download_urls[1])
end
```

---

## Multi-Account Usage

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

```lua
-- Default account
app.integrations.telnyx.send_sms({ from = "+1...", to = "+1...", text = "Hi" })

-- Named accounts
app.integrations.telnyx.work.send_sms({ from = "+1...", to = "+1...", text = "Hi" })
app.integrations.telnyx.personal.send_sms({ from = "+1...", to = "+1...", text = "Hi" })
```

All functions are identical across accounts — only the credentials differ.
Metadata-derived Lua example 
local result = app.integrations.telnyx.list_phone_numbers({page_size = 1, page_number = 1, filter_phone_number = "example_filter_phone_number", filter_status = "example_filter_status"})
print(result)

Functions

list_phone_numbers Read

List phone numbers on your Telnyx account. Returns phone number IDs, numbers in E.164 format, status, and billing details.

Lua path
app.integrations.telnyx.list_phone_numbers
Full name
telnyx.telnyx_list_phone_numbers
ParameterTypeRequiredDescription
page_size integer no Number of results per page (default: 20, max: 250).
page_number integer no Page number to retrieve (starts at 1).
filter_phone_number string no Filter by phone number in E.164 format (e.g., "+12345678900").
filter_status string no Filter by phone number status.
get_phone_number Read

Get details for a specific phone number by its ID. Returns the number, status, connection, and billing information.

Lua path
app.integrations.telnyx.get_phone_number
Full name
telnyx.telnyx_get_phone_number
ParameterTypeRequiredDescription
phone_number_id string yes The Telnyx phone number ID (e.g., "1293384265029123456").
list_messages Read

List SMS and MMS messages sent and received on your Telnyx account. Supports filtering by direction, phone number, and date range.

Lua path
app.integrations.telnyx.list_messages
Full name
telnyx.telnyx_list_messages
ParameterTypeRequiredDescription
page_size integer no Number of results per page (default: 20, max: 250).
page_number integer no Page number to retrieve (starts at 1).
direction string no Filter by message direction.
filter_source string no Filter by source phone number in E.164 format.
filter_destination string no Filter by destination phone number in E.164 format.
filter_status string no Filter by delivery status.
send_sms Write

Send an SMS or MMS message via Telnyx. Provide a sender phone number (from your Telnyx account), a destination number, and the message body.

Lua path
app.integrations.telnyx.send_sms
Full name
telnyx.telnyx_send_sms
ParameterTypeRequiredDescription
from string yes Sender phone number in E.164 format (e.g., "+12345678900"). Must be a number on your Telnyx account.
to string yes Destination phone number in E.164 format (e.g., "+19876543210").
text string yes The text body of the message.
subject string no Subject line (for MMS messages).
media_urls array no Array of media URLs to include as MMS attachments.
use_mms boolean no Set to true to send as MMS. Defaults to false (SMS).
list_calls Read

List voice calls made on your Telnyx account. Returns call session IDs, status, participants, and duration.

Lua path
app.integrations.telnyx.list_calls
Full name
telnyx.telnyx_list_calls
ParameterTypeRequiredDescription
page_size integer no Number of results per page (default: 20, max: 250).
page_number integer no Page number to retrieve (starts at 1).
filter_status string no Filter by call session status.
get_call Read

Get details for a specific voice call by its call session ID. Returns participants, status, duration, and call metadata.

Lua path
app.integrations.telnyx.get_call
Full name
telnyx.telnyx_get_call
ParameterTypeRequiredDescription
call_session_id string yes The Telnyx call session ID (e.g., "0ccc7b54-4e3a-4fa1-8c3f-5d2e3f4g5h6i").
list_call_recordings Read

List call recordings stored on your Telnyx account. Returns recording IDs, associated call sessions, download URLs, duration, and creation timestamps.

Lua path
app.integrations.telnyx.list_call_recordings
Full name
telnyx.telnyx_list_call_records
ParameterTypeRequiredDescription
page_size integer no Number of results per page (default: 20, max: 250).
page_number integer no Page number to retrieve (starts at 1).
filter_call_session_id string no Filter recordings by call session ID.
filter_conference_id string no Filter recordings by conference ID.