Skip to main content
POST
Schedule a call

Authorizations

Authorization
string
header
required

An API key from Settings → API keys, sent as Authorization: Bearer kb_live_…. A workspace key starts kb_; a personal key starts kbp_ and acts as its owner.

Headers

Idempotency-Key
string
required

A unique key (a UUID works) for this request. Retrying with the same key returns the first answer instead of running twice.

Maximum string length: 255
Kallabot-Version
enum<string>

The API version to answer as, a date (YYYY-MM-DD). Leave it out for the current version (2026-11-07). An unknown version is refused with 400 unsupported_api_version.

Available options:
2026-11-07
Example:

"2026-11-07"

Body

application/json
agent_id
string
required

The agent that makes the call. It must be published and allowed to dial out.

to
string
required

The number to call, in E.164 (e.g. +971501234567).

Required string length: 8 - 20
run_at
string<date-time>
required

When to dial (ISO 8601 with a time zone). Must be in the future.

from
string | null

The caller ID, in E.164: one of your numbers. Omit to use the agent's caller number.

Required string length: 8 - 20
timezone
string
default:UTC

The callee's IANA time zone (e.g. Asia/Dubai), kept with the booking for showing its time.

Required string length: 1 - 64
reason
string | null

Why the call is booked; the agent is told.

Maximum string length: 280
variables
Variables · object

Values for the agent's {{variables}} (e.g. first_name). At most 50 keys.

Response

Successful Response

id
string
required

The scheduled call's id.

agent_id
string
required

The agent that makes the call.

timezone
string
required

The callee's IANA time zone.

source
enum<string>
required

manual (booked through the API or dashboard), callback (a caller asked) or retry.

Available options:
manual,
callback,
retry
state
enum<string>
required

proposed (a callback waiting for confirmation; never dials on its own), scheduled, dialing, done, canceled or failed.

Available options:
proposed,
scheduled,
dialing,
done,
canceled,
failed
attempts
integer
required

Dial attempts made.

party
string | null

The number to call, masked.

run_at
string | null

When it dials (ISO 8601).

reason
string | null

Why it was booked.

variables
Variables · object

Values for the agent's {{variables}}.

source_call_id
string | null

The call that asked for it, for a callback.

call_id
string | null

The call it placed, once dialled.

phone_number_id
string | null

The number it calls from.

last_error
string | null

Why the last attempt failed.

created_by_user_id
string | null

Who booked it.

created_at
string | null

When it was booked (ISO 8601).

updated_at
string | null

When it last changed (ISO 8601).

to_e164
string | null

The number to call, unmasked (single reads and writes only).