SDKs

The SDKs aren’t published yet. The install commands below will work once @kallabot/sdk is on npm and kallabot is on PyPI. Until then, call the API directly; every example in these docs also has a curl tab.

TypeScript / JavaScript

npm i @kallabot/sdkNode 18+, Deno, Bun, Cloudflare Workers, Vercel Edge, and browsers (for voice calls). No runtime dependencies.

Python

pip install kallabotPython 3.9+. Sync Kallabot and async AsyncKallabot clients with the same methods.

Both are generated from the same OpenAPI spec as the API reference, so every operation, field and scope is there, with editor completion.

Quickstart

import Kallabot from "@kallabot/sdk";

const kallabot = new Kallabot(); // reads KALLABOT_API_KEY
const call = await kallabot.calls.create({
  agent_id: "8f0e4c1a-3b7d-4e2f-9a61-2c5d8b7e1f30",
  to: "+971501234567",
  variables: { first_name: "Sara" },
});
console.log(call.id, call.lifecycle); // "call_5f0a…", "queued"

from kallabot import Kallabot

client = Kallabot()  # reads KALLABOT_API_KEY
call = client.calls.create(
    agent_id="8f0e4c1a-3b7d-4e2f-9a61-2c5d8b7e1f30",
    to="+971501234567",
    variables={"first_name": "Sara"},
)
print(call.id, call.lifecycle)  # call_5f0a…  queued

Methods are named after their resource: calls.create(), agents.list(), agents.publish(), agents.versions.list(), knowledge.sources.create(), webhooks.create(), webCalls.create() (web_calls.create() in Python). TypeScript reads with get(), Python with retrieve(). Both kinds of API key work the same way.

What the SDKs do for you

Automatic idempotency keys

Every create and action gets a fresh Idempotency-Key, reused on every retry, so a retried calls.create can never ring someone twice. Pass your own to dedupe across your own retries:

await kallabot.calls.create({ agent_id, to }, { idempotencyKey: `reminder-${appointment.id}` });

client.calls.create(agent_id=agent_id, to=to, idempotency_key=f"reminder-{appointment.id}")

Retries with backoff

Network errors, timeouts, 408, retryable 5xx (only where a repeat can’t run twice), 429 and 409 idempotency_in_progress are retried with exponential backoff and jitter. A 429 waits exactly Retry-After. Set maxRetries / max_retries (default 2). Errors that need a change to the request are never retried.

Typed errors

Every API error is an exception carrying the stable code, status, detail, field problems and requestId / request_id.

import { PaymentRequiredError, ValidationError, KallabotError } from "@kallabot/sdk";
try {
  await kallabot.calls.create({ agent_id, to });
} catch (err) {
  if (err instanceof PaymentRequiredError) notifyOwner("Out of minutes");
  else if (err instanceof ValidationError) err.fieldProblems.forEach((p) => show(p.path, p.message));
  else if (err instanceof KallabotError) console.error(err.code, err.requestId);
  else throw err;
}

import kallabot
try:
    client.calls.create(agent_id=agent_id, to=to)
except kallabot.APIStatusError as err:
    if err.code == "insufficient_credit":
        notify_owner("Out of minutes")
    else:
        raise

Auto-pagination

Iterate a list and the SDK fetches further pages as you go:

for await (const agent of kallabot.agents.list({ status: "active" })) console.log(agent.name);

for call in client.calls.list(direction="outbound"):
    print(call.id, call.outcome)

Revisions

Pass the revision you read so a stale write is refused: { ifMatch: agent.revision } in TypeScript, if_match=agent.revision in Python.

Webhook verification

verify checks the Standard Webhooks signature and timestamp and returns a typed event.

import { Webhooks } from "@kallabot/sdk";
const event = await Webhooks.verify(rawBody, request.headers, process.env.KALLABOT_WEBHOOK_SECRET!);

event = kallabot.webhooks.verify(raw_body, headers, secret="whsec_…")

See Webhooks.

Request IDs and rate limits

Every result knows its response: agent.lastResponse.requestId and .rateLimit in TypeScript; agent.request_id and agent.rate_limit in Python.

File uploads

knowledge.sources.create sends files as multipart: toFile(buffer, "menu.pdf") in TypeScript, a Path, an open file or bytes in Python. See Knowledge.

Browser voice calls

@kallabot/sdk/web connects a web page to an agent over WebRTC. It never sees an API key: your server creates the session and hands the browser a single-use grant.

import { KallabotWebCall } from "@kallabot/sdk/web";

const { id, grant, ice_servers } = await fetch("/api/voice", { method: "POST" }).then((r) => r.json());
const call = await KallabotWebCall.start({ callId: id, grant, iceServers: ice_servers });
call.on("transcript", (line) => render(line));
await call.hangUp();

See Web calls for the server side.

The main client refuses to start in a web page, whichever key you pass, because anyone could read the key there. In the browser, use only @kallabot/sdk/web.

Pin the API version

Set Kallabot-Version once as a default header, so a future API version never changes behaviour under you:

const kallabot = new Kallabot({ defaultHeaders: { "Kallabot-Version": "2026-11-07" } });

client = Kallabot(default_headers={"Kallabot-Version": "2026-11-07"})

Each request also identifies the SDK release (X-Kallabot-SDK). If a release is ever retired, the API answers 426 sdk_version_unsupported and the SDK tells you how to upgrade. See Versioning.

Get started

Essentials

Build

Webhooks

Policies

TypeScript / JavaScript

Python

Quickstart

What the SDKs do for you

Browser voice calls

Pin the API version

TypeScript / JavaScript

Python

​Quickstart

​What the SDKs do for you

​Browser voice calls

​Pin the API version

Quickstart

What the SDKs do for you

Browser voice calls

Pin the API version