Can I use MessageBird as a CLI?

Yes. KosmoKrator exposes a MessageBird CLI through kosmo integrations:call and the provider shortcut command. Commands can return JSON for scripts, CI, and coding agents.

Can I expose MessageBird through MCP?

Yes. The KosmoKrator MCP gateway can expose selected MessageBird tools to clients such as Claude Code, Cursor, Codex, and other MCP-compatible tools.

Where are MessageBird credentials stored?

MessageBird credentials are configured in KosmoKrator's local integration settings and reused by CLI, Lua, and MCP gateway surfaces.

Can I deny write access for MessageBird MCP tools?

Yes. Start the gateway with --write=deny for read-only clients, or use ask/allow only for trusted workspaces.

productivity

MessageBird Lua API for KosmoKrator Agents

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

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.

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 MessageBird workflow without starting an interactive agent session.

Inline Lua call

kosmo integrations:lua --eval 'dump(app.integrations.messagebird.send_sms({originator = "example_originator", recipients = "example_recipients", body = "example_body", options = "example_options"}))' --json

Read Lua docs headlessly

kosmo integrations:lua --eval 'print(docs.read("messagebird"))' --json
kosmo integrations:lua --eval 'print(docs.read("messagebird.send_sms"))' --json

Workflow file

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

workflow.lua

local messagebird = app.integrations.messagebird
local result = messagebird.send_sms({originator = "example_originator", recipients = "example_recipients", body = "example_body", options = "example_options"})

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

MCP-only Lua

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

MessageBird - Lua API Reference

Namespace: app.integrations.messagebird

This integration wraps MessageBird’s classic REST API at https://rest.messagebird.com using Authorization: AccessKey .... It covers SMS, voice messages, contacts, groups, lookup/HLR, Verify, balance, and purchased numbers.

SMS Messages

app.integrations.messagebird.send_sms({
  originator = "ExampleCo",
  recipients = {"31612345678"},
  body = "Your order is ready.",
  options = { reference = "ord_123" }
})

local messages = app.integrations.messagebird.list_messages({
  limit = 20,
  status = "delivered",
  direction = "mt"
})

local message = app.integrations.messagebird.get_message({ id = "msg_123" })
app.integrations.messagebird.delete_message({ id = "msg_123" })

delete_message only applies to messages the API still allows cancelling, such as scheduled messages.

Voice Messages

app.integrations.messagebird.send_voice_message({
  originator = "31612345678",
  recipients = {"31687654321"},
  body = "This is a voice notification.",
  options = { language = "en-gb", voice = "female", repeat = 1 }
})

local voice_messages = app.integrations.messagebird.list_voice_messages({ limit = 20 })
local voice_message = app.integrations.messagebird.get_voice_message({ id = "voice_123" })
app.integrations.messagebird.delete_voice_message({ id = "voice_123" })

Contacts

local contacts = app.integrations.messagebird.list_contacts({ limit = 20 })

local contact = app.integrations.messagebird.create_contact({
  contact = {
    msisdn = 31612345678,
    firstName = "Ada",
    lastName = "Lovelace",
    customDetails = { custom1 = "customer" }
  }
})

local saved = app.integrations.messagebird.get_contact({ id = "contact_123" })

app.integrations.messagebird.update_contact({
  id = "contact_123",
  contact = { firstName = "Ada" }
})

local groups = app.integrations.messagebird.list_contact_groups({ id = "contact_123" })
local messages = app.integrations.messagebird.list_contact_messages({ id = "contact_123" })

delete_contact({ id = "contact_123" }) removes the contact.

Groups

local groups = app.integrations.messagebird.list_groups({ limit = 20 })
local group = app.integrations.messagebird.create_group({ name = "Customers" })
local one = app.integrations.messagebird.get_group({ id = "group_123" })

app.integrations.messagebird.update_group({
  id = "group_123",
  name = "VIP Customers"
})

local group_contacts = app.integrations.messagebird.list_group_contacts({
  id = "group_123"
})

