Outbound Calls - ClutchCall

Place a call to any phone number over one of your SIP trunks with a single control-plane call. You supply the destination, a caller-id, and the trunk to route over. The engine dials the carrier. You get back a Call handle. Its sid addresses everything else: audio, transfer, hangup, telemetry.

Outbound originate is a control-plane operation. It returns as soon as the call is dialing, not when the callee answers. To read the outcome, poll calls.get (below), or consume call-lifecycle events.

Before you start

A configured SIP trunk

Outbound calls route over a trunk that you own. Create one and note its trunkId — see SIP trunking.

A caller-id that you are allowed to present

The from number must be one that the trunk (or your carrier) permits. The numbers that you allocated live in number provisioning.

An initialized Voice client

import { Voice } from "@clutchcall/sdk/voice";

const v = new Voice({
  baseUrl: "https://engine.clutchcall.dev",
  apiKey:  process.env.CLUTCHCALL_CREDENTIALS!,
  orgId:   "org_abc",
});

Place a call

Call calls.originate with the destination, caller-id, and trunk. The returned handle carries the sid. The sid is the only identifier that you need for everything that follows.

TypeScript
Python

const call = await v.calls.originate({
  to:      "+15551234567",   // E.164 destination
  from:    "+15558675309",   // caller-id you're allowed to present
  trunkId: "trunk_main",     // SIP trunk to route over
});

console.log(call.sid, call.status); // e.g. "call_9f2c…" "dialing"

import os
from clutchcall.voice import Voice

v = Voice(
    base_url="https://engine.clutchcall.dev",
    api_key=os.environ["CLUTCHCALL_CREDENTIALS"],
    org_id="org_abc",
)

call = v.calls.originate(
    to="+15551234567",
    from_="+15558675309",
    trunk_id="trunk_main",
)

print(call.sid, call.status)  # e.g. "call_9f2c…" "dialing"

string

required

The E.164 destination number.

string

required

The caller-id, in E.164 form. The trunk must permit it.

string

required

The SIP trunk to route the call over.

string

The AI agent id to attach automatically on answer (see below).

number

The seconds to ring before the engine gives up. The server clamps the value to 5..120; the default is 30.

Attach an AI agent

Pass agent, and the engine wires the audio bridge for you the moment the callee answers. The agent starts talking with no AudioBridge code on your side. This one call is the whole outbound-AI path.

TypeScript
Python

const call = await v.calls.originate({
  to:      "+15551234567",
  from:    "+15558675309",
  trunkId: "trunk_main",
  agent:   "appointment-reminder",   // attaches on answer
});

call = v.calls.originate(
    to="+15551234567",
    from_="+15558675309",
    trunk_id="trunk_main",
    agent="appointment-reminder",   # attaches on answer
)

The agent id names a server-side agent that you configured: its speech-to-speech or ASR/LLM/TTS pipeline, prompt, and tools. Build one in the agent runtime. To attach an agent to a call that is already connected, or to hand a call between a bot and a person, see AI ↔ human handoff.

You can also own the media yourself: feed the caller’s audio to your own recognizer, and push your own synthesized audio back. To do this, omit agent and attach an audio bridge to the sid instead.

Cap the ring time

ringTimeoutSec bounds how long the callee’s phone rings before the engine abandons the call as no_answer. Pass a shorter value for tight retry loops. Pass a longer value for numbers that are slow to pick up. The engine clamps the value to 5..120 seconds. A value below 5 becomes 5. A value above 120 becomes 120. You never have to validate the value yourself.

TypeScript
Python

const call = await v.calls.originate({
  to:      "+15551234567",
  from:    "+15558675309",
  trunkId: "trunk_main",
  ringTimeoutSec: 15,   // give up after 15s instead of the default 30
});

call = v.calls.originate(
    to="+15551234567",
    from_="+15558675309",
    trunk_id="trunk_main",
    ring_timeout_sec=15,   # give up after 15s instead of the default 30
)

ringTimeoutSec: 3 is accepted but behaves as 5. ringTimeoutSec: 240 behaves as 120. The clamp is silent. The value that you read back on the call can differ from the value that you sent.

Poll for the outcome

originate returns at dialing. To learn whether the call connected, fetch the call again. calls.get({ sid }) returns a fresh Call with the current status.

TypeScript
Python

const c = await v.calls.get({ sid: call.sid });
if (c.status === "in_progress") console.log("connected");

c = v.calls.get(sid=call.sid)
if c.status == "in_progress":
    print("connected")

A call moves through these statuses:

Status	Meaning
`dialing`	Originate is accepted. The engine reaches out to the carrier.
`ringing`	The callee’s phone is ringing.
`in_progress`	The call is answered and connected. Audio is flowing.
`completed`	The call ended normally after it connected.
`no_answer`	The call rang past `ringTimeoutSec` without an answer.
`failed`	The call was rejected, busy, or unreachable.

Poll until the call leaves the ringing states to get its terminal outcome:

TypeScript
Python

async function waitConnected(sid: string) {
  for (;;) {
    const c = await v.calls.get({ sid });
    if (c.status !== "dialing" && c.status !== "ringing") return c.status;
    await new Promise((r) => setTimeout(r, 500));
  }
}

const outcome = await waitConnected(call.sid); // in_progress | no_answer | failed

import time

def wait_connected(sid: str) -> str:
    while True:
        c = v.calls.get(sid=sid)
        if c.status not in ("dialing", "ringing"):
            return c.status
        time.sleep(0.5)

outcome = wait_connected(call.sid)  # in_progress | no_answer | failed

Polling is fine for one-off calls. For fleets of calls, subscribe to call-lifecycle events instead of polling each sid. The engine pushes every transition (initiated, ringing, answered, cleared) as it happens.

Placing many calls

calls.originate places one call. For high-volume outbound — pacing thousands of numbers with a rate limit and a concurrency cap — use the control-plane bulk dialer. Do not loop originate yourself. The bulk dialer owns the pacing and back-pressure. See the PBX & ACD guide for campaign setup.

SIP trunking

Create and configure the trunks that outbound calls route over.

Number provisioning

Allocate the numbers that you present as caller-id.

Call lifecycle

The full event stream — a push alternative to polling status.

AI ↔ human handoff

Attach an agent mid-call, or hand a call between a bot and a person.

​Before you start

​Place a call

​Attach an AI agent

​Cap the ring time

​Poll for the outcome

​Placing many calls

​Related

SIP trunking

Number provisioning

Call lifecycle

AI ↔ human handoff

Before you start

Place a call

Attach an AI agent

Cap the ring time

Poll for the outcome

Placing many calls

Related