Inbound Calls - TeleQuick

When a caller dials one of your numbers, TeleQuick Voice answers the carrier for you and hands the call to whatever you pointed that number at — an AI agent, a human queue, a prompt, or your own code. The one idea to internalize: an inbound call is the same object as an outbound one. The SIP gateway runs the call as a back-to-back user agent (B2BUA), decodes the carrier’s audio, and publishes it onto the very same tracks an outbound call uses:

voice/<sid>/uplink     caller → cloud   (what the caller is saying)
voice/<sid>/downlink   cloud → caller   (what is played back)

So every SDK primitive you already know — attach an agent, open an AudioBridge, transfer, hangup — works on an inbound sid unchanged. There is no separate inbound media API. The only inbound-specific decision is what should happen the moment the call is answered.

How the gateway answers

You do not send provisional or final responses yourself; the gateway does it, in the exact sequence carriers expect:

100 Trying

The gateway acknowledges the carrier’s INVITE immediately so the trunk does not retransmit.

183 Session Progress (with SDP)

Early-media answer carrying the negotiated SDP. This opens the media path before the call is picked up, so a ringback tone or an agent greeting can be heard during ringing.

200 OK (same SDP)

Final answer. The gateway reuses the SDP it already offered at 183.

The answer always carries SDP on 183/200. An SDP-less 180 Ringing makes many carriers tear the call down with a BYE, so TeleQuick never sends one. If you bring your own trunk, make sure your carrier accepts early media with SDP — see SIP trunking.

Once answered, the carrier’s G.711 (µ-law/A-law) audio is decoded to the internal format, published on voice/<sid>/uplink, and whatever you publish on voice/<sid>/downlink is paced back to the caller. The full state machine — ring, answer, hold, transfer, clear — is on Call lifecycle.

Decide what happens on answer

Each trunk (or number) carries an inbound rule that the gateway consults when a call arrives:

Rule	What the gateway does
`HANDLE_AI`	Auto-bridge the call to a server-side agent. The runtime is attached for you.
`PLAY_AND_HANGUP`	Play a prompt (an audio URL), then hang up. No agent, no bridge.
`NOTIFY_AND_HANGUP`	Notify your app of the incoming call so you answer and drive it.
`REJECT`	Refuse the `INVITE` — for numbers you never want to receive on.

Most teams never touch this directly: in the voice console at agent.telequick.dev you assign a number (or trunk) to an agent, a skill queue, or an IVR program, and the console sets the rule for you. The rest of this page shows each path.

Route to an AI agent (the common case)

Point a number at an agent and you are done — the gateway answers, attaches the runtime, and wires the audio bridge end to end. Your process never touches the media. This is HANDLE_AI.

Console
Python
Go

In agent.telequick.dev, open the number under Numbers, set On inbound → AI agent, and pick the agent you built (e.g. support-frontline). Save. The next call to that number reaches the agent. See Build a voice agent.

from telequick.method_id import InboundRule

# native-core control client, connected to your engine RPC endpoint
await client.set_inbound_routing(
    trunk_id="trunk_main",
    rule=InboundRule.HANDLE_AI,
    ai_quic_url="agent://support-frontline",   # the agent to bridge to
)

err := client.SetInboundRouting(
    "trunk_main",
    github.com/telequick/telequick-sdk/go.InboundRule_HANDLE_AI,
    "",                       // audioUrl
    "",                       // webhookUrl
    "",                       // aiWebsocketUrl
    "agent://support-frontline", // aiQuicUrl
)

Programmatic set_inbound_routing lives in the native SDK cores (Python, Go, Rust). The browser/TypeScript SDK does not carry this low-level RPC — configure inbound routing for TypeScript apps in the console (or your control-plane provisioning), then handle the resulting call with the high-level Voice client.

Because the agent runs entirely server-side, turn-taking, barge-in, and tool calls are all handled for you — tune them in Turn detection and Tool calling.