app.integrations.messagebird.add_contact_to_group({
  group_id = "group_123",
  contact_id = "contact_123"
})

app.integrations.messagebird.remove_contact_from_group({
  group_id = "group_123",
  contact_id = "contact_123"
})

delete_group({ id = "group_123" }) deletes a group.

Lookup And HLR

local lookup = app.integrations.messagebird.lookup_phone_number({
  phone_number = "31612345678",
  country_code = "NL"
})

local hlr = app.integrations.messagebird.get_hlr_lookup({
  phone_number = "31612345678"
})

local requested = app.integrations.messagebird.request_hlr_lookup({
  phone_number = "31612345678",
  options = { reference = "crm_check_123" }
})

HLR requests can incur provider costs. Use them when active network/operator status is needed, not for simple formatting checks.

Verify

local verify = app.integrations.messagebird.create_verify({
  recipient = "31612345678",
  options = {
    originator = "Code",
    type = "sms",
    template = "Your code is %token"
  }
})

local status = app.integrations.messagebird.get_verify({ id = verify.id })

local checked = app.integrations.messagebird.verify_token({
  id = verify.id,
  token = "123456"
})

delete_verify({ id = "verify_123" }) deletes or cancels a verification.

Balance And Numbers

local balance = app.integrations.messagebird.list_balance({})
local account = app.integrations.messagebird.get_current_user({})

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

local number = app.integrations.messagebird.get_number({
  number = "31612345678"
})

app.integrations.messagebird.update_number({
  number = "31612345678",
  settings = { smsUrl = "https://example.test/messagebird/inbound" }
})

get_current_user is an account-level balance check because the classic MessageBird REST API does not expose a richer current-user endpoint.

Multi-Account Usage

app.integrations.messagebird.send_sms({...})
app.integrations.messagebird.default.send_sms({...})
app.integrations.messagebird.production.send_sms({...})

Named account namespaces use the same functions with different stored credentials.

Raw agent markdown

# MessageBird - Lua API Reference

Namespace: `app.integrations.messagebird`

This integration wraps MessageBird's classic REST API at `https://rest.messagebird.com` using `Authorization: AccessKey ...`. It covers SMS, voice messages, contacts, groups, lookup/HLR, Verify, balance, and purchased numbers.

## SMS Messages

```lua
app.integrations.messagebird.send_sms({
  originator = "ExampleCo",
  recipients = {"31612345678"},
  body = "Your order is ready.",
  options = { reference = "ord_123" }
})

local messages = app.integrations.messagebird.list_messages({
  limit = 20,
  status = "delivered",
  direction = "mt"
})

local message = app.integrations.messagebird.get_message({ id = "msg_123" })
app.integrations.messagebird.delete_message({ id = "msg_123" })
```

`delete_message` only applies to messages the API still allows cancelling, such as scheduled messages.

## Voice Messages

```lua
app.integrations.messagebird.send_voice_message({
  originator = "31612345678",
  recipients = {"31687654321"},
  body = "This is a voice notification.",
  options = { language = "en-gb", voice = "female", repeat = 1 }
})

local voice_messages = app.integrations.messagebird.list_voice_messages({ limit = 20 })
local voice_message = app.integrations.messagebird.get_voice_message({ id = "voice_123" })
app.integrations.messagebird.delete_voice_message({ id = "voice_123" })
```

## Contacts

```lua
local contacts = app.integrations.messagebird.list_contacts({ limit = 20 })

local contact = app.integrations.messagebird.create_contact({
  contact = {
    msisdn = 31612345678,
    firstName = "Ada",
    lastName = "Lovelace",
    customDetails = { custom1 = "customer" }
  }
})

local saved = app.integrations.messagebird.get_contact({ id = "contact_123" })

app.integrations.messagebird.update_contact({
  id = "contact_123",
  contact = { firstName = "Ada" }
})

local groups = app.integrations.messagebird.list_contact_groups({ id = "contact_123" })
local messages = app.integrations.messagebird.list_contact_messages({ id = "contact_123" })
```

