Calls

Place Calls

Place a single outbound call from the Katexs dashboard or fire one programmatically from your backend. Both paths use the same call engine and return the same call log.

Place a call from the dashboard

The fastest way to test a live agent. Open Creator, select an agent that is set to Active, and click Call a number in the Deploy tab. Enter the destination, choose a caller ID from your workspace, and dial.

1
Open the agent
Go to Creator and open the agent you want to call from. It must be Active and have a phone number assigned.
2
Click Call a number
In the Deploy tab, click the call button and enter the destination in E.164 format, such as +15555550142.
3
Choose the caller ID
Pick one of your provisioned or imported numbers. This is what the recipient sees.
4
Dial and watch
The call connects and the transcript streams in real time. You can transfer, whisper, or hang up from the same panel.

Dashboard calls are billed the same as API calls. They are useful for one-off tests, demos, and manual follow-ups.

Place a call from the API

Send a POST request to /v1/calls with your API key in the Authorization header. The call is queued immediately and the response contains a call ID you can use to poll or correlate with webhooks.

bash

curl -X POST https://api.katexs.com/v1/calls \
  -H "Authorization: Bearer $KATEXS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_123",
    "from": "+15555550100",
    "to": "+15555550142",
    "variables": {
      "first_name": "Maria",
      "company_name": "Katexs Dental"
    },
    "metadata": {
      "campaign_id": "cmp_44",
      "lead_id": "lead_8891"
    }
  }'

json

{
  "id": "cl_992",
  "status": "queued",
  "agent_id": "agt_123",
  "from": "+15555550100",
  "to": "+15555550142",
  "created_at": "2026-08-02T15:04:05Z"
}

Required fields

Field	Type	Description
agent_id	string	The active agent that will run the conversation.
from	string	A phone number in your workspace used as the caller ID.
to	string	The destination number in E.164 format.

Optional fields

Field	Type	Description
variables	object	Key-value pairs injected into {{placeholders}} in the prompt and greeting.
metadata	object	Opaque JSON echoed on every webhook and stored on the call log.
schedule_at	ISO 8601	Queues the call to start at a future time instead of immediately.
max_duration_sec	integer	Hard cap on call length. The agent wraps up and hangs up at the limit.
record	boolean	Whether to record the call. Defaults to true.

Variables and personalization

Pass any data your prompt references as variables. If the prompt says Hello {{first_name}}, include first_name in the variables object. Missing variables render as empty strings, so write prompts that degrade gracefully.

json

"variables": {
  "first_name": "Maria",
  "company_name": "Katexs Dental",
  "appointment_type": "cleaning"
}

Rate limits and concurrency

Each workspace has default limits to protect the telephony layer and your budget. Calls that exceed the limits return HTTP 429 with a Retry-After header.

Limit	Default	Notes
Create-call requests	60 per minute	Bursts above this are throttled.
Simultaneous outbound calls	10 per workspace	Additional calls are queued until a line frees up.
Max duration	1 hour	Configurable per call with max_duration_sec.

Retry 429 and 5xx errors with exponential backoff. Never retry a 4xx validation error without fixing the request body first.

In-call controls Webhook events