Calls

Outbound Calls

Place a single call from the dashboard, fire one from your backend when a lead comes in, or hand a whole list to a Campaign. All three paths use the same call engine.

From the dashboard

1
Open the agent
Go to Creator → your agent → Deploy. The agent must be Live and have a caller ID assigned under Settings → Phone Numbers.
2
Click Call a number
Enter the destination in E.164 format (+15555550142) and pick which of your numbers to call from.
3
Watch it live
The transcript streams into the panel as the agent talks. You can barge in, transfer, or hang up from the same view.

From the API

POST to /v1/calls with an agent, a caller ID, and a destination. The call is queued immediately and the response returns a call ID you can poll or receive webhooks for.

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",
    "metadata": { "crm_id": "lead_8891", "source": "webform" },
    "variables": {
      "first_name": "Maria",
      "service": "dental cleaning"
    }
  }'

json

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

Request fields

Field	Required	Description
agent_id	Yes	The agent that will run the conversation.
from	Yes	A number in your workspace, used as caller ID.
to	Yes	Destination in E.164 format.
variables	No	Key/value pairs injected into {{placeholders}} in the prompt and greeting.
metadata	No	Opaque JSON echoed back on every webhook and stored on the call log.
schedule_at	No	ISO timestamp. Queues the call instead of dialing now.
max_duration_sec	No	Hard cap. The agent wraps up and hangs up at the limit.

Variables and personalization

Anything you pass in variables is available in the prompt as {{first_name}}, {{service}}, and so on. Unset variables render as empty strings, so write prompts that read cleanly either way.

Lifecycle

queued — Accepted and waiting for a free line or its scheduled time.
ringing — The carrier is dialing the destination.
in-progress — Answered. Transcript events start streaming to your server URL.
ended — Terminal. The call log now carries an end reason, recording, and cost.

For more than a handful of numbers, use Campaigns instead of looping over the API — it handles pacing, retries, time-zone windows, and Do-Not-Call suppression for you.

Rate limits and retries

The default concurrency is 10 simultaneous outbound calls per workspace and 60 create-call requests per minute. Exceeding either returns 429 with a Retry-After header. Retry on 429 and 5xx with exponential backoff; never retry a 4xx validation error.

Set up a campaign Webhook events