Can I use RingCentral as a CLI?

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

Can I expose RingCentral through MCP?

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

Where are RingCentral credentials stored?

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

Can I deny write access for RingCentral MCP tools?

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

productivity

RingCentral Lua API for KosmoKrator Agents

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

Lua Namespace

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

Inline Lua call

kosmo integrations:lua --eval 'dump(app.integrations.ringcentral.list_messages({messageType = "example_messageType", dateFrom = "example_dateFrom", dateTo = "example_dateTo", direction = "example_direction", readStatus = "example_readStatus", perPage = 1, page = 1}))' --json

Read Lua docs headlessly

kosmo integrations:lua --eval 'print(docs.read("ringcentral"))' --json
kosmo integrations:lua --eval 'print(docs.read("ringcentral.list_messages"))' --json

Workflow file

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

workflow.lua

local ringcentral = app.integrations.ringcentral
local result = ringcentral.list_messages({messageType = "example_messageType", dateFrom = "example_dateFrom", dateTo = "example_dateTo", direction = "example_direction", readStatus = "example_readStatus", perPage = 1, page = 1})

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

MCP-only Lua

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

RingCentral Lua API Reference

Namespace: app.integrations.ringcentral

This integration wraps the RingCentral REST API under /restapi/v1.0. It covers account and extension discovery, phone numbers, message store workflows, SMS, call logs, presence, personal contacts, and generic relative API calls for documented endpoints that do not yet have a named helper.

Account, Extensions, And Phone Numbers

local account = app.integrations.ringcentral.get_account({})

local extensions = app.integrations.ringcentral.list_extensions({
  extensionType = "User",
  perPage = 50
})

local extension = app.integrations.ringcentral.get_extension({
  extension_id = "123456789"
})

local account_numbers = app.integrations.ringcentral.list_account_phone_numbers({})
local my_numbers = app.integrations.ringcentral.list_extension_phone_numbers({})

Phone-number records include usage types such as MainCompanyNumber, CompanyNumber, and DirectNumber, plus type/capability data such as voice, fax, and SMS support.

Messages And SMS

local messages = app.integrations.ringcentral.list_messages({
  messageType = "Sms",
  dateFrom = "2026-05-01T00:00:00Z",
  perPage = 25
})

local message = app.integrations.ringcentral.get_message({
  messageId = "1234567890"
})

app.integrations.ringcentral.update_message({
  message_id = "1234567890",
  readStatus = "Read"
})

app.integrations.ringcentral.send_sms({
  from = "+16505551234",
  to = "+16505559876",
  text = "Hello from RingCentral"
})

The message store contains SMS, fax, pager, and voicemail records visible to the authenticated extension. Account-wide SMS history may require account-level reporting or admin workflows outside this extension mailbox endpoint.

Call Logs And Presence

local calls = app.integrations.ringcentral.list_calls({
  dateFrom = "2026-05-01T00:00:00Z",
  direction = "Inbound"
})

local account_calls = app.integrations.ringcentral.list_account_calls({
  dateFrom = "2026-05-01T00:00:00Z",
  perPage = 100
})

local presence = app.integrations.ringcentral.get_presence({
  detailedTelephonyState = true
})

Extension call logs show records for the authenticated extension. Account-level call logs may require admin privileges and broader scopes.

Contacts

local contacts = app.integrations.ringcentral.list_contacts({
  startsWith = "Acme"
})

local created = app.integrations.ringcentral.create_contact({
  firstName = "Ada",
  lastName = "Lovelace",
  mobilePhone = "+16505550100",
  email = "ada@example.test"
})

local updated = app.integrations.ringcentral.update_contact({
  contact_id = created.id,
  company = "Example"
})

Contact tools operate on the authenticated extension’s personal address book.

Generic API Tools

Use api_get, api_post, api_put, and api_delete for documented relative RingCentral API paths that are not wrapped yet. Absolute URLs are rejected.

local raw = app.integrations.ringcentral.api_get({
  path = "/restapi/v1.0/account/~/extension/~"
})

Account

get_current_user returns the authenticated extension. Multi-account namespaces expose the same tool set:

app.integrations.ringcentral.list_messages({})
app.integrations.ringcentral.default.list_messages({})
app.integrations.ringcentral.support.list_messages({})

Raw agent markdown

# RingCentral Lua API Reference

Namespace: `app.integrations.ringcentral`

This integration wraps the RingCentral REST API under `/restapi/v1.0`. It covers account and extension discovery, phone numbers, message store workflows, SMS, call logs, presence, personal contacts, and generic relative API calls for documented endpoints that do not yet have a named helper.

