KosmoKrator

communication

Novu Lua API for KosmoKrator Agents

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

7 functions 5 read 2 write API key auth
Submit Novu feedback View package source

Lua Namespace

Agents call this integration through app.integrations.novu.*. Use lua_read_doc("integrations.novu") 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.

Novu — Lua API Reference

list_notifications

List notifications from Novu with optional filtering.

Parameters

NameTypeRequiredDescription
pageintegernoPage number (1-based, default: 1)
limitintegernoItems per page (default: 10, max: 100)
channelstringnoFilter by channel: in_app, email, sms, chat, push

Examples

-- List recent notifications
local result = app.integrations.novu.list_notifications({
  page = 1,
  limit = 20
})

-- Filter by email channel
local result = app.integrations.novu.list_notifications({
  channel = "email",
  limit = 50
})

get_notification

Get details of a specific notification.

Parameters

NameTypeRequiredDescription
idstringyesThe notification ID

Example

local result = app.integrations.novu.get_notification({
  id = "notification-id-here"
})

list_subscribers

List all notification subscribers.

Parameters

NameTypeRequiredDescription
pageintegernoPage number (0-based, default: 0)
limitintegernoItems per page (default: 10, max: 100)

Example

local result = app.integrations.novu.list_subscribers({
  page = 0,
  limit = 50
})

for _, subscriber in ipairs(result.data) do
  print(subscriber.email)
end

get_subscriber

Get details of a specific subscriber.

Parameters

NameTypeRequiredDescription
idstringyesThe subscriber ID

Example

local result = app.integrations.novu.get_subscriber({
  id = "subscriber-id-here"
})
print(result.email)
print(result.first_name)

create_subscriber

Create a new notification subscriber.

Parameters

NameTypeRequiredDescription
emailstringyesEmail address
firstNamestringnoFirst name
lastNamestringnoLast name
phonestringnoPhone number (e.g., “+1234567890”)

Example

local result = app.integrations.novu.create_subscriber({
  email = "[email protected]",
  firstName = "John",
  lastName = "Doe",
  phone = "+1234567890"
})

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

trigger_event

Trigger a notification event to one or more subscribers.

Parameters

NameTypeRequiredDescription
namestringyesWorkflow trigger key / template name
tostringyesSubscriber ID, email, or JSON array of recipients
payloadobjectnoKey-value template variables

Examples

-- Trigger to a single subscriber by email
local result = app.integrations.novu.trigger_event({
  name = "onboarding-welcome",
  to = "[email protected]",
  payload = { name = "John", plan = "Pro" }
})

-- Trigger to a single subscriber by ID
local result = app.integrations.novu.trigger_event({
  name = "order-confirmation",
  to = "subscriber-id-here",
  payload = { orderNumber = "ORD-123", total = "$99.00" }
})

-- Trigger to multiple recipients
local result = app.integrations.novu.trigger_event({
  name = "team-update",
  to = '["[email protected]", "[email protected]"]',
  payload = { message = "Sprint review tomorrow at 3pm" }
})

get_current_user

Get the currently authenticated Novu user.

Parameters

None.

Example

local result = app.integrations.novu.get_current_user({})
print("Logged in as: " .. result.email)
print("Organization: " .. result.organization.name)

Multi-Account Usage

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

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

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

-- Named accounts
app.integrations.novu.production.function_name({...})
app.integrations.novu.staging.function_name({...})

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

Raw agent markdown 
# Novu — Lua API Reference

## list_notifications

List notifications from Novu with optional filtering.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | no | Page number (1-based, default: 1) |
| `limit` | integer | no | Items per page (default: 10, max: 100) |
| `channel` | string | no | Filter by channel: `in_app`, `email`, `sms`, `chat`, `push` |

### Examples

```lua
-- List recent notifications
local result = app.integrations.novu.list_notifications({
  page = 1,
  limit = 20
})

-- Filter by email channel
local result = app.integrations.novu.list_notifications({
  channel = "email",
  limit = 50
})
```

---

## get_notification

Get details of a specific notification.

### Parameters

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

### Example

```lua
local result = app.integrations.novu.get_notification({
  id = "notification-id-here"
})
```

---

## list_subscribers

List all notification subscribers.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | no | Page number (0-based, default: 0) |
| `limit` | integer | no | Items per page (default: 10, max: 100) |

### Example

```lua
local result = app.integrations.novu.list_subscribers({
  page = 0,
  limit = 50
})

for _, subscriber in ipairs(result.data) do
  print(subscriber.email)
end
```

---

## get_subscriber

Get details of a specific subscriber.

