KosmoKrator

productivity

Aircall Lua API for KosmoKrator Agents

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

Lua Namespace

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

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.aircall.ping({}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("aircall"))' --json
kosmo integrations:lua --eval 'print(docs.read("aircall.ping"))' --json

Workflow file

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

workflow.lua 
local aircall = app.integrations.aircall
local result = aircall.ping({})

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

MCP-only Lua

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

Aircall Lua API Reference

Namespace: app.integrations.aircall

This integration targets Aircall Public API v1 and v2. Most list tools accept page, per_page, order, or a params object. Write tools accept a payload object or common top-level fields.

Aircall customers normally configure api_id and api_token for Basic Auth. Marketplace apps can instead provide an OAuth access_token; the same tools work with either credential mode.

Common Patterns

List calls:

local result = app.integrations.aircall.list_calls({
  from = 1704067200,
  to = 1706745600,
  per_page = 50,
  fetch_contact = true
})

Tag a call:

local result = app.integrations.aircall.tag_call({
  call_id = "123",
  tags = { 456, 789 }
})

Transfer a call:

local result = app.integrations.aircall.transfer_call({
  call_id = "123",
  user_id = "456"
})

Create a webhook:

local result = app.integrations.aircall.create_webhook({
  url = "https://example.test/aircall/webhook",
  events = { "call.created", "call.ended" }
})

Coverage

Tools cover users, teams, calls, conversation intelligence, dialer campaigns, numbers, contacts, tags, webhooks, company/integration metadata, and raw API helpers.

Raw API Helpers

local result = app.integrations.aircall.api_get({
  path = "/calls/search",
  params = {
    phone_number = "+15551234567"
  }
})

The path must be relative. /calls is normalized to /v1/calls; pass /v2/users explicitly for v2 user endpoints.

Raw agent markdown 
# Aircall Lua API Reference

Namespace: `app.integrations.aircall`

This integration targets Aircall Public API v1 and v2. Most list tools accept
`page`, `per_page`, `order`, or a `params` object. Write tools accept a
`payload` object or common top-level fields.

Aircall customers normally configure `api_id` and `api_token` for Basic Auth.
Marketplace apps can instead provide an OAuth `access_token`; the same tools
work with either credential mode.

## Common Patterns

List calls:

```lua
local result = app.integrations.aircall.list_calls({
  from = 1704067200,
  to = 1706745600,
  per_page = 50,
  fetch_contact = true
})
```

Tag a call:

```lua
local result = app.integrations.aircall.tag_call({
  call_id = "123",
  tags = { 456, 789 }
})
```

Transfer a call:

```lua
local result = app.integrations.aircall.transfer_call({
  call_id = "123",
  user_id = "456"
})
```

Create a webhook:

```lua
local result = app.integrations.aircall.create_webhook({
  url = "https://example.test/aircall/webhook",
  events = { "call.created", "call.ended" }
})
```

## Coverage

Tools cover users, teams, calls, conversation intelligence, dialer campaigns,
numbers, contacts, tags, webhooks, company/integration metadata, and raw API
helpers.

## Raw API Helpers

```lua
local result = app.integrations.aircall.api_get({
  path = "/calls/search",
  params = {
    phone_number = "+15551234567"
  }
})
```

The `path` must be relative. `/calls` is normalized to `/v1/calls`; pass
`/v2/users` explicitly for v2 user endpoints.
Metadata-derived Lua example 
local result = app.integrations.aircall.ping({})
print(result)

Functions

ping Read

Test the Aircall API token with the ping endpoint.

Lua path
app.integrations.aircall.ping
Full name
aircall.aircall_ping
ParameterTypeRequiredDescription
No parameters.
get_current_user Read

Retrieve the currently authenticated user.

Lua path
app.integrations.aircall.get_current_user
Full name
aircall.aircall_get_current_user
ParameterTypeRequiredDescription
No parameters.
list_users Read

List users in the Aircall account.