`delete_contact({ id = "contact_123" })` removes the contact.

## Groups

```lua
local groups = app.integrations.messagebird.list_groups({ limit = 20 })
local group = app.integrations.messagebird.create_group({ name = "Customers" })
local one = app.integrations.messagebird.get_group({ id = "group_123" })

app.integrations.messagebird.update_group({
  id = "group_123",
  name = "VIP Customers"
})

local group_contacts = app.integrations.messagebird.list_group_contacts({
  id = "group_123"
})

app.integrations.messagebird.add_contact_to_group({
  group_id = "group_123",
  contact_id = "contact_123"
})

app.integrations.messagebird.remove_contact_from_group({
  group_id = "group_123",
  contact_id = "contact_123"
})
```

`delete_group({ id = "group_123" })` deletes a group.

## Lookup And HLR

```lua
local lookup = app.integrations.messagebird.lookup_phone_number({
  phone_number = "31612345678",
  country_code = "NL"
})

local hlr = app.integrations.messagebird.get_hlr_lookup({
  phone_number = "31612345678"
})

local requested = app.integrations.messagebird.request_hlr_lookup({
  phone_number = "31612345678",
  options = { reference = "crm_check_123" }
})
```

HLR requests can incur provider costs. Use them when active network/operator status is needed, not for simple formatting checks.

## Verify

```lua
local verify = app.integrations.messagebird.create_verify({
  recipient = "31612345678",
  options = {
    originator = "Code",
    type = "sms",
    template = "Your code is %token"
  }
})

local status = app.integrations.messagebird.get_verify({ id = verify.id })

local checked = app.integrations.messagebird.verify_token({
  id = verify.id,
  token = "123456"
})
```

`delete_verify({ id = "verify_123" })` deletes or cancels a verification.

## Balance And Numbers

```lua
local balance = app.integrations.messagebird.list_balance({})
local account = app.integrations.messagebird.get_current_user({})

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

local number = app.integrations.messagebird.get_number({
  number = "31612345678"
})

app.integrations.messagebird.update_number({
  number = "31612345678",
  settings = { smsUrl = "https://example.test/messagebird/inbound" }
})
```

`get_current_user` is an account-level balance check because the classic MessageBird REST API does not expose a richer current-user endpoint.

## Multi-Account Usage

```lua
app.integrations.messagebird.send_sms({...})
app.integrations.messagebird.default.send_sms({...})
app.integrations.messagebird.production.send_sms({...})
```

Named account namespaces use the same functions with different stored credentials.

Metadata-derived Lua example

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

Functions

send_sms Write

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

Lua path: app.integrations.messagebird.send_sms
Full name: messagebird.messagebird_send_sms

Parameter	Type	Required	Description
`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.
`options`	object	no	Optional MessageBird SMS parameters such as reference, scheduledDatetime, type, datacoding, validity, reportUrl.

list Read

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

Lua path: app.integrations.messagebird.list
Full name: messagebird.messagebird_list_messages

Parameter	Type	Required	Description
`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).
`originator`	string	no	Filter by originator.
`recipient`	string	no	Filter by recipient.
`contact_id`	string	no	Filter by contact ID.

get Read

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

Lua path: app.integrations.messagebird.get
Full name: messagebird.messagebird_get_message

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

delete Write

Delete a scheduled MessageBird SMS message.

Lua path: app.integrations.messagebird.delete
Full name: messagebird.messagebird_delete_message

Parameter	Type	Required	Description
`id`	string	yes	Message ID.

send_voice Write

Send a MessageBird text-to-speech voice message.

Lua path: app.integrations.messagebird.send_voice
Full name: messagebird.messagebird_send_voice_message

Parameter	Type	Required	Description
`originator`	string	yes	Sender phone number.
`recipients`	array	yes	Recipient phone numbers or contact IDs.
`body`	string	yes	Voice message text.
`options`	object	no	Optional voice settings such as language, voice, repeat, ifMachine, machineTimeout, scheduledDatetime.

list_voice Read

List MessageBird voice messages with optional filters.