## Account, Extensions, And Phone Numbers

```lua
local account = app.integrations.ringcentral.get_account({})

local extensions = app.integrations.ringcentral.list_extensions({
  extensionType = "User",
  perPage = 50
})

local extension = app.integrations.ringcentral.get_extension({
  extension_id = "123456789"
})

local account_numbers = app.integrations.ringcentral.list_account_phone_numbers({})
local my_numbers = app.integrations.ringcentral.list_extension_phone_numbers({})
```

Phone-number records include usage types such as `MainCompanyNumber`, `CompanyNumber`, and `DirectNumber`, plus type/capability data such as voice, fax, and SMS support.

## Messages And SMS

```lua
local messages = app.integrations.ringcentral.list_messages({
  messageType = "Sms",
  dateFrom = "2026-05-01T00:00:00Z",
  perPage = 25
})

local message = app.integrations.ringcentral.get_message({
  messageId = "1234567890"
})

app.integrations.ringcentral.update_message({
  message_id = "1234567890",
  readStatus = "Read"
})

app.integrations.ringcentral.send_sms({
  from = "+16505551234",
  to = "+16505559876",
  text = "Hello from RingCentral"
})
```

The message store contains SMS, fax, pager, and voicemail records visible to the authenticated extension. Account-wide SMS history may require account-level reporting or admin workflows outside this extension mailbox endpoint.

## Call Logs And Presence

```lua
local calls = app.integrations.ringcentral.list_calls({
  dateFrom = "2026-05-01T00:00:00Z",
  direction = "Inbound"
})

local account_calls = app.integrations.ringcentral.list_account_calls({
  dateFrom = "2026-05-01T00:00:00Z",
  perPage = 100
})

local presence = app.integrations.ringcentral.get_presence({
  detailedTelephonyState = true
})
```

Extension call logs show records for the authenticated extension. Account-level call logs may require admin privileges and broader scopes.

## Contacts

```lua
local contacts = app.integrations.ringcentral.list_contacts({
  startsWith = "Acme"
})

local created = app.integrations.ringcentral.create_contact({
  firstName = "Ada",
  lastName = "Lovelace",
  mobilePhone = "+16505550100",
  email = "ada@example.test"
})

local updated = app.integrations.ringcentral.update_contact({
  contact_id = created.id,
  company = "Example"
})
```

Contact tools operate on the authenticated extension's personal address book.

## Generic API Tools

Use `api_get`, `api_post`, `api_put`, and `api_delete` for documented relative RingCentral API paths that are not wrapped yet. Absolute URLs are rejected.

```lua
local raw = app.integrations.ringcentral.api_get({
  path = "/restapi/v1.0/account/~/extension/~"
})
```

## Account

`get_current_user` returns the authenticated extension. Multi-account namespaces expose the same tool set:

```lua
app.integrations.ringcentral.list_messages({})
app.integrations.ringcentral.default.list_messages({})
app.integrations.ringcentral.support.list_messages({})
```

Metadata-derived Lua example

local result = app.integrations.ringcentral.list_messages({messageType = "example_messageType", dateFrom = "example_dateFrom", dateTo = "example_dateTo", direction = "example_direction", readStatus = "example_readStatus", perPage = 1, page = 1})
print(result)

Functions

list_messages Read

List messages from the RingCentral message store. Supports filtering by type (SMS, Fax, VoiceMail), date range, read status, and direction. Returns paginated message records.

Lua path: app.integrations.ringcentral.list_messages
Full name: ringcentral.ringcentral_list_messages

Parameter	Type	Required	Description
`messageType`	string	no	Filter by message type: Sms, Fax, VoiceMail, Pager, or All (default: All).
`dateFrom`	string	no	Start date for filtering (ISO 8601, e.g., "2025-01-01T00:00:00Z").
`dateTo`	string	no	End date for filtering (ISO 8601, e.g., "2025-01-31T23:59:59Z").
`direction`	string	no	Filter by direction: Inbound, Outbound, or All.
`readStatus`	string	no	Filter by read status: Read, Unread, or All.
`perPage`	integer	no	Number of records per page (default: 100, max: 1000).
`page`	integer	no	Page number for pagination (default: 1).

get_message Read

Get detailed information about a specific message in the RingCentral message store by its ID. Returns the full message record including sender, recipient, subject, and content.

Lua path: app.integrations.ringcentral.get_message
Full name: ringcentral.ringcentral_get_message