Lua path
app.integrations.aircall.list_users
Full name
aircall.aircall_list_users
ParameterTypeRequiredDescription
No parameters.
get_user Read

Retrieve a user by ID or email.

Lua path
app.integrations.aircall.get_user
Full name
aircall.aircall_get_user
ParameterTypeRequiredDescription
No parameters.
create_user Write

Create a user.

Lua path
app.integrations.aircall.create_user
Full name
aircall.aircall_create_user
ParameterTypeRequiredDescription
No parameters.
update_user Write

Update a user.

Lua path
app.integrations.aircall.update_user
Full name
aircall.aircall_update_user
ParameterTypeRequiredDescription
No parameters.
delete_user Write

Delete a user.

Lua path
app.integrations.aircall.delete_user
Full name
aircall.aircall_delete_user
ParameterTypeRequiredDescription
No parameters.
list_user_availabilities Read

List users availability.

Lua path
app.integrations.aircall.list_user_availabilities
Full name
aircall.aircall_list_user_availabilities
ParameterTypeRequiredDescription
No parameters.
get_user_availability Read

Retrieve one user availability.

Lua path
app.integrations.aircall.get_user_availability
Full name
aircall.aircall_get_user_availability
ParameterTypeRequiredDescription
No parameters.
start_outbound Write

Start an outbound call from a user phone app.

Lua path
app.integrations.aircall.start_outbound
Full name
aircall.aircall_start_outbound_call
ParameterTypeRequiredDescription
No parameters.
dial_user_phone Write

Dial a phone number in a user phone app.

Lua path
app.integrations.aircall.dial_user_phone
Full name
aircall.aircall_dial_user_phone
ParameterTypeRequiredDescription
No parameters.
list_users_v2 Read

List users using the v2 user API.

Lua path
app.integrations.aircall.list_users_v2
Full name
aircall.aircall_list_users_v2
ParameterTypeRequiredDescription
No parameters.
get_user_v2 Read

Retrieve a user using the v2 user API.

Lua path
app.integrations.aircall.get_user_v2
Full name
aircall.aircall_get_user_v2
ParameterTypeRequiredDescription
No parameters.
create_user_v2 Write

Create a user using the v2 user API.

Lua path
app.integrations.aircall.create_user_v2
Full name
aircall.aircall_create_user_v2
ParameterTypeRequiredDescription
No parameters.
update_user_v2 Write

Update a user using the v2 user API.

Lua path
app.integrations.aircall.update_user_v2
Full name
aircall.aircall_update_user_v2
ParameterTypeRequiredDescription
No parameters.
list_user_numbers_v2 Read

List numbers assigned to a v2 user.

Lua path
app.integrations.aircall.list_user_numbers_v2
Full name
aircall.aircall_list_user_numbers_v2
ParameterTypeRequiredDescription
No parameters.
list_teams Read

List teams.

Lua path
app.integrations.aircall.list_teams
Full name
aircall.aircall_list_teams
ParameterTypeRequiredDescription
No parameters.
get_team Read

Retrieve a team.

Lua path
app.integrations.aircall.get_team
Full name
aircall.aircall_get_team
ParameterTypeRequiredDescription
No parameters.
create_team Write

Create a team.

Lua path
app.integrations.aircall.create_team
Full name
aircall.aircall_create_team
ParameterTypeRequiredDescription
No parameters.
delete_team Write

Delete a team.

Lua path
app.integrations.aircall.delete_team
Full name
aircall.aircall_delete_team
ParameterTypeRequiredDescription
No parameters.
add_user_team Write

Add a user to a team.

Lua path
app.integrations.aircall.add_user_team
Full name
aircall.aircall_add_user_to_team
ParameterTypeRequiredDescription
No parameters.
remove_user_from_team Write

Remove a user from a team.

Lua path
app.integrations.aircall.remove_user_from_team
Full name
aircall.aircall_remove_user_from_team
ParameterTypeRequiredDescription
No parameters.
list Read

List calls with filters and pagination.