Lua path: app.integrations.messagebird.list_voice
Full name: messagebird.messagebird_list_voice_messages

Parameter	Type	Required	Description
`limit`	integer	no	Maximum results.
`offset`	integer	no	Pagination offset.
`originator`	string	no	Filter by originator.
`recipient`	string	no	Filter by recipient.
`status`	string	no	Filter by voice message status.
`contact_id`	string	no	Filter by contact ID.

get_voice Read

Get a MessageBird voice message by ID.

Lua path: app.integrations.messagebird.get_voice
Full name: messagebird.messagebird_get_voice_message

Parameter	Type	Required	Description
`id`	string	yes	Voice message ID.

delete_voice Write

Delete a scheduled MessageBird voice message.

Lua path: app.integrations.messagebird.delete_voice
Full name: messagebird.messagebird_delete_voice_message

Parameter	Type	Required	Description
`id`	string	yes	Voice message ID.

list_contacts Read

List MessageBird contacts.

Lua path: app.integrations.messagebird.list_contacts
Full name: messagebird.messagebird_list_contacts

Parameter	Type	Required	Description
`limit`	integer	no	Maximum results.
`offset`	integer	no	Pagination offset.

create_contact Write

Create a MessageBird contact.

Lua path: app.integrations.messagebird.create_contact
Full name: messagebird.messagebird_create_contact

Parameter	Type	Required	Description
`contact`	object	yes	Contact payload with msisdn, firstName, lastName, customDetails.

get_contact Read

Get a MessageBird contact by ID.

Lua path: app.integrations.messagebird.get_contact
Full name: messagebird.messagebird_get_contact

Parameter	Type	Required	Description
`id`	string	yes	Contact ID.

update_contact Write

Update a MessageBird contact.

Lua path: app.integrations.messagebird.update_contact
Full name: messagebird.messagebird_update_contact

Parameter	Type	Required	Description
`id`	string	yes	Contact ID.
`contact`	object	yes	Contact fields to update.

delete_contact Write

Delete a MessageBird contact.

Lua path: app.integrations.messagebird.delete_contact
Full name: messagebird.messagebird_delete_contact

Parameter	Type	Required	Description
`id`	string	yes	Contact ID.

list_contact_groups Read

List groups for a MessageBird contact.

Lua path: app.integrations.messagebird.list_contact_groups
Full name: messagebird.messagebird_list_contact_groups

Parameter	Type	Required	Description
`id`	string	yes	Contact ID.

list_contact Read

List MessageBird messages for a contact.

Lua path: app.integrations.messagebird.list_contact
Full name: messagebird.messagebird_list_contact_messages

Parameter	Type	Required	Description
`id`	string	yes	Contact ID.
`params`	object	no	Optional query parameters.

list_groups Read

List MessageBird contact groups.

Lua path: app.integrations.messagebird.list_groups
Full name: messagebird.messagebird_list_groups

Parameter	Type	Required	Description
`limit`	integer	no	Maximum results.
`offset`	integer	no	Pagination offset.

create_group Write

Create a MessageBird contact group.

Lua path: app.integrations.messagebird.create_group
Full name: messagebird.messagebird_create_group

Parameter	Type	Required	Description
`name`	string	yes	Group name.

get_group Read

Get a MessageBird contact group.

Lua path: app.integrations.messagebird.get_group
Full name: messagebird.messagebird_get_group

Parameter	Type	Required	Description
`id`	string	yes	Group ID.

update_group Write

Update a MessageBird contact group.

Lua path: app.integrations.messagebird.update_group
Full name: messagebird.messagebird_update_group

Parameter	Type	Required	Description
`id`	string	yes	Group ID.
`name`	string	yes	New group name.

delete_group Write

Delete a MessageBird contact group.

Lua path: app.integrations.messagebird.delete_group
Full name: messagebird.messagebird_delete_group

Parameter	Type	Required	Description
`id`	string	yes	Group ID.

list_group_contacts Read

List contacts in a MessageBird group.