### Parameters

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

### Example

```lua
local result = app.integrations.novu.get_subscriber({
  id = "subscriber-id-here"
})
print(result.email)
print(result.first_name)
```

---

## create_subscriber

Create a new notification subscriber.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `email` | string | yes | Email address |
| `firstName` | string | no | First name |
| `lastName` | string | no | Last name |
| `phone` | string | no | Phone number (e.g., "+1234567890") |

### Example

```lua
local result = app.integrations.novu.create_subscriber({
  email = "[email protected]",
  firstName = "John",
  lastName = "Doe",
  phone = "+1234567890"
})

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

---

## trigger_event

Trigger a notification event to one or more subscribers.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | string | yes | Workflow trigger key / template name |
| `to` | string | yes | Subscriber ID, email, or JSON array of recipients |
| `payload` | object | no | Key-value template variables |

### Examples

```lua
-- Trigger to a single subscriber by email
local result = app.integrations.novu.trigger_event({
  name = "onboarding-welcome",
  to = "[email protected]",
  payload = { name = "John", plan = "Pro" }
})

-- Trigger to a single subscriber by ID
local result = app.integrations.novu.trigger_event({
  name = "order-confirmation",
  to = "subscriber-id-here",
  payload = { orderNumber = "ORD-123", total = "$99.00" }
})

-- Trigger to multiple recipients
local result = app.integrations.novu.trigger_event({
  name = "team-update",
  to = '["[email protected]", "[email protected]"]',
  payload = { message = "Sprint review tomorrow at 3pm" }
})
```

---

## get_current_user

Get the currently authenticated Novu user.

### Parameters

None.

### Example

```lua
local result = app.integrations.novu.get_current_user({})
print("Logged in as: " .. result.email)
print("Organization: " .. result.organization.name)
```

---

## Multi-Account Usage

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

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

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

-- Named accounts
app.integrations.novu.production.function_name({...})
app.integrations.novu.staging.function_name({...})
```

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

Metadata-Derived Lua Example

local result = app.integrations.novu.novu_list_notifications({
  page = 1,
  limit = 1,
  channel = "example_channel"
})
print(result)

Functions

novu_list_notifications

List notifications from Novu. Returns a paginated list of notifications, optionally filtered by channel (e.g., in_app, email, sms, chat, push).

Operation
Read read
Full name
novu.novu_list_notifications
ParameterTypeRequiredDescription
page integer no Page number for pagination (1-based, default: 1).
limit integer no Number of notifications per page (default: 10, max: 100).
channel string no Filter by notification channel. Options: in_app, email, sms, chat, push.

novu_get_notification

Get details of a specific notification in Novu by its ID. Returns the full notification object including status, channel data, and content.

Operation
Read read
Full name
novu.novu_get_notification
ParameterTypeRequiredDescription
id string yes The notification ID.

novu_list_subscribers

List subscribers from Novu. Returns a paginated list of all notification subscribers with their details.

Operation
Read read
Full name
novu.novu_list_subscribers
ParameterTypeRequiredDescription
page integer no Page number for pagination (0-based, default: 0).
limit integer no Number of subscribers per page (default: 10, max: 100).

novu_get_subscriber

Get details of a specific subscriber in Novu by their ID. Returns the subscriber profile including email, phone, and preferences.

Operation
Read read
Full name
novu.novu_get_subscriber
ParameterTypeRequiredDescription
id string yes The subscriber ID.

novu_create_subscriber

Create a new subscriber in Novu. Requires an email address. Optionally include first name, last name, and phone number.

Operation
Write write
Full name
novu.novu_create_subscriber
ParameterTypeRequiredDescription
email string yes The subscriber's email address.
firstName string no The subscriber's first name.
lastName string no The subscriber's last name.
phone string no The subscriber's phone number (e.g., "+1234567890").

novu_trigger_event

Trigger a notification event in Novu. Sends a notification based on a workflow template to one or more subscribers. The "to" field can be a subscriber ID, email address, or an array of recipients.

Operation
Write write
Full name
novu.novu_trigger_event
ParameterTypeRequiredDescription
name string yes The workflow trigger key / template name (e.g., "onboarding-welcome").
to string yes Recipient — a subscriber ID, email address, or JSON-encoded array of recipient identifiers.
payload object no Key-value pairs to pass as template variables (e.g., {"name": "John", "plan": "Pro"}).

novu_get_current_user

Get the currently authenticated Novu user. Returns user profile information including name, email, and organization details.

Operation
Read read
Full name
novu.novu_get_current_user
ParameterTypeRequiredDescription
No parameters.