Lua path
app.integrations.aircall.list
Full name
aircall.aircall_list_calls
ParameterTypeRequiredDescription
No parameters.
get Read

Retrieve details of a specific call.

Lua path
app.integrations.aircall.get
Full name
aircall.aircall_get_call
ParameterTypeRequiredDescription
No parameters.
transfer Write

Transfer a call to a user, team, or external phone number.

Lua path
app.integrations.aircall.transfer
Full name
aircall.aircall_transfer_call
ParameterTypeRequiredDescription
No parameters.
comment Write

Add a comment to a call.

Lua path
app.integrations.aircall.comment
Full name
aircall.aircall_comment_call
ParameterTypeRequiredDescription
No parameters.
tag Write

Apply tags to a call.

Lua path
app.integrations.aircall.tag
Full name
aircall.aircall_tag_call
ParameterTypeRequiredDescription
No parameters.
archive Write

Archive a call.

Lua path
app.integrations.aircall.archive
Full name
aircall.aircall_archive_call
ParameterTypeRequiredDescription
No parameters.
unarchive Write

Unarchive a call.

Lua path
app.integrations.aircall.unarchive
Full name
aircall.aircall_unarchive_call
ParameterTypeRequiredDescription
No parameters.
pause_recording Write

Pause live recording on a call.

Lua path
app.integrations.aircall.pause_recording
Full name
aircall.aircall_pause_call_recording
ParameterTypeRequiredDescription
No parameters.
resume_recording Write

Resume live recording on a call.

Lua path
app.integrations.aircall.resume_recording
Full name
aircall.aircall_resume_call_recording
ParameterTypeRequiredDescription
No parameters.
delete_recording Write

Delete a call recording.

Lua path
app.integrations.aircall.delete_recording
Full name
aircall.aircall_delete_call_recording
ParameterTypeRequiredDescription
No parameters.
delete_voicemail Write

Delete a call voicemail.

Lua path
app.integrations.aircall.delete_voicemail
Full name
aircall.aircall_delete_call_voicemail
ParameterTypeRequiredDescription
No parameters.
create_insight_card Write

Create an insight card on a call.

Lua path
app.integrations.aircall.create_insight_card
Full name
aircall.aircall_create_insight_card
ParameterTypeRequiredDescription
No parameters.
get_transcription Read

Retrieve a call transcription.

Lua path
app.integrations.aircall.get_transcription
Full name
aircall.aircall_get_call_transcription
ParameterTypeRequiredDescription
No parameters.
get_realtime_transcription Read

Retrieve a realtime call transcription.

Lua path
app.integrations.aircall.get_realtime_transcription
Full name
aircall.aircall_get_call_realtime_transcription
ParameterTypeRequiredDescription
No parameters.
get_sentiments Read

Retrieve call sentiments.

Lua path
app.integrations.aircall.get_sentiments
Full name
aircall.aircall_get_call_sentiments
ParameterTypeRequiredDescription
No parameters.
get_topics Read

Retrieve call topics.

Lua path
app.integrations.aircall.get_topics
Full name
aircall.aircall_get_call_topics
ParameterTypeRequiredDescription
No parameters.
get_summary Read

Retrieve a call summary.

Lua path
app.integrations.aircall.get_summary
Full name
aircall.aircall_get_call_summary
ParameterTypeRequiredDescription
No parameters.
get_custom_summary_result Read

Retrieve a custom call summary result.

Lua path
app.integrations.aircall.get_custom_summary_result
Full name
aircall.aircall_get_call_custom_summary_result
ParameterTypeRequiredDescription
No parameters.
get_action_items Read

Retrieve call action items.

Lua path
app.integrations.aircall.get_action_items
Full name
aircall.aircall_get_call_action_items
ParameterTypeRequiredDescription
No parameters.
get_playbook_result Read

Retrieve call playbook result.

Lua path
app.integrations.aircall.get_playbook_result
Full name
aircall.aircall_get_call_playbook_result
ParameterTypeRequiredDescription
No parameters.
get_evaluations Read