Parameter	Type	Required	Description
`messageId`	string	yes	The unique identifier of the message record.

update_message Write

Update a RingCentral message store record, commonly to set readStatus to Read or Unread.

Lua path: app.integrations.ringcentral.update_message
Full name: ringcentral.ringcentral_update_message

Parameter	Type	Required	Description
`message_id`	string	yes	Message record ID.
`readStatus`	string	no	Read or Unread.
`payload`	object	no	Additional official message update fields.

delete_message Write

Delete a message from the authenticated extension's RingCentral message store.

Lua path: app.integrations.ringcentral.delete_message
Full name: ringcentral.ringcentral_delete_message

Parameter	Type	Required	Description
`message_id`	string	yes	Message record ID.

send_sms Write

Send an SMS message via RingCentral. The "from" number must be a phone number assigned to the authenticated extension. The "to" number is the destination phone number.

Lua path: app.integrations.ringcentral.send_sms
Full name: ringcentral.ringcentral_send_sms

Parameter	Type	Required	Description
`from`	string	yes	The phone number to send from (must be a RingCentral number assigned to the extension, e.g., "+16505551234").
`to`	string	yes	The destination phone number (e.g., "+16505559876").
`text`	string	yes	The SMS message body text. Maximum 160 characters per segment; longer messages are concatenated.

list_calls Read

List call log records for the authenticated RingCentral extension. Supports filtering by date range, direction, type, and phone number. Returns paginated call records with caller, receiver, duration, and result.

Lua path: app.integrations.ringcentral.list_calls
Full name: ringcentral.ringcentral_list_calls

Parameter	Type	Required	Description
`dateFrom`	string	no	Start date for filtering (ISO 8601, e.g., "2025-01-01T00:00:00Z").
`dateTo`	string	no	End date for filtering (ISO 8601, e.g., "2025-01-31T23:59:59Z").
`direction`	string	no	Filter by direction: Inbound, Outbound, or All.
`type`	string	no	Filter by call type: Voice, Fax, or All.
`phoneNumber`	string	no	Filter by phone number (caller or receiver).
`perPage`	integer	no	Number of records per page (default: 100, max: 1000).
`page`	integer	no	Page number for pagination (default: 1).

list_account_calls Read

List account-level call log records for RingCentral. Admin permissions may be required.

Lua path: app.integrations.ringcentral.list_account_calls
Full name: ringcentral.ringcentral_list_account_calls

Parameter	Type	Required	Description
`dateFrom`	string	no	Start date for filtering.
`dateTo`	string	no	End date for filtering.
`direction`	string	no	Inbound, Outbound, or All.
`type`	string	no	Voice, Fax, or All.
`phoneNumber`	string	no	Filter by caller or receiver phone number.
`extensionNumber`	string	no	Filter by extension number.
`perPage`	integer	no	Records per page.
`page`	integer	no	Page number.

get_call Read

Get a single call log record for the authenticated RingCentral extension.

Lua path: app.integrations.ringcentral.get_call
Full name: ringcentral.ringcentral_get_call

Parameter	Type	Required	Description
`call_id`	string	yes	Call log record ID.

list_contacts Read

List contacts from the RingCentral personal address book. Supports filtering by name prefix and pagination. Returns contact records with names, phone numbers, and email addresses.

Lua path: app.integrations.ringcentral.list_contacts
Full name: ringcentral.ringcentral_list_contacts

Parameter	Type	Required	Description
`startsWith`	string	no	Filter contacts whose first name, last name, or company name starts with this string.
`perPage`	integer	no	Number of records per page (default: 100, max: 1000).
`page`	integer	no	Page number for pagination (default: 1).

get_contact Read

Get a RingCentral personal address book contact by contact ID.

Lua path: app.integrations.ringcentral.get_contact
Full name: ringcentral.ringcentral_get_contact

Parameter	Type	Required	Description
`contact_id`	string	yes	Address book contact ID.

create_contact Write

Create a contact in the authenticated RingCentral extension's personal address book.

Lua path: app.integrations.ringcentral.create_contact
Full name: ringcentral.ringcentral_create_contact

Parameter	Type	Required	Description
`firstName`	string	no	First name.
`lastName`	string	no	Last name.
`company`	string	no	Company name.
`email`	string	no	Email address.
`businessPhone`	string	no	Business phone number.
`mobilePhone`	string	no	Mobile phone number.
`payload`	object	no	Additional official contact fields.

update_contact Write

Update a RingCentral personal address book contact by contact ID.

Lua path: app.integrations.ringcentral.update_contact
Full name: ringcentral.ringcentral_update_contact

