Quick Start

The fastest path — paste this into any AI agent (Claude Code, Codex, Cursor, and more):

Install CALL-E for me: https://open.heycall-e.com/document/mcp-archive/CALL-E-installation-guide.md

Your agent handles the rest.

SDK: Follow the TypeScript or Python quickstart with an explicit recipient.

Contents

• What is CALL-E?
• Capabilities
• Get Started
  • Agent Install
  • MCP
  • SDK
  • API
• Supported Regions and Languages
• Examples
• Troubleshooting
• In Development
• Repository Structure
• Telemetry
• Development
• Community

What is CALL-E?

CALL-E automates goal-driven phone tasks that scripted voice bots cannot handle.

Traditional calling platforms use prebuilt bots optimized for high-volume, repetitive scripts. CALL-E is different: you describe a goal, and CALL-E figures out how to achieve it over the phone. It handles natural conversation, adapts to unexpected responses, and returns a structured result when the call ends.

This makes CALL-E practical for tasks where a rigid script would fail — appointment confirmations, research calls, follow-ups, lead qualification.

Call lifecycle:

flowchart LR
    A["Goal + phone number"] --> B["Plan"]
    B --> C{"Details\ncomplete?"}
    C -- "Missing info" --> D["Clarify"]
    D --> B
    C -- "Confirmed" --> E["Dial"]
    E --> F["Live conversation"]
    F --> G["Structured result\n+ transcript\n+ summary"]

Capabilities

In Development

Goal-Driven Long Tasks — CALL-E plans a multi-step task end-to-end: it designs the calling approach, executes the calls, learns from real outcomes, and continuously improves its strategy over time. This goes beyond single calls — CALL-E learns how to achieve each phone-based goal more reliably across attempts. This feature is under active development and not yet generally available.

Get Started

Choose the integration path that fits your use case:

Agent Install

Paste this single prompt into your agent for automatic setup:

Install CALL-E for me: https://open.heycall-e.com/document/mcp-archive/CALL-E-installation-guide.md

Works in Claude Code, Codex, Cursor, and any agent that can run shell commands. The linked guide stays up to date, so the prompt never changes.

For manual setup, expand the table below or see the full install guide.

MCP

CALL-E exposes a Streamable HTTP MCP endpoint. Any compatible MCP client can connect, authorize via OAuth, and run CALL-E with three tools.

Endpoint:

https://seleven-mcp-sg.airudder.com/mcp/openagent_oauth

Transport: Streamable HTTP

Tool flow:

sequenceDiagram
    participant Client as MCP Client
    participant CE as CALL-E
    participant Phone

    Client->>CE: plan_call(goal, phone)
    CE-->>Client: plan_id, confirm_token, ready_to_run=true
    Note over Client: User confirms intent
    Client->>CE: run_call(plan_id, confirm_token)
    CE-->>Client: run_id
    CE-)Phone: Outbound call
    Note over Client,CE: Follow next_step, default first wait ~60s
    loop Until terminal status, stop instruction, or confirmation request
        Client->>CE: get_call_run(run_id)
        CE-->>Client: status, activity, transcript, next_step
    end

Tools:

Server-directed delays, stop instructions, and retry-confirmation questions take precedence over the default cadence. Ask the user before a requested retry; do not place another call automatically. The ~60-second delay is a polling recommendation, not a completion deadline. Persist the returned run_id and resume get_call_run after a local timeout or restart; do not call run_call again. MCP run_call does not accept a webhook_url, so MCP clients should poll get_call_run for completion.

For OAuth details, tool contracts, setup, and the completion workflow, see the MCP guide.

SDK

CALL-E server SDKs are available for TypeScript and Python. Use them in trusted backend services, workers, and automation systems.

Install: Python requires version 3.11 or later.

# TypeScript
pnpm add @call-e/calle@0.7.0

# Python
pip install calle-ai==0.7.0

Set your API key, recipient, and workflow key:

export CALLE_API_KEY="<YOUR_CALLE_API_KEY>"
export CALLE_EXAMPLE_PHONE="<AUTHORIZED_E164_PHONE>"
export CALLE_IDEMPOTENCY_KEY="<UNIQUE_WORKFLOW_KEY>"