Retrieve call evaluations.

Lua path
app.integrations.aircall.get_evaluations
Full name
aircall.aircall_get_call_evaluations
ParameterTypeRequiredDescription
No parameters.
get_dialer_campaign Read

Retrieve a user dialer campaign.

Lua path
app.integrations.aircall.get_dialer_campaign
Full name
aircall.aircall_get_dialer_campaign
ParameterTypeRequiredDescription
No parameters.
create_dialer_campaign Write

Create a user dialer campaign.

Lua path
app.integrations.aircall.create_dialer_campaign
Full name
aircall.aircall_create_dialer_campaign
ParameterTypeRequiredDescription
No parameters.
delete_dialer_campaign Write

Delete a user dialer campaign.

Lua path
app.integrations.aircall.delete_dialer_campaign
Full name
aircall.aircall_delete_dialer_campaign
ParameterTypeRequiredDescription
No parameters.
list_dialer_campaign_phone_numbers Read

List dialer campaign phone numbers.

Lua path
app.integrations.aircall.list_dialer_campaign_phone_numbers
Full name
aircall.aircall_list_dialer_campaign_phone_numbers
ParameterTypeRequiredDescription
No parameters.
add_dialer_campaign_phone_numbers Write

Add phone numbers to a dialer campaign.

Lua path
app.integrations.aircall.add_dialer_campaign_phone_numbers
Full name
aircall.aircall_add_dialer_campaign_phone_numbers
ParameterTypeRequiredDescription
No parameters.
delete_dialer_campaign_phone_number Write

Delete a phone number from a dialer campaign.

Lua path
app.integrations.aircall.delete_dialer_campaign_phone_number
Full name
aircall.aircall_delete_dialer_campaign_phone_number
ParameterTypeRequiredDescription
No parameters.
list_numbers Read

List Aircall numbers.

Lua path
app.integrations.aircall.list_numbers
Full name
aircall.aircall_list_numbers
ParameterTypeRequiredDescription
No parameters.
get_number Read

Retrieve an Aircall number.

Lua path
app.integrations.aircall.get_number
Full name
aircall.aircall_get_number
ParameterTypeRequiredDescription
No parameters.
update_number Write

Update an Aircall number.

Lua path
app.integrations.aircall.update_number
Full name
aircall.aircall_update_number
ParameterTypeRequiredDescription
No parameters.
update_number_music_and_messages Write

Update number music and messages.

Lua path
app.integrations.aircall.update_number_music_and_messages
Full name
aircall.aircall_update_number_music_and_messages
ParameterTypeRequiredDescription
No parameters.
create_number_configuration Write

Create number configuration for public API messaging.

Lua path
app.integrations.aircall.create_number_configuration
Full name
aircall.aircall_create_number_configuration
ParameterTypeRequiredDescription
No parameters.
delete_number_configuration Write

Delete number configuration for public API messaging.

Lua path
app.integrations.aircall.delete_number_configuration
Full name
aircall.aircall_delete_number_configuration
ParameterTypeRequiredDescription
No parameters.
list_contacts Read

List contacts.

Lua path
app.integrations.aircall.list_contacts
Full name
aircall.aircall_list_contacts
ParameterTypeRequiredDescription
No parameters.
get_contact Read

Retrieve a contact.

Lua path
app.integrations.aircall.get_contact
Full name
aircall.aircall_get_contact
ParameterTypeRequiredDescription
No parameters.
create_contact Write

Create a contact.

Lua path
app.integrations.aircall.create_contact
Full name
aircall.aircall_create_contact
ParameterTypeRequiredDescription
No parameters.
update_contact Write

Update a contact.

Lua path
app.integrations.aircall.update_contact
Full name
aircall.aircall_update_contact
ParameterTypeRequiredDescription
No parameters.
delete_contact Write

Delete a contact.

Lua path
app.integrations.aircall.delete_contact
Full name
aircall.aircall_delete_contact
ParameterTypeRequiredDescription
No parameters.
update_contact_phone_number Write