Parameter	Type	Required	Description
`contact_id`	string	yes	Address book contact ID.
`firstName`	string	no	First name.
`lastName`	string	no	Last name.
`company`	string	no	Company name.
`email`	string	no	Email address.
`businessPhone`	string	no	Business phone number.
`mobilePhone`	string	no	Mobile phone number.
`payload`	object	no	Additional official contact fields.

delete_contact Write

Delete a contact from the authenticated RingCentral extension's personal address book.

Lua path: app.integrations.ringcentral.delete_contact
Full name: ringcentral.ringcentral_delete_contact

Parameter	Type	Required	Description
`contact_id`	string	yes	Address book contact ID.

get_account Read

Get RingCentral account metadata for the authenticated token.

Lua path: app.integrations.ringcentral.get_account
Full name: ringcentral.ringcentral_get_account

Parameter	Type	Required	Description
No parameters.

list_extensions Read

List users and extensions in the RingCentral account with optional type/status filters and pagination.

Lua path: app.integrations.ringcentral.list_extensions
Full name: ringcentral.ringcentral_list_extensions

Parameter	Type	Required	Description
`extensionType`	string	no	Filter by extension type such as User, Department, or Announcement.
`status`	string	no	Filter by extension status.
`perPage`	integer	no	Records per page.
`page`	integer	no	Page number.

get_extension Read

Get details for a RingCentral extension by extension ID.

Lua path: app.integrations.ringcentral.get_extension
Full name: ringcentral.ringcentral_get_extension

Parameter	Type	Required	Description
`extension_id`	string	yes	RingCentral extension ID.

list_account_phone_numbers Read

List RingCentral account phone numbers, including usage type, phone number type, and assignment metadata.

Lua path: app.integrations.ringcentral.list_account_phone_numbers
Full name: ringcentral.ringcentral_list_account_phone_numbers

Parameter	Type	Required	Description
`usageType`	string	no	Filter by usage type such as MainCompanyNumber or DirectNumber.
`status`	string	no	Filter by phone number status.
`perPage`	integer	no	Records per page.
`page`	integer	no	Page number.

list_extension_phone_numbers Read

List phone numbers assigned to the authenticated RingCentral extension.

Lua path: app.integrations.ringcentral.list_extension_phone_numbers
Full name: ringcentral.ringcentral_list_extension_phone_numbers

Parameter	Type	Required	Description
`usageType`	string	no	Filter by usage type.
`perPage`	integer	no	Records per page.
`page`	integer	no	Page number.

get_presence Read

Get presence for the authenticated RingCentral extension, including telephony status and user status when available.

Lua path: app.integrations.ringcentral.get_presence
Full name: ringcentral.ringcentral_get_presence

Parameter	Type	Required	Description
`detailedTelephonyState`	boolean	no	Request detailed telephony state when supported.

get_current_user Read

Get information about the currently authenticated RingCentral extension. Returns extension ID, name, status, phone numbers, and account details.

Lua path: app.integrations.ringcentral.get_current_user
Full name: ringcentral.ringcentral_get_current_user

Parameter	Type	Required	Description
No parameters.

api_get Read

Call a relative RingCentral REST API GET path, such as "/restapi/v1.0/account/~". Absolute URLs are rejected.

Lua path: app.integrations.ringcentral.api_get
Full name: ringcentral.ringcentral_api_get

Parameter	Type	Required	Description
`path`	string	yes	Relative RingCentral API path.
`params`	object	no	Query parameters.

api_post Write

Call a relative RingCentral REST API POST path with a JSON body. Absolute URLs are rejected.

Lua path: app.integrations.ringcentral.api_post
Full name: ringcentral.ringcentral_api_post

Parameter	Type	Required	Description
`path`	string	yes	Relative RingCentral API path.
`payload`	object	no	JSON request body.

api_put Write

Call a relative RingCentral REST API PUT path with a JSON body. Absolute URLs are rejected.

Lua path: app.integrations.ringcentral.api_put
Full name: ringcentral.ringcentral_api_put

Parameter	Type	Required	Description
`path`	string	yes	Relative RingCentral API path.
`payload`	object	no	JSON request body.

api_delete Write

Call a relative RingCentral REST API DELETE path. Absolute URLs are rejected.

Lua path: app.integrations.ringcentral.api_delete
Full name: ringcentral.ringcentral_api_delete

Parameter	Type	Required	Description
`path`	string	yes	Relative RingCentral API path.
`payload`	object	no	Optional JSON body.