Replace the non-working key placeholder with your key from the CALL-E dashboard. These examples place a real call. Use a number you own or are authorized to call; for integration testing, follow the official test-hotline instructions. Choose and save a unique workflow key before the first request. Reuse it only for the same request; a new key can create another call.

The examples below use the published TypeScript and Python SDKs at 0.7.0. An explicit recipients entry uses these API fields:

Set region and locale for your recipient. name is not an accepted recipient field in the API schema. Python SDK 0.7.0 also accepts the singular shorthand recipient={"phone": "..."}; use phones inside a recipients list, as shown below.

When explicit recipients are omitted, the service attempts to infer them from task. It can return no_recipients if inference finds none. Use explicit recipients when the destination is known; see recipient errors.

TypeScript:

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

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

const call = await client.calls.createAndWait({
  task: "Call the recipient and confirm whether they can attend Friday lunch.",
  recipients: [{ phones: [process.env.CALLE_EXAMPLE_PHONE!], region: "US", locale: "en-US" }],
  resultSchema: {
    type: "object",
    required: ["can_attend"],
    properties: {
      can_attend: { type: "string", enum: ["yes", "no", "unknown"] },
    },
  },
}, { idempotencyKey: process.env.CALLE_IDEMPOTENCY_KEY! });

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

Python:

import os
from calle import CalleClient

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

call = client.calls.create_and_wait(
    task="Call the recipient and confirm whether they can attend Friday lunch.",
    recipients=[{"phones": [os.environ["CALLE_EXAMPLE_PHONE"]], "region": "US", "locale": "en-US"}],
    idempotency_key=os.environ["CALLE_IDEMPOTENCY_KEY"],
    result_schema={
        "type": "object",
        "required": ["can_attend"],
        "properties": {
            "can_attend": {"type": "string", "enum": ["yes", "no", "unknown"]},
        },
    },
)

print(call["status"])
print(call["task_completed"])
print(call["structured_result"])
print(call["evidence"])

Python exceptions:

Import the exported exception classes directly from calle:

from calle import (
    CalleAPIError,
    CalleAuthenticationError,
    CalleConnectionError,
    CalleRateLimitError,
    CalleTimeoutError,
    CalleWebhookSignatureError,
)

Catch authentication/rate-limit subclasses before CalleAPIError when handling them separately. A polling timeout does not cancel an accepted call. For a complete example that saves the Call ID and resumes polling, see the Calls example and recovery guide.

Community SDKs

• Kotlin / Android SDK — Community-maintained Kotlin SDK for integrating CALL-E voice agents into Android and Wear OS apps.

API

The CALL-E Developer API provides direct HTTP access for any trusted backend, worker, or workflow system.

Set credentials: Replace <YOUR_CALLE_API_KEY> with the complete key from the CALL-E dashboard.

export CALLE_API_KEY="<YOUR_CALLE_API_KEY>"
export CALLE_BASE_URL="https://api.heycall-e.com"

Endpoints:

The webhook URL is yours. Pass it as webhook_url when creating a call. See the webhooks guide.

Create a call:

curl "$CALLE_BASE_URL/v1/calls" \
  --request POST \
  --header "Authorization: Bearer $CALLE_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: wf_123_friday_lunch" \
  --data '{
    "task": "Call each recipient and ask whether they can attend Friday lunch.",
    "recipients": [
      { "phones": ["<E164_PHONE>"],
        "region": "US",
        "locale": "en-US"
      }
    ],
    "result_schema": {
      "type": "object",
      "required": ["completed_count"],
      "properties": {
        "completed_count": {
          "type": "integer"
        }
      }
    },
    "recipient_result_schema": {
      "type": "object",
      "required": ["can_attend"],
      "properties": {
        "can_attend": {
          "type": "string",
          "enum": ["yes", "no", "unknown"]
        }
      }
    },
    "metadata": {
      "workflow_run_id": "wf_123"
    },
    "webhook_url": "https://example.com/calle/webhook"
  }'

