Copy page

Guides

Quickstart

Create a CALL-E call task, wait for the terminal result, and read the structured output.

This quickstart uses the one-shot Calls API. If your application repeats a workflow that has already been authored and published in CALL-E, start with Goal Runs instead.

Outbound calling is not available in every country or region. Check the current supported regions and languages before building an integration. A phone number can be valid E.164 and still be rejected with unsupported_region; see Errors for recovery guidance.

API key · TypeScript · Python

Install

Install the server SDK package for your runtime:

Code
pnpm add @call-e/calle
pip install calle-ai

Set your API key before running the examples:

Code
export CALLE_API_KEY="iams_live_example"

You can view your API keys in the CALL-E dashboard.

See Authentication for API key handling and server-only usage.

Create a client

TypeScript:

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

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

Python:

Code
import os
from calle import CalleClient

client = CalleClient(api_key=os.environ["CALLE_API_KEY"])

Minimum request

The minimum create request is task-only. Include the phone number directly in the task when CALL-E should infer the recipient from the instruction. Replace <E164_PHONE> with a phone number you own or are authorized to call.

Code
{
  "task": "Call <E164_PHONE> and ask whether they can hear clearly."
}

Create and wait

TypeScript:

Code
const call = await client.calls.createAndWait({
  task: "Call <E164_PHONE> and ask whether they can hear clearly.",
  resultSchema: {
    type: "object",
    required: ["can_hear_clearly"],
    properties: {
      can_hear_clearly: { type: "string", enum: ["yes", "no", "unknown"] },
    },
  },
});

Python:

Code
call = client.calls.create_and_wait(
    task="Call <E164_PHONE> and ask whether they can hear clearly.",
    result_schema={
        "type": "object",
        "required": ["can_hear_clearly"],
        "properties": {
            "can_hear_clearly": {"type": "string", "enum": ["yes", "no", "unknown"]},
        },
    },
)

Read the result

The terminal call task includes a stable status, a schema-valid structured result, and task-level outcome fields from the post-call summary. When CALL-E cannot produce a schema-valid result from the evidence, structured_result is null.

See Task completion for how to interpret task_completed (taskCompleted in TypeScript) and completion_confidence.

TypeScript:

Code
console.log(call.status);
console.log(call.structuredResult);
console.log(call.taskCompleted, call.completionConfidence, call.evidence);

Example output:

Code
{
  "status": "completed",
  "taskCompleted": true,
  "completionConfidence": {"score": 0.92, "label": "high"},
  "evidence": ["The recipient clearly answered yes."],
  "structuredResult": {
    "can_hear_clearly": "yes"
  }
}

Python:

Code
print(call["status"])
print(call["structured_result"])
print(call["task_completed"], call["completion_confidence"], call["evidence"])

Example output:

Code
{
  "status": "completed",
  "task_completed": true,
  "completion_confidence": {"score": 0.92, "label": "high"},
  "evidence": ["The recipient clearly answered yes."],
  "structured_result": {
    "can_hear_clearly": "yes"
  }
}