Call Lifecycle

A phone call has two views that you care about. This page lines them up. On the wire, the call is a SIP dialog: an INVITE, some provisional responses, a 200 OK, an ACK, then media, then a BYE. In your code, the call is a single CallStatus that walks dialing → ringing → in_progress → completed, or ends early at no_answer or failed. Both views name the same call by the same sid. This page is the map between them: what each SIP message means, when the media path comes up, and exactly where an AI agent attaches. You almost never touch raw SIP. The gateway speaks it for you. But raw SIP knowledge helps when you read a status, debug a call that never connected, or decide when it is safe to attach audio. This page tells you which SIP moment your CallStatus reflects.

The signalling sequence

A back-to-back user agent (B2BUA) in the SIP gateway sits between the caller and the agent. It terminates the caller’s dialog, runs your routing, and drives the signalling on both legs. For a single leg, the message flow is:

   caller / carrier                 SIP gateway (B2BUA)
        │                                  │
        │  ── INVITE (SDP offer) ──────────▶│   dialing
        │  ◀──────────── 100 Trying ────────│   dialing   (gateway got it, working)
        │  ◀──────────── 180 Ringing ───────│   ringing   (far end is alerting)
        │  ◀──── 183 Session Progress (SDP) ─│   ringing   (early media — ringback/IVR audio)
        │  ◀──────────── 200 OK (SDP answer)─│   in_progress  (answered; media negotiated)
        │  ── ACK ─────────────────────────▶│   in_progress  (dialog confirmed)
        │  ══════════ RTP media both ways ══│════════════
        │  ── BYE ─────────────────────────▶│   completed (either side can send BYE)
        │  ◀──────────── 200 OK ─────────────│

For inbound calls, the direction is mirrored. The carrier sends the INVITE, and the gateway answers with 100 / 183 / 200. The state machine is identical. Only the sender of each message flips.

SIP messages → CallStatus

Your SDK never shows individual SIP messages. It collapses them into the six statuses on CallStatus. The gateway applies this mapping:

CallStatus	SIP moment that triggers it	Meaning
`dialing`	`INVITE` sent, `100 Trying`	The call is placed. The far end is not yet alerting.
`ringing`	`180 Ringing` or `183 Session Progress`	The far end is alerting. Early media (ringback / IVR) may already be audible.
`in_progress`	`200 OK` + `ACK`	The call is answered. Media flows both ways.
`completed`	`BYE` after a `200 OK` (Q.850 normal clearing)	The call connected and ended normally.
`no_answer`	Ring timeout, `480`, `486 Busy`, or `408` before any `200`	Nobody picked up, or the line was busy. The call never reached `in_progress`.
`failed`	`4xx`/`5xx`/`6xx` rejection, or media setup failed	The call could not be set up at all.

The most important dividing line: in_progress is the only status that guarantees a live media path. Everything before it is signalling. completed, no_answer, and failed are all terminal. completed means the call connected, then ended. no_answer and failed mean the call never connected.

Media setup: where audio actually comes up

SIP negotiates media with SDP (Session Description Protocol): an offer in the INVITE, and an answer in a response. Two details decide when you have audio:

Early media (183 + SDP). The gateway answers with 183 Session Progress that carries an SDP answer before the call is picked up. This opens a one-way media path. The caller hears ringback, a “please hold”, or an IVR prompt while the call is still in ringing. This is why an AI receptionist can start to talk the instant a caller connects.
Same SDP on 200. When the call is answered, the 200 OK repeats the SDP already agreed in the 183. Nothing re-negotiates, and there is no audio gap at pickup.

The gateway answers with 183 Session Progress carrying SDP, not a bare 180 Ringing. Some carriers drop a call (they send an unsolicited BYE) if they see a 180 with no media description. If you bridge your own carrier and see calls torn down at the ring stage, check this first.

On the wire, phone legs carry G.711 (µ-law or A-law). The media plane decodes G.711 to the runtime’s 8 kHz PCM16 contract. It re-encodes on the way back out: G.711 for a phone leg, Opus for a browser or app leg. You never handle the codec transcoding. See the codec guide for which codec rides which transport.

Where the agent attaches

An AI agent does not wait for the call to be fully answered. The engine wires it up during setup, so there is no dead air at pickup:

INVITE arrives, routing runs

On the inbound INVITE, the gateway resolves the trunk and asks the routing engine what to do. When the decision is “hand this call to an AI agent,” the routing engine tells the runtime to start a session for this sid. The media leg opens on the core that owns the call.

The provider connection pre-warms

While the call is still ringing, a realtime (speech-to-speech) agent opens its model connection ahead of answer, during the INVITE/SDP exchange. The model is then ready the moment audio flows. A cascade (ASR → LLM → TTS) agent opens its provider streams the same way.

Answer, and audio bridges in