Lua path: app.integrations.messagebird.list_group_contacts
Full name: messagebird.messagebird_list_group_contacts

Parameter	Type	Required	Description
`id`	string	yes	Group ID.
`params`	object	no	Optional query parameters.

add_contact_group Write

Add a contact to a MessageBird group.

Lua path: app.integrations.messagebird.add_contact_group
Full name: messagebird.messagebird_add_contact_to_group

Parameter	Type	Required	Description
`group_id`	string	yes	Group ID.
`contact_id`	string	yes	Contact ID.

remove_contact_from_group Write

Remove a contact from a MessageBird group.

Lua path: app.integrations.messagebird.remove_contact_from_group
Full name: messagebird.messagebird_remove_contact_from_group

Parameter	Type	Required	Description
`group_id`	string	yes	Group ID.
`contact_id`	string	yes	Contact ID.

lookup_phone_number Read

Validate and look up a phone number with MessageBird Lookup.

Lua path: app.integrations.messagebird.lookup_phone_number
Full name: messagebird.messagebird_lookup_phone_number

Parameter	Type	Required	Description
`phone_number`	string	yes	Phone number to look up.
`country_code`	string	no	Optional ISO country code for national numbers.

get_hlr_lookup Read

Get MessageBird HLR lookup information for a phone number.

Lua path: app.integrations.messagebird.get_hlr_lookup
Full name: messagebird.messagebird_get_hlr_lookup

Parameter	Type	Required	Description
`phone_number`	string	yes	Phone number.

request_hlr_lookup Write

Request a MessageBird HLR lookup for a phone number.

Lua path: app.integrations.messagebird.request_hlr_lookup
Full name: messagebird.messagebird_request_hlr_lookup

Parameter	Type	Required	Description
`phone_number`	string	yes	Phone number.
`options`	object	no	Optional HLR lookup parameters.

create_verify Write

Create a MessageBird Verify request and send a token.

Lua path: app.integrations.messagebird.create_verify
Full name: messagebird.messagebird_create_verify

Parameter	Type	Required	Description
`recipient`	string	yes	Phone number or email to verify.
`options`	object	no	Optional verify parameters: originator, reference, type, template, timeout, tokenLength, datacoding.

get_verify Read

Get a MessageBird Verify request by ID.

Lua path: app.integrations.messagebird.get_verify
Full name: messagebird.messagebird_get_verify

Parameter	Type	Required	Description
`id`	string	yes	Verify ID.

verify_token Write

Verify a token for a MessageBird Verify request.

Lua path: app.integrations.messagebird.verify_token
Full name: messagebird.messagebird_verify_token

Parameter	Type	Required	Description
`id`	string	yes	Verify ID.
`token`	string	yes	Token sent to the recipient.

delete_verify Write

Delete a MessageBird Verify request.

Lua path: app.integrations.messagebird.delete_verify
Full name: messagebird.messagebird_delete_verify

Parameter	Type	Required	Description
`id`	string	yes	Verify ID.

get_balance Read

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

Lua path: app.integrations.messagebird.get_balance
Full name: messagebird.messagebird_list_balance

Parameter	Type	Required	Description
No parameters.

list_numbers Read

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

Lua path: app.integrations.messagebird.list_numbers
Full name: messagebird.messagebird_list_numbers

Parameter	Type	Required	Description
`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.

get_number Read

Get a purchased MessageBird phone number.

Lua path: app.integrations.messagebird.get_number
Full name: messagebird.messagebird_get_number

Parameter	Type	Required	Description
`number`	string	yes	Purchased phone number.

update_number Write

Update settings for a purchased MessageBird phone number.

Lua path: app.integrations.messagebird.update_number
Full name: messagebird.messagebird_update_number

Parameter	Type	Required	Description
`number`	string	yes	Purchased phone number.
`settings`	object	yes	Number settings to update.

get_current_user Read

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

Lua path: app.integrations.messagebird.get_current_user
Full name: messagebird.messagebird_get_current_user

Parameter	Type	Required	Description
No parameters.