Calling calling
The built-in dialer's setup: calling settings, US and Canadian numbers bought for credits, what a call costs and the monthly calling spend limit. Calls themselves are placed in the Kenso app. Also outside dialers (Aircall, Ringover, a signed dialer webhook) and their members (dialer-*).
Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through calling_read and changes through calling_write. Each takes operation plus that operation's parameters, and your workspace role decides which operations you see.
Each operation with a route calls the Kenso API at https://api.ken.so with Authorization: Bearer <Kenso API key>, Ken-Version: 1.1 and X-Ken-Workspace-Id: <workspace id>. You can call that route directly with the same headers.
Operations: dialer-connections-aircall-authorize-url, dialer-connections-aircall-connect, dialer-webhook-connect, dialer-connections-delete, dialer-connections-get, dialer-connections-members-list, dialer-connections-members-update, numbers-available, numbers-buy, numbers-list, numbers-release, numbers-update, rates-get, dialer-connections-ringover-connect, settings-get, settings-update, spend-limit-get, spend-limit-update, voicemails-delete, voicemails-list
dialer-connections-aircall-authorize-url
Write. Early access: needs calls on for the workspace. POST https://api.ken.so/v1/integrations/aircall/connection/authorize-url
Get Aircall's consent URL to connect the workspace through Kenso's Aircall app.
POST /api/v1/integrations/aircall/connection/authorize-url. Staff, or a workspace with the calls flag (workspace admin). Sends Ken-Version 1.1. Returns url, valid for 10 minutes. A person opens it while signed in to Kenso: an Aircall admin approves, and Settings > Calling in the Kenso app finishes the connect in that person's session (an agent cannot finish it). invalid_state with detail not_configured while Kenso's Aircall app is not set up (use dialer-connections-aircall-connect with an API ID and token instead); conflict when Aircall is already connected.
dialer-connections-aircall-connect
Write. Early access: needs calls on for the workspace. POST https://api.ken.so/v1/integrations/aircall/connection
Body (json): apiId string, apiToken string
Connect the workspace's Aircall account with its API ID and API token.
POST /api/v1/integrations/aircall/connection. Staff, or a workspace with the calls flag (workspace admin). Sends Ken-Version 1.1. api_id and api_token come from Aircall (Integrations > API Keys). Kenso checks them with Aircall, adds its webhook to the Aircall account so every call comes back to Kenso, then stores both encrypted; they are never returned. Returns 201 with the connection as dialer-connections-get returns it (connectedAs is the Aircall company). Aircall refusing the credentials is validation_failed on apiToken; Aircall already connected, or Aircall refusing Kenso's webhook (an account holds 100 at most), is conflict; Aircall not answering is unavailable. Nothing is stored on any of them. Then link the Aircall users to members with dialer-connections-members-list and dialer-connections-members-update.
dialer-webhook-connect
Write. Early access: needs calls on for the workspace. POST https://api.ken.so/v1/integrations/dialer-webhook/connection
Create the workspace's dialer webhook: a URL and signing secret any dialer posts calls to.
POST /api/v1/integrations/dialer-webhook/connection. Staff, or a workspace with the calls flag (workspace admin). Sends Ken-Version 1.1. Returns 201 with connection, url, hookKey and secret. hookKey and secret are shown only in this response: Kenso keeps a hash and an encrypted copy. The dialer posts each call to url with X-Ken-Signature: t=<unix seconds>,v1=<hex>, the hex being HMAC-SHA256(secret, t + "." + body); the body and the answers are in the Kenso API docs (dialer-webhook.md). A workspace with a dialer webhook already connected is conflict: disconnect it with dialer-connections-delete first.
dialer-connections-delete
Write. Early access: needs calls on for the workspace. DELETE https://api.ken.so/v1/integrations/{integrationKey}/connection
Path: integrationKey
Disconnect a dialer. Its calls stop reaching Kenso; calls already logged stay.
DELETE /api/v1/integrations/{integrationKey}/connection. Staff, or a workspace with the calls flag
(workspace admin). Sends Ken-Version 1.1. integration_key: aircall, ringover, dialpad, justcall,
cloudtalk or dialer-webhook. Kenso asks the dialer to stop sending, then clears the tokens or the webhook secret. Returns 204.
Not connected is not found. A dialer webhook that is reconnected gets a new URL and secret.
dialer-connections-get
Read. Early access: needs calls on for the workspace. GET https://api.ken.so/v1/integrations/{integrationKey}/connection
Path: integrationKey
Return the workspace's connection to a dialer.
GET /api/v1/integrations/{integrationKey}/connection. Staff, or a workspace with the calls flag
(workspace admin). Sends Ken-Version 1.1. integration_key: aircall, ringover, dialpad, justcall,
cloudtalk or dialer-webhook. Returns provider, status (connected or needs_reconnect), connectedAs, connectedAt and lastEventAt
(omitted until the dialer sent an event). Tokens and secrets are never returned. Not connected is not found.
dialer-connections-members-list
Read. Early access: needs calls on for the workspace. GET https://api.ken.so/v1/integrations/{integrationKey}/connection/members
Path: integrationKey
List the dialer's users and the Kenso member each one is.
GET /api/v1/integrations/{integrationKey}/connection/members. Staff, or a workspace with the calls
flag (workspace admin). Sends Ken-Version 1.1. integration_key: aircall, ringover, dialpad, justcall or
cloudtalk (a dialer webhook has no user directory: provider_not_available). Up to 500 users: externalUserId, email, name, numbers
(E.164), memberId and match (linked: saved; email: the member with the user's email, saved by
dialer-connections-members-update). Unavailable while the dialer cannot be reached.
dialer-connections-members-update
Write. Early access: needs calls on for the workspace. PUT https://api.ken.so/v1/integrations/{integrationKey}/connection/members
Path: integrationKey
Body (json): members array
Replace which Kenso member each dialer user is.
PUT /api/v1/integrations/{integrationKey}/connection/members. Staff, or a workspace with the calls
flag (workspace admin). Sends Ken-Version 1.1. integration_key: aircall, ringover, dialpad, justcall or cloudtalk. members: every
link to keep, [{"member_id": 31, "external_user_id": "1234"}], up to 500; a member or a user once
each. A member left out is unlinked; an empty list unlinks everyone. external_user_id comes from
dialer-connections-members-list. Returns the members list as that operation does.
numbers-available
Read. Early access: needs calling on for the workspace. GET https://api.ken.so/v1/calling/numbers/available
Query: areaCode string, country string, locality string
Search up to 10 local phone numbers for sale in the US or Canada, by area code or city. Requires the workspace_settings permission.
GET /api/v1/calling/numbers/available. Staff, or a workspace with the calling flag. Sends Ken-Version 1.1.
country: US or CA (and one the workspace calls). area_code: three digits. locality: a city.
Returns data [{e164, countryIso2, locality, region, monthlyCredits}]. 503 provider_unavailable
when the carrier is not set up or not reachable.
numbers-buy
Write. Early access: needs calling on for the workspace. POST https://api.ken.so/v1/calling/numbers
Body (json): areaCode string, assignedMemberId integer, cnam string, country string, e164 string, locality string
Buy a local phone number for 100 credits a month. Only when the user asks to buy one. Requires the workspace_settings and billing permissions.
POST /api/v1/calling/numbers. Staff, or a workspace with the calling flag. Sends Ken-Version 1.1. country: US or CA. e164: a number from calling(operation="numbers-available"); when a fresh search no longer offers it, the first number that search offers is bought instead, so tell the user the number you got. area_code (three digits) and locality narrow that search; a US or Canadian e164 sent without area_code is searched for in its own area code. assigned_member_id: an active member with no number yet. cnam: the caller name shown with its calls, at most 15 letters, digits, spaces and . , & -, US numbers only. Toll-free numbers are not sold. The first month is charged when the number is active. Returns data, the number (201). status ordering: the carrier has not assigned it yet. Errors: 400 validation_failed or invalid_member, 402 insufficient_credits when the workspace cannot pay the first month (error.refusal), 409 number_limit_reached (five numbers: release one first), no_numbers_available (try another area code or city) or member_already_has_number, 503 provider_unavailable (the carrier is not set up or refused the order; nothing was charged).
numbers-list
Read. Early access: needs calling on for the workspace. GET https://api.ken.so/v1/calling/numbers
List the workspace's phone numbers (not released), newest first. At most five.
GET /api/v1/calling/numbers. Staff, or a workspace with the calling flag. Sends Ken-Version 1.1.
Returns data [{numberId, e164, countryIso2, numberType (local), status (ordering, active,
releasing), assignedMemberId, cnam, monthlyCredits, unpaid, orderedAt, activatedAt,
releasedAt}] and pagination {hasMore: false}. unpaid true: its monthly credits could not be
charged, and outbound calls from it are refused until they are.
numbers-release
Write. Early access: needs calling on for the workspace. DELETE https://api.ken.so/v1/calling/numbers/{numberId}
Path: numberId
Release a phone number: its monthly credits stop and the number goes back to the carrier. Only when the user asks; it cannot be bought back. Requires the workspace_settings and billing permissions.
DELETE /api/v1/calling/numbers/{numberId}. Staff, or a workspace with the calling flag. Sends Ken-Version 1.1.
The paid month is not refunded. Returns data, the number with status released (also when the
carrier no longer has it or never assigned it), or 202 with status releasing when the carrier
has not taken it back yet: the number stays releasing and finishes by itself once the number
lifecycle job is on; until then you may call this operation again. 404 for a number of
another workspace, 503 provider_unavailable when the carrier is not set up.
numbers-update
Write. Early access: needs calling on for the workspace. PATCH https://api.ken.so/v1/calling/numbers/{numberId}
Path: numberId
Assign a phone number to a member (or nobody) or set its caller name (CNAM). Requires the workspace_settings permission.
PATCH /api/v1/calling/numbers/{numberId}. Staff, or a workspace with the calling flag. Sends Ken-Version 1.1.
changes keys: assigned_member_id (a member id, or null to unassign) and cnam (at most 15
letters, digits, spaces and . , & -, US numbers only; null clears it). Absent keys stay.
Returns data, the number. Errors: 400 invalid_member (not an active member), 409
member_already_has_number, 409 invalid_state (being ordered or released), 503
provider_unavailable (the carrier did not take the caller name; nothing was saved), 404 for a
number of another workspace.
rates-get
Read. Early access: needs calling on for the workspace. GET https://api.ken.so/v1/calling/rates
Query: to string
Return what a call to a phone number costs per minute, in millicredits.
GET /api/v1/calling/rates?to=. Staff, or a workspace with the calling flag. Sends Ken-Version 1.1.
to: the number, E.164 like +14155550100. Returns data {to, countryIso2, lineType, priced,
millicreditsPerMinute (the destination plus the rep's leg), recordingMillicreditsPerMinute
(added when recorded)}. priced false: Kenso has no price for that destination yet and it cannot
be called; both rates are null. 400 invalid_phone when to is not a phone number.
dialer-connections-ringover-connect
Write. Early access: needs calls on for the workspace. POST https://api.ken.so/v1/integrations/ringover/connection
Body (json): apiKey string, webhookKey string
Connect the workspace's Ringover account with its API key, so its calls land in Kenso.
POST /api/v1/integrations/ringover/connection. Staff, or a workspace with the calls flag
(workspace admin). Sends Ken-Version 1.1. api_key: a Ringover API key (Ringover dashboard,
Developer, API keys) with the users, calls, callback and webhooks rights. Kenso checks it against
Ringover, stores it encrypted, links each Ringover user to the Kenso member with the same email and
registers Kenso's webhook on the account. Returns 201 with connection and webhook {registered, url,
events, signingKeyStored}. When Ringover refused the webhook (registered false) and signingKeyStored
is false, Kenso refuses every call until it has the key: copy the webhook key from Ringover's webhook
configuration page, run dialer-connections-delete, connect again with webhook_key, then paste the url
of that second answer into Ringover's webhook settings for those events (each connect makes a new
url). A key Ringover refuses is a validation error and nothing is stored; a workspace with Ringover
already connected is conflict.
settings-get
Read. Early access: needs calling on for the workspace. GET https://api.ken.so/v1/calling/settings
Return the workspace's calling settings: recording, consent notice, voicemail drops and calling countries.
GET /api/v1/calling/settings. Staff, or a workspace with the calling flag. Sends Ken-Version 1.1.
Returns data {recordingEnabled, consentNotice (auto, always, never), voicemailDropMode (off,
manual, auto), voicemailToMobile, voicemailToMobileAcceptedByMemberId,
voicemailToMobileAcceptedAt, allowedCountries (US, CA), dncScrub, updatedAt (null while the
workspace runs on the defaults)}.
settings-update
Write. Early access: needs calling on for the workspace. PATCH https://api.ken.so/v1/calling/settings
Update the workspace's calling settings. Absent fields stay unchanged. Change them only when the user asks. Requires the workspace_settings permission.
PATCH /api/v1/calling/settings. Staff, or a workspace with the calling flag. Sends Ken-Version 1.1. changes keys (snake_case or wire camelCase): recording_enabled (bool), consent_notice (auto, always, never), voicemail_drop_mode (off, manual, auto), voicemail_to_mobile (bool), accept_tcpa_notice (bool), allowed_countries (non-empty list of US, CA), dnc_scrub (bool). Null is not allowed. voicemail_to_mobile true needs accept_tcpa_notice true in the same call: only send it after the user accepted the TCPA notice for voicemail drops to mobiles. Kenso records who accepted and when. Returns the settings.
spend-limit-get
Read. Early access: needs calling on for the workspace. GET https://api.ken.so/v1/calling/spend-limit
Return the workspace's monthly calling spend limit and what calling spent this month.
GET /api/v1/calling/spend-limit. Staff, or a workspace with the calling flag. Sends Ken-Version 1.1.
Returns data {monthlyLimitMillicredits (null is no limit; 1 credit = 1,000 millicredits),
isDefault (true at the 2,000-credit default), spentThisMonthMillicredits (call minutes and
recordings this UTC month, plus open call holds: what the cap counts; number fees are not in
it)}. Separate from the workflow spend limits.
spend-limit-update
Write. Early access: needs calling on for the workspace. PATCH https://api.ken.so/v1/calling/spend-limit
Set the workspace's monthly calling spend limit, in millicredits (null is no limit). Only when the user asks. Requires the workspace_settings and billing permissions.
PATCH /api/v1/calling/spend-limit. Staff, or a workspace with the calling flag. Sends Ken-Version 1.1. monthly_limit_millicredits: null for no limit, else 1 to 100,000,000 (2,000,000 = 2,000 credits). Returns the same shape as calling(operation="spend-limit-get").
voicemails-delete
Write. Early access: needs calling on for the workspace. DELETE https://api.ken.so/v1/calling/voicemails/{voicemailId}
Path: voicemailId
Delete one of the caller's voicemail greetings and its audio. Only when the user asks; it cannot be undone. Requires edit on the Accounts page.
DELETE /api/v1/calling/voicemails/{voicemailId}. Staff, or a workspace with the calling flag.
Sends Ken-Version 1.1. voicemail_id: from calling(operation="voicemails-list"). Returns 204 with
no body. A drop on a live call that has not played the greeting yet fails. 404 for a greeting
of another member or workspace, or one already deleted; 403 for a credential with no member.
voicemails-list
Read. Early access: needs calling on for the workspace. GET https://api.ken.so/v1/calling/voicemails
List the caller's own voicemail greetings, the recordings a call can drop on a voicemail.
GET /api/v1/calling/voicemails. Staff, or a workspace with the calling flag. Sends Ken-Version 1.1.
Greetings belong to the member signed in (Dialer 08): a credential with no member, like a
workspace API key, gets 403. Returns data, at most five, oldest first (the first is the one an
auto drop plays): {voicemailId, name, durationSeconds, format (wav or mp3), audioUrl (a link to
listen, valid 5 minutes, absent while Kenso's audio store is not set up), createdAt}. Uploading
a greeting and dropping one on a call happen only in the Kenso app.