On 200 OK + ACK, the call is in_progress. The engine decodes the caller audio to 8 kHz PCM16 and publishes it as the call’s uplink track (voice/<sid>/uplink). The engine publishes the agent’s replies on the downlink track (voice/<sid>/downlink) and paces them out to the caller. The agent is now on the far end of the media bridge.

The turn loop runs until teardown

From here, the runtime drives greet → listen → think → speak until someone hangs up or a guardrail fires. That inner loop is its own topic — see session lifecycle.

You do not write any of this attach logic for a server-side agent. Pass an agent id to originate, or configure it on the inbound trunk. That is enough. The gateway attaches the bridge automatically on answer. If you want to handle the audio yourself instead, attach an AudioBridge to the same sid.

Following the lifecycle from the SDK

originate returns as soon as the call is placed. You get a Call in dialing, not a call that is already connected. Read status, or fetch a fresh snapshot with calls.get, to follow the call forward:

TypeScript
Python

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

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

// Place the call and hand it to a server-side agent on answer.
const call = await v.calls.originate({
  to:      "+15557654321",
  from:    "+15551234567",
  trunkId: "trunk_default",
  agent:   "sales-qualifier",     // engine attaches the bridge on 200 OK
  ringTimeoutSec: 30,             // → no_answer if unanswered in 30s
});

console.log(call.status);         // "dialing"

// Poll forward (or drive this from lifecycle webhooks — see below).
const now = await v.calls.get({ sid: call.sid });
if (now.status === "in_progress") {
  // media is live; safe to attach audio, start recording, etc.
} else if (now.status === "no_answer" || now.status === "failed") {
  // never connected — retry, fall back, or log
}

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="+15557654321",
    from_="+15551234567",
    trunk_id="trunk_default",
    agent="sales-qualifier",       # engine attaches the bridge on 200 OK
    ring_timeout_sec=30,           # → no_answer if unanswered in 30s
)

print(call.status)                 # "dialing"

now = v.calls.get(sid=call.sid)
if now.status == "in_progress":
    ...                            # media is live
elif now.status in ("no_answer", "failed"):
    ...                            # never connected

ringTimeoutSec (server-clamped 5–120, default 30) is the ceiling on the ringing stage. If no 200 OK arrives in time, the gateway gives up. The call lands on no_answer instead of ringing forever.

Lifecycle events and CDRs

The gateway also emits every transition on the wire to the events pipeline, so you do not have to poll. Each SIP milestone becomes a call event: initiated (INVITE), ring, established (answer), holds and resumes, transferred (a REFER-based handoff), and cleared (the final BYE, carrying the Q.850 cause and the call duration). On clearing, the gateway also writes a CDR. Subscribe to these events with webhooks. Read the assembled per-call timeline in call traces.

Multi-segment calls. When a call is handed from an AI agent to a human, or back, it stays one sid. The events pipeline folds the call into multiple segments under that one id. Each segment is tagged by the handler that owned it. A transfer shows up as one continuous call, not two. See handoffs.

Hanging up

Either side ends the call with a BYE. When the caller hangs up, the gateway tears the dialog down. The runtime session ends, and the call moves to completed. To end the call from your side, call hangup():

await call.hangup();               // gateway sends BYE → completed

Teardown cancels any in-flight model work, flushes the outbound audio, releases the media leg, and emits the cleared event and CDR. The runtime side is covered in session lifecycle.

Inbound calls

Receive an INVITE from the carrier and route it to an agent.

Outbound calls

Originate calls and drive them with the paced dialer.

Handoffs

Transfer, REFER, and warm handoff without a change of sid.

Session lifecycle

The greet → listen → think → speak loop inside in_progress.

Codec guide

G.711 on the wire, PCM16 inside, Opus to the browser.

Call traces

The assembled per-call event timeline that you read after the fact.

Overview

Quickstart

Core Concepts

Build Guides

Agent Runtime

Transport to Web & Apps

Transport to Telephony

CTI (CSTA)

High Availability

Comparison & Benchmarks

Migration

Integrations

Observability

SDK Reference

API Reference

Troubleshooting

Cookbooks

Recipes

The signalling sequence

SIP messages → CallStatus

Media setup: where audio actually comes up

Where the agent attaches

Following the lifecycle from the SDK

Lifecycle events and CDRs

Hanging up

Inbound calls

Outbound calls

Handoffs

Session lifecycle

Codec guide

Call traces

​The signalling sequence

​SIP messages → CallStatus

​Media setup: where audio actually comes up

​Where the agent attaches

​Following the lifecycle from the SDK

​Lifecycle events and CDRs

​Hanging up

​Related

Inbound calls

Outbound calls

Handoffs

Session lifecycle

Codec guide

Call traces

The signalling sequence

SIP messages → CallStatus

Media setup: where audio actually comes up

Where the agent attaches

Following the lifecycle from the SDK

Lifecycle events and CDRs

Hanging up

Related