Update a phone number from a contact.

Lua path
app.integrations.aircall.update_contact_phone_number
Full name
aircall.aircall_update_contact_phone_number
ParameterTypeRequiredDescription
No parameters.
delete_contact_phone_number Write

Delete a phone number from a contact.

Lua path
app.integrations.aircall.delete_contact_phone_number
Full name
aircall.aircall_delete_contact_phone_number
ParameterTypeRequiredDescription
No parameters.
update_contact_email Write

Update an email from a contact.

Lua path
app.integrations.aircall.update_contact_email
Full name
aircall.aircall_update_contact_email
ParameterTypeRequiredDescription
No parameters.
delete_contact_email Write

Delete an email from a contact.

Lua path
app.integrations.aircall.delete_contact_email
Full name
aircall.aircall_delete_contact_email
ParameterTypeRequiredDescription
No parameters.
list_tags Read

List tags.

Lua path
app.integrations.aircall.list_tags
Full name
aircall.aircall_list_tags
ParameterTypeRequiredDescription
No parameters.
get_tag Read

Retrieve a tag.

Lua path
app.integrations.aircall.get_tag
Full name
aircall.aircall_get_tag
ParameterTypeRequiredDescription
No parameters.
create_tag Write

Create a tag.

Lua path
app.integrations.aircall.create_tag
Full name
aircall.aircall_create_tag
ParameterTypeRequiredDescription
No parameters.
update_tag Write

Update a tag.

Lua path
app.integrations.aircall.update_tag
Full name
aircall.aircall_update_tag
ParameterTypeRequiredDescription
No parameters.
delete_tag Write

Delete a tag.

Lua path
app.integrations.aircall.delete_tag
Full name
aircall.aircall_delete_tag
ParameterTypeRequiredDescription
No parameters.
list_webhooks Read

List webhooks.

Lua path
app.integrations.aircall.list_webhooks
Full name
aircall.aircall_list_webhooks
ParameterTypeRequiredDescription
No parameters.
get_webhook Read

Retrieve a webhook.

Lua path
app.integrations.aircall.get_webhook
Full name
aircall.aircall_get_webhook
ParameterTypeRequiredDescription
No parameters.
create_webhook Write

Create a webhook.

Lua path
app.integrations.aircall.create_webhook
Full name
aircall.aircall_create_webhook
ParameterTypeRequiredDescription
No parameters.
update_webhook Write

Update a webhook.

Lua path
app.integrations.aircall.update_webhook
Full name
aircall.aircall_update_webhook
ParameterTypeRequiredDescription
No parameters.
delete_webhook Write

Delete a webhook.

Lua path
app.integrations.aircall.delete_webhook
Full name
aircall.aircall_delete_webhook
ParameterTypeRequiredDescription
No parameters.
get_company Read

Retrieve company information.

Lua path
app.integrations.aircall.get_company
Full name
aircall.aircall_get_company
ParameterTypeRequiredDescription
No parameters.
get_integration Read

Retrieve integration information.

Lua path
app.integrations.aircall.get_integration
Full name
aircall.aircall_get_integration
ParameterTypeRequiredDescription
No parameters.
api_get Read

Call a safe relative Aircall API path with GET.

Lua path
app.integrations.aircall.api_get
Full name
aircall.aircall_api_get
ParameterTypeRequiredDescription
No parameters.
api_post Write

Call a safe relative Aircall API path with POST.

Lua path
app.integrations.aircall.api_post
Full name
aircall.aircall_api_post
ParameterTypeRequiredDescription
No parameters.
api_put Write

Call a safe relative Aircall API path with PUT.

Lua path
app.integrations.aircall.api_put
Full name
aircall.aircall_api_put
ParameterTypeRequiredDescription
No parameters.
api_delete Write

Call a safe relative Aircall API path with DELETE.

Lua path
app.integrations.aircall.api_delete
Full name
aircall.aircall_api_delete
ParameterTypeRequiredDescription
No parameters.