Route to a human or a queue

To send inbound callers to people, point the number at a skill queue or an IVR program (VDN) instead of an agent. The gateway answers, the dialplan runs your IVR steps (announcements, digit collection, queue_to_skill), and the ACD picks the next eligible agent — on a browser softphone or a real SIP deskphone. This is all configuration; you write no media code.

PBX / ACD

Skills, VDNs, IVR vectors, and the agent picker behind human routing.

AI → human handoff

Let an AI agent qualify the caller, then warm-transfer to a person.

A common pattern is to answer with AI first and escalate: the agent gathers intent and identity, then calls a queue-transfer tool to hand the live call to a human.

Handle the call in your own process

When you want your own service to answer and drive inbound audio — rather than a prebuilt agent — use NOTIFY_AND_HANGUP. The gateway tells your app about each incoming call; you answer it, then attach an AudioBridge to the resulting sid exactly as you would for an outbound call. This is the “inbound == outbound” payoff.

Set the rule to notify

Configure the trunk with NOTIFY_AND_HANGUP and (optionally) a webhook_url the gateway POSTs incoming-call events to.

Receive the incoming call

Get the caller and the sid — from your webhook, or by pulling queued calls on the native core (get_incoming_calls), whose results arrive on your event stream.

Answer, then bridge

Accept the leg with answer_incoming_call, then subscribe uplink and publish downlink through an AudioBridge on that sid.

Python (native core)
TypeScript (bridge by sid)

from telequick.method_id import InboundRule

await client.set_inbound_routing(
    trunk_id="trunk_main",
    rule=InboundRule.NOTIFY_AND_HANGUP,
    webhook_url="https://ops.example.com/hooks/inbound",
)

# In your event handler, when an incoming call arrives for this trunk:
async def on_call_event(ev):
    if ev.type == "CHANNEL_CREATE":
        # Accept the leg (empty AI URLs → you drive the media yourself).
        await client.answer_incoming_call(ev.call_sid)
        # From here, open an AudioBridge on ev.call_sid and read/write frames.

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

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

// Your webhook handed you the inbound call's sid.
export async function handleInbound(sid: string) {
  const bridge = await v.audioBridge.attach(sid, {
    codec: "pcm16",
    onUplink: (frame, tsUs) => {
      // caller audio → your ASR / model
    },
  });
  // reply → the caller
  bridge.publishDownlink(replyPcm, Date.now() * 1000);
  return bridge;
}

The attach half of the AudioBridge is written from the server’s point of view: you subscribe uplink (hear the caller) and publish downlink (talk to the caller). This is the same handle an outbound call gives you — see Sessions, calls, tracks & streams.

Where routing decisions live

The gateway does not hardcode any of this. On answer it asks the engine’s dialplan — a hot-reloaded rule engine, keyed by DID then source IP — what to do with the call: play a prompt, start an AI bidirectional stream, or enter an IVR vector. Editing a number’s routing in the console updates those rules within seconds; in-flight calls keep the behavior they started with. Trunk INVITEs bypass the registrar’s access control, while everything else is gated by digest auth, source-IP ACLs, and a spam filter (see SIP trunking).

Number provisioning

Buy, import, and assign the numbers callers dial.

Outbound calls

The mirror of this page — originate calls and the paced dialer.

Call lifecycle

Ring, answer, hold, transfer, and clear — the full state machine.

Audio bridge API

Subscribe uplink and publish downlink on any sid.

​How the gateway answers

​Decide what happens on answer

​Route to an AI agent (the common case)

​Route to a human or a queue

PBX / ACD

AI → human handoff

​Handle the call in your own process

​Where routing decisions live

​Related

Number provisioning

Outbound calls

Call lifecycle

Audio bridge API

How the gateway answers

Decide what happens on answer

Route to an AI agent (the common case)

Route to a human or a queue

Handle the call in your own process

Where routing decisions live

Related