Read a result:

curl "$CALLE_BASE_URL/v1/calls/call_123" \
  --header "Authorization: Bearer $CALLE_API_KEY"

Terminal call result:

{
  "status": "completed",
  "task_completed": true,
  "completion_confidence": { "score": 0.92, "label": "high" },
  "evidence": ["The recipient said they can attend Friday lunch."],
  "structured_result": { "completed_count": 1 },
  "recipients": [
    {
      "structured_result": { "can_attend": "yes" },
      "attempts": [
        {
          "transcript_turns": [
            { "offset_seconds": 0, "speaker": "bot", "text": "Hi, I am calling about Friday lunch." },
            { "offset_seconds": 4, "speaker": "user", "text": "Yes, I can attend." }
          ]
        }
      ]
    }
  ]
}

For authentication, webhooks, and the full reference, see the API docs.

Supported Regions and Languages

Use these country codes with the SDK and API recipient settings.

Notes

• Local means calls use a local number in the destination country or calling-code region.
• International means calls use an international number. These numbers are intended primarily for development and call testing, and calls through the shared international number pool may cost more.
• Region not listed? Use a SIP integration to call that destination. For risk-control reasons, we enable additional International regions for development and testing only after careful review.

Examples

Runnable demos are in examples/:

These are starting-point demos, not the canonical SDK or API contract.

Troubleshooting

If installation, authentication, or MCP tool verification fails, see the CALL-E troubleshooting guide.

Common issues covered:

• Cursor network errors — if setup works in your terminal but fails in the Cursor agent shell, see the Cursor troubleshooting steps.
• calle auth login failures — fetch failures, login errors, and token cache issues.
• Missing MCP tools — how to confirm that plan_call, run_call, and get_call_run are available after install.

Repository Structure

This is a multi-ecosystem integration monorepo. Each integration has its own package and marketplace entry point.

For layout rules and marketplace naming conventions, see docs/agent-integration-layout.md.

Telemetry

The calle CLI sends best-effort usage telemetry to help diagnose installation, authentication, and tool availability issues.

What is collected: anonymous installation ID, CLI version, integration source (e.g. claude/claude_code_plugin/<version>), command stage, outcome, error type, readable base_url_host and server_host (hostname and any non-default port), and server_url_hash (SHA-256 of the complete configured server URL).

The URL hash does not conceal the separate readable host fields. See the CLI telemetry field details and example.

What is never collected: phone numbers, call goals, OAuth tokens, broker login URLs, transcripts, or contact data.

Opt out with --no-telemetry. First follow CLI entry point selection to prepare the launcher and a JSON request. Add --no-telemetry to its argv:

["auth", "status", "--no-telemetry"]

Broker and MCP requests still create service-side security, audit, and operational logs required to run calls.

Development

Requires Node >=22 and pnpm 10.18.3, Changesets, and GitHub Actions.

pnpm install
pnpm check
pnpm test
pnpm pack:dry-run

pnpm --filter @call-e/core check
pnpm --filter @call-e/core test
pnpm --filter @call-e/cli check
pnpm --filter @call-e/cli test
pnpm --filter @call-e/codex-plugin check
pnpm --filter @call-e/codex-plugin test
pnpm --filter @call-e/claude-plugin check
pnpm --filter @call-e/claude-plugin test
pnpm --filter @call-e/cursor-plugin check
pnpm --filter @call-e/cursor-plugin test
pnpm --filter @call-e/openclaw-cli-skill check
pnpm --filter @call-e/openclaw-cli-skill test
pnpm --filter @call-e/skills-sh-skill check
pnpm --filter @call-e/skills-sh-skill test
pnpm run check:examples

For user-visible package changes, add a changeset. The release workflow publishes changed @call-e/* packages to npm and maintains the @call-e/codex-plugin@latest and @call-e/claude-plugin@latest install aliases.

See CONTRIBUTING.md for pull request guidelines.

Community

• Website: heycall-e.com
• Docs: docs.heycall-e.com
• Discord: discord.gg/6AbXUzUV8w