Copy page

Guides

SDKs

The official server SDKs support single-target Calls and published Goal Runs. Use SDK 1.0.1 with the production API. Legacy call-task integrations must migrate their inputs and result handling before upgrading.

Install

Terminal
pnpm add @call-e/calle@1.0.1
pip install calle-ai==1.0.1

Python requires 3.11 or later. Keep API keys in trusted server environments. Source: TypeScript and Python.

Configuration

Terminal
export CALLE_BASE_URL="https://api.heycall-e.com"
export CALLE_API_KEY="<YOUR_CALLE_API_KEY>"
export CALLE_TEST_PHONE="<AUTHORIZED_E164_PHONE>"
export CALLE_IDEMPOTENCY_KEY="hello-001"

For the test environment, set CALLE_BASE_URL=https://test-api.heycall-e.com and use a test-compatible key. These examples make a real call. Omitted region and locale are inferred from the phone and task; conflicting or ambiguous input returns 422 input_incomplete for correction.

TypeScript

TypeScript
import { CalleClient } from "@call-e/calle";

const client = new CalleClient({
  apiKey: process.env.CALLE_API_KEY!,
  baseUrl: process.env.CALLE_BASE_URL!,
});

const created = await client.calls.create(
  {
    task: "Say hello in English, allow a brief reply, then politely end the call.",
    phone: process.env.CALLE_TEST_PHONE!,
    resultSchema: {
      type: "object",
      additionalProperties: false,
      properties: { summary: { type: "string" } },
      required: ["summary"],
    },
  },
  { idempotencyKey: process.env.CALLE_IDEMPOTENCY_KEY! },
);
console.log("Keep this Call ID:", created.id);

const ready = await client.calls.waitForResult(created.id, {
  intervalMs: 2000,
  timeoutMs: 600000,
});
console.log(ready.result, ready.error);
console.log(ready.transcript);

Python

Python
import os
from calle import CalleClient

client = CalleClient(
    api_key=os.environ["CALLE_API_KEY"],
    base_url=os.environ["CALLE_BASE_URL"],
)
created = client.calls.create(
    task="Say hello in English, allow a brief reply, then politely end the call.",
    phone=os.environ["CALLE_TEST_PHONE"],
    idempotency_key=os.environ["CALLE_IDEMPOTENCY_KEY"],
    result_schema={
        "type": "object",
        "additionalProperties": False,
        "properties": {"summary": {"type": "string"}},
        "required": ["summary"],
    },
)
print("Keep this Call ID:", created["id"])
ready = client.calls.wait_for_result(
    created["id"], interval_seconds=2, timeout_seconds=600
)
print(ready["result"], ready["error"])
print(ready["transcript"])

The client defaults to production. Wait helpers stop when result_status is not pending (resultStatus in TypeScript), including unavailable results with both result and error null. A timeout does not cancel or replace the Call. Python exposes the Billing identifier as call_id; TypeScript uses callId. Use the separate resource id for API requests.

For a runnable Python or Ruby example that saves the request and resumes the same Call, see Run a complete example.

Retry safely

Persist one key and the original request before calling create. Retrying the same logical call uses both unchanged. Do not generate a new key inside a retry loop or copy resolved region/locale from the response into an originally omitted input. A replay returns the original Call even after failure or completion; it does not initiate another phone call. Follow Call retry decisions to distinguish 409 idempotency_conflict with reason creation_in_progress from changed-input conflicts.

Existing integrations

Keep a legacy client for historical call-task IDs. The current SDK's Calls methods use the single-target interface; Goal endpoints and request shapes remain unchanged, but the result readiness rule has changed. SDK 0.7.x Goal wait helpers can time out on unavailable results; upgrade to 1.0 or poll REST using result_status. HTTP/Python use result_schema and error.detail_code; TypeScript uses resultSchema and error.detailCode. See the migration guide.

Community SDKs

Android / Wear OS is community-maintained. Check its documented API compatibility independently of the server SDK releases.