Calls - TeleQuick

A call is a single SIP dialog handled by the engine as a back-to-back user agent (two legs, caller ↔ agent). Everything about it — the media session, the agent session, the audio tracks, the CDR, telemetry — keys off one identifier, the call_sid. This page is the control plane for that object: place a call, look it up, move it, and end it. To move audio in and out of a live call, see the audio bridge.

These operations are exposed through the Voice SDK (TeleQuickClient), not a hand-written REST surface. Under the hood each call maps to a typed control-plane RPC (voice.calls.*); the SDK carries your API key and org id, and the control-plane API relays the op to the engine over a correlated control channel. Address calls through the SDK — there is no separately documented POST /calls REST endpoint to curl.

Construct the client

Every calls operation hangs off a TeleQuickClient instance scoped to one org. Construct it once and reuse it.

TypeScript
Python
Go
Rust

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

const voice = new Voice({
  baseUrl: "https://engine.telequick.dev",   // control-plane API host
  apiKey:  process.env.TELEQUICK_API_KEY!,
  orgId:   "org_123",
  relayHost: "relay.telequick.dev",     // for the audio bridge; optional
});

from telequick.voice import Voice

voice = Voice(
    base_url="https://engine.telequick.dev",
    api_key=os.environ["TELEQUICK_API_KEY"],
    org_id="org_123",
)

voice, err := voice.New("https://engine.telequick.dev", apiKey, "org_123")

let voice = Voice::new("https://engine.telequick.dev", &api_key, "org_123")?;

Originate a call

calls.originate dials to from from over the trunk you name, and — if you pass an agent — the engine attaches the voice agent automatically the moment the far end answers. You get back a Call (below) as soon as the request is accepted; watch status (or the call-lifecycle events) to follow it from dialing to in_progress.

Request

string

required

Destination in E.164 (e.g. +15551234567).

from

string

required

Caller-ID presented on the outbound leg, in E.164. Must be a number your trunk is allowed to present.

trunkId

string

required

The trunk to originate on. Trunks are provisioned in the console — see SIP trunking.

agent

string

Optional agent id. When set, the engine binds this server-side voice agent to the call on answer and wires the audio bridge end-to-end, so you don’t open one yourself. Omit it to originate a bare call and drive the audio yourself.

ringTimeoutSec

integer

default:"30"

Seconds to ring before giving up (the call then lands in no_answer). The control plane clamps this to 5..120.

TypeScript
Python
Go
Rust

const call = await voice.calls.originate({
  to:       "+15551234567",
  from:     "+15558675309",
  trunkId:  "trunk_main",
  agent:    "healthcare-assistant",  // optional
  ringTimeoutSec: 30,
});
console.log(call.sid, call.status);   // "cs_…", "dialing"

call = voice.calls.originate(
    to="+15551234567",
    from_="+15558675309",       # `from` is reserved in Python → from_
    trunk_id="trunk_main",
    agent="healthcare-assistant",
    ring_timeout_sec=30,
)
print(call.sid, call.status)

call, err := voice.Calls().Originate(voice.OriginateArgs{
    To:             "+15551234567",
    From:           "+15558675309",
    TrunkID:        "trunk_main",
    Agent:          "healthcare-assistant",
    RingTimeoutSec: 30,
})

let call = voice.calls().originate(OriginateArgs {
    to:               "+15551234567",
    from:             "+15558675309",
    trunk_id:         "trunk_main",
    agent:            Some("healthcare-assistant"),
    ring_timeout_sec: 30,
})?;

The `Call` object

originate and get both return a Call. These fields are the whole object — there are no video codecs or track lists here; audio lives on the bridge.

sid

string

The call_sid — the universal key. Use it to open the audio bridge, attach an agent, transfer, hang up, and to join CDRs, recordings, and telemetry.

status

string

One of dialing, ringing, in_progress, completed, failed, no_answer.

string

Destination number (E.164).

from

string

Caller-ID presented (E.164). In the Python SDK this attribute is from_.

startedAt

string

ISO-8601 timestamp for when the call was created.

trunkId

string

The trunk the call is on. Absent for calls with no trunk association.

agent

string

The bound agent id, if one was attached (at originate or later via agents.attach).

Get a call

calls.get fetches the current Call snapshot by sid. Use it to poll status after an originate, or to hydrate a call you learned about from a webhook or the lifecycle stream.

sid

string

required

The call_sid to look up.

TypeScript
Python
Go
Rust

const call = await voice.calls.get({ sid: "cs_abc123" });
if (call.status === "in_progress") { /* … */ }

call = voice.calls.get(sid="cs_abc123")

call, err := voice.Calls().Get("cs_abc123")

let call = voice.calls().get("cs_abc123")?;

get returns a point-in-time snapshot; it does not stream. For live status without polling, consume call-lifecycle events or wire up webhooks.

Transfer a call

call.transfer moves a connected call. Pass exactly one of:

string

A PSTN number (E.164) to forward the call to. This drives a SIP transfer (REFER) on the caller leg.

agent

string

An agent id to re-attach the call to a different server-side agent, instead of forwarding it off-net.

Passing both, or neither, is rejected before any RPC is sent.

TypeScript
Python
Go
Rust

// Forward to a PSTN number…
await call.transfer({ to: "+15550001111" });
// …or re-attach to a different agent.
await call.transfer({ agent: "billing-specialist" });
// shorthand: a bare string is treated as `to`
await call.transfer("+15550001111");

call.transfer(to="+15550001111")
call.transfer(agent="billing-specialist")

call.Transfer(voice.TransferArgs{To: "+15550001111"})
call.Transfer(voice.TransferArgs{Agent: "billing-specialist"})

call.transfer_to("+15550001111")?;
call.transfer_agent("billing-specialist")?;

The agent re-attach path and operator-initiated to: transfers are wired end-to-end. Executing an outbound leg in response to a peer-initiated REFER (the far end asks to be transferred) is only partially implemented — the request is acknowledged, but the onward leg may not complete. Prefer initiating transfers from your side. For warm AI→human handoff (which is a distinct, shipped flow), see AI ↔ human handoff.

Hang up a call

call.hangup tears down the dialog and both media legs. It emits the cleared lifecycle event (with a Q.850 cause and duration) and finalizes the CDR.

TypeScript
Python
Go
Rust

await call.hangup();

call.hangup()

call.Hangup()

call.hangup()?;

End-to-end

Originate

Dial out, optionally binding an agent so audio is wired for you.

Track status

Poll calls.get, or subscribe to lifecycle events, until status reaches in_progress (or no_answer / failed).

Act on the live call

Move audio with the audio bridge, transfer, or attach a different agent mid-call.

Hang up

Call hangup when you’re done — this is what finalizes the CDR.

Audio bridge

Move caller and agent audio in and out of a live call over MoQT.

Agents API

Bind or swap a server-side voice agent on a call.

Call lifecycle

Every state a call moves through, and the events you can subscribe to.

Outbound dialing

Single originate, paced campaigns, and the dialer model.

​Construct the client

​Originate a call

​Request

​The Call object

​Get a call

​Transfer a call

​Hang up a call

​End-to-end

​Related

Audio bridge

Agents API

Call lifecycle

Outbound dialing

Construct the client

Originate a call

Request

The `Call` object

Get a call

Transfer a call

Hang up a call

End-to-end

Related