KosmoKrator

messaging

MessageBird Lua API for KosmoKrator Agents

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

6 functions 5 read 1 write API key auth
Submit MessageBird feedback View package source

Lua Namespace

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

MessageBird — Lua API Reference

send_sms

Send an SMS message to one or more recipients.

Parameters

NameTypeRequiredDescription
originatorstringyesSender name or phone number (e.g., "OpenCompany" or "+3197012345678"). Max 11 chars for alphanumeric.
recipientsarrayyesArray of phone numbers in international format, e.g., {"+31612345678", "+447912345678"}
bodystringyesSMS text. Max 160 chars for a single message; longer messages are concatenated.

Example

local result = app.integrations.messagebird.send_sms({
  originator = "OpenCompany",
  recipients = {"+31612345678"},
  body = "Hello from MessageBird!"
})

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

get_message

Retrieve details of a specific message by ID.

Parameters

NameTypeRequiredDescription
idstringyesThe message ID (e.g., "a6e89f50c0d25b35a212345678901234")

Example

local result = app.integrations.messagebird.get_message({
  id = "a6e89f50c0d25b35a212345678901234"
})

print("Status: " .. result.status)
print("Body: " .. result.body)

list_messages

List sent and received messages with optional filters.

Parameters

NameTypeRequiredDescription
limitintegernoMax results (default: 20, max: 1000)
offsetintegernoPagination offset (default: 0)
statusstringnoFilter: scheduled, sent, buffered, delivered, expired, delivery_failed
directionstringnoFilter: mt (outgoing), mo (incoming)

Example

local result = app.integrations.messagebird.list_messages({
  limit = 10,
  status = "delivered"
})

for _, msg in ipairs(result.items) do
  print(msg.id .. " -> " .. msg.status)
end

list_balance

Check your MessageBird account balance.

Parameters

None.

Example

local result = app.integrations.messagebird.list_balance({})

print("Balance: " .. result.amount .. " " .. result.type)

list_numbers

List purchased phone numbers with optional filters.

Parameters

NameTypeRequiredDescription
limitintegernoMax results (default: 20)
offsetintegernoPagination offset (default: 0)
country_codestringnoISO 3166-1 alpha-2 country code (e.g., "NL", "US")
number_typestringnoFilter: mobile, landline

Example

local result = app.integrations.messagebird.list_numbers({
  country_code = "NL",
  number_type = "mobile"
})

for _, num in ipairs(result.items) do
  print(num.number .. " (" .. num.country .. ")")
end

get_current_user

Get current account information and balance.

Parameters

None.

Example

local result = app.integrations.messagebird.get_current_user({})

print("Balance: " .. result.amount)
print("Payment type: " .. result.type)

Multi-Account Usage

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

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

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

-- Named accounts
app.integrations.messagebird.work.function_name({...})
app.integrations.messagebird.personal.function_name({...})

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

Raw agent markdown 
# MessageBird — Lua API Reference

## send_sms

Send an SMS message to one or more recipients.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `originator` | string | yes | Sender name or phone number (e.g., `"OpenCompany"` or `"+3197012345678"`). Max 11 chars for alphanumeric. |
| `recipients` | array | yes | Array of phone numbers in international format, e.g., `{"+31612345678", "+447912345678"}` |
| `body` | string | yes | SMS text. Max 160 chars for a single message; longer messages are concatenated. |

### Example

```lua
local result = app.integrations.messagebird.send_sms({
  originator = "OpenCompany",
  recipients = {"+31612345678"},
  body = "Hello from MessageBird!"
})

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

---

## get_message

Retrieve details of a specific message by ID.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | The message ID (e.g., `"a6e89f50c0d25b35a212345678901234"`) |

### Example

```lua
local result = app.integrations.messagebird.get_message({
  id = "a6e89f50c0d25b35a212345678901234"
})

print("Status: " .. result.status)
print("Body: " .. result.body)
```

---

## list_messages

List sent and received messages with optional filters.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | integer | no | Max results (default: 20, max: 1000) |
| `offset` | integer | no | Pagination offset (default: 0) |
| `status` | string | no | Filter: `scheduled`, `sent`, `buffered`, `delivered`, `expired`, `delivery_failed` |
| `direction` | string | no | Filter: `mt` (outgoing), `mo` (incoming) |

### Example

```lua
local result = app.integrations.messagebird.list_messages({
  limit = 10,
  status = "delivered"
})

for _, msg in ipairs(result.items) do
  print(msg.id .. " -> " .. msg.status)
end
```

---

## list_balance

Check your MessageBird account balance.

### Parameters

None.

### Example

```lua
local result = app.integrations.messagebird.list_balance({})

print("Balance: " .. result.amount .. " " .. result.type)
```

---

## list_numbers

List purchased phone numbers with optional filters.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | integer | no | Max results (default: 20) |
| `offset` | integer | no | Pagination offset (default: 0) |
| `country_code` | string | no | ISO 3166-1 alpha-2 country code (e.g., `"NL"`, `"US"`) |
| `number_type` | string | no | Filter: `mobile`, `landline` |

### Example

```lua
local result = app.integrations.messagebird.list_numbers({
  country_code = "NL",
  number_type = "mobile"
})

for _, num in ipairs(result.items) do
  print(num.number .. " (" .. num.country .. ")")
end
```

---

## get_current_user

Get current account information and balance.

### Parameters

None.

### Example

```lua
local result = app.integrations.messagebird.get_current_user({})

print("Balance: " .. result.amount)
print("Payment type: " .. result.type)
```

---

## Multi-Account Usage

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

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

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

-- Named accounts
app.integrations.messagebird.work.function_name({...})
app.integrations.messagebird.personal.function_name({...})
```

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

Metadata-Derived Lua Example

local result = app.integrations.messagebird.messagebird_send_sms({
  originator = "example_originator",
  recipients = "example_recipients",
  body = "example_body"
})
print(result)

Functions

messagebird_send_sms

Send an SMS message to one or more recipients via MessageBird. Specify a sender (originator), one or more phone numbers, and the message body.

Operation
Write write
Full name
messagebird.messagebird_send_sms
ParameterTypeRequiredDescription
originator string yes Sender name or phone number (e.g., "OpenCompany" or "+3197012345678"). Max 11 characters for alphanumeric, or a valid phone number.
recipients array yes Array of recipient phone numbers in international format (e.g., ["+31612345678", "+447912345678"]).
body string yes The SMS text message body. Max 160 characters for a single SMS; longer messages are concatenated and charged accordingly.

messagebird_get_message

Retrieve details of a specific MessageBird message by its ID, including status, recipient info, and delivery timestamps.

Operation
Read read
Full name
messagebird.messagebird_get_message
ParameterTypeRequiredDescription
id string yes The message ID (e.g., "a6e89f50c0d25b35a212345678901234").

messagebird_list_messages

List sent and received messages from MessageBird. Supports filtering by status and direction, with pagination.

Operation
Read read
Full name
messagebird.messagebird_list_messages
ParameterTypeRequiredDescription
limit integer no Maximum number of messages to return (default: 20, max: 1000).
offset integer no Offset for pagination (default: 0).
status string no Filter by message status: scheduled, sent, buffered, delivered, expired, delivery_failed.
direction string no Filter by direction: mt (outgoing / mobile terminated), mo (incoming / mobile originated).

messagebird_list_balance

Check your MessageBird account balance. Returns the available amount and payment type (prepaid or postpaid).

Operation
Read read
Full name
messagebird.messagebird_list_balance
ParameterTypeRequiredDescription
No parameters.

messagebird_list_numbers

List purchased phone numbers in your MessageBird account. Supports filtering by country code and number type.

Operation
Read read
Full name
messagebird.messagebird_list_numbers
ParameterTypeRequiredDescription
limit integer no Maximum number of numbers to return (default: 20).
offset integer no Offset for pagination (default: 0).
country_code string no Filter by ISO 3166-1 alpha-2 country code (e.g., "NL", "US", "GB").
number_type string no Filter by number type: mobile, landline.

messagebird_get_current_user

Get the current MessageBird account information, including balance and payment type.

Operation
Read read
Full name
messagebird.messagebird_get_current_user
ParameterTypeRequiredDescription
No parameters.