PBX / ACD Integration

You have two ways to put agents on calls without a change to your phone system. The first way: peer with your PBX. Keep Asterisk or FreeSWITCH answering the PSTN, and hand selected calls to ClutchCall Voice over a plain SIP trunk. The second way: route through the built-in ACD. Let the platform own the number, walk callers through an IVR vector, and distribute calls to skill queues. Those queues can mix AI agents with human agents on browser softphones or real SIP deskphones. Pick the first way when you migrate incrementally and the PBX stays the system of record. Pick the second way when you want the platform to be the contact-center brain end to end.

The SIP signalling plane is an internal B2BUA with its own built-in registrar. There is no separate SIP proxy or registrar service to run. Your PBX talks to it as an ordinary SIP peer.

Option A — Peer with a tenant PBX over SIP

The internal realm reaches your PBX as a SIP peer. You define a trunk whose realm is internal. You point it at your PBX’s SIP address. You then route calls across it in either direction. Media is G.711 (PCMU/PCMA) on the wire. The engine decodes it to the runtime’s PCM16 bus and transcodes it back. Any PBX that speaks standard SIP + RTP interoperates.

Create an internal-realm trunk to the PBX

Add a trunk that matches on the PBX’s source IP (or a DID map) and carries its SIP/RTP addressing. Set realm: "internal" so the engine treats the trunk as a trusted peer, not as a carrier edge. Internal-realm INVITEs bypass the registrar ACL. Trunks are sealed at rest and hydrated to the engine. See SIP Trunking and the full field list in admin trunks.

// AddTrunk DTO (abridged) — a peer link to an on-prem Asterisk/FreeSWITCH
{
  "trunk_id": "pbx-hq",
  "direction": "both",
  "realm": "internal",
  "gateway_ip": "10.20.0.10",          // the PBX SIP address
  "internal_sip_ip": "10.20.0.2",
  "internal_rtp_ip": "10.20.0.2",
  "codec_preferences": ["PCMU", "PCMA", "OPUS"],
  "inbound_rule": 3,                    // HANDLE_AI: hand the leg to an agent
  "agent_id": "support-agent"
}

Send calls from the PBX to an agent

In your PBX dialplan, route the extensions or DIDs that you want AI-handled to the trunk. In Asterisk, that is a Dial(PJSIP/${EXTEN}@pbx-hq). In FreeSWITCH, that is a bridge to the gateway. The INVITE lands on the SIP gateway, which resolves the trunk by source IP. Because inbound_rule is HANDLE_AI, the gateway starts the bound agent and answers with early media. The answer sequence is 100 Trying → 183 with SDP → 200 with the same SDP. An SDP-less 180 makes some carriers drop the call, so the gateway always offers early media.

Send calls from an agent back to the PBX

Outbound originations and transfers can target the same trunk. An AI agent can therefore hand a caller to a PBX extension — a human on a deskphone that the PBX already manages. Use the SDK’s Calls.originate with the pbx-hq trunk_id, or use an in-call transfer. The platform sends a blind or attended transfer as SIP REFER.

TypeScript
Python

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

const voice = new Voice({ apiKey: process.env.CLUTCHCALL_API_KEY });

// Ring a PBX extension across the peer trunk and attach an agent.
const call = await voice.calls.originate({
  trunkId: "pbx-hq",
  to: "sip:2001@10.20.0.10",   // extension on the tenant PBX
  app: "AI_BIDIRECTIONAL_STREAM",
  agentId: "support-agent",
});

// Later, transfer the live leg to a human extension via SIP REFER.
await call.transfer({ to: "sip:2002@10.20.0.10" });

from clutchcall import Voice
import os

voice = Voice(api_key=os.environ["CLUTCHCALL_API_KEY"])

call = voice.calls.originate(
    trunk_id="pbx-hq",
    to="sip:2001@10.20.0.10",
    app="AI_BIDIRECTIONAL_STREAM",
    agent_id="support-agent",
)

call.transfer(to="sip:2002@10.20.0.10")

Inbound peer REFER (RFC 3515) is acknowledged (auto-202), and it emits a transferred lifecycle event. But execution of the outbound leg from a PBX-originated REFER is only partially implemented. Platform-side operator-initiated transfer (the SDK transfer call above) is fully wired. Drive transfers from the platform side for now.

The engine is itself a FreeSWITCH-style modular core: an internal registrar, dialplan, and B2BUA modeled on the FreeSWITCH internal profile. A full cutover is therefore usually just a re-point of trunks and agents. There is no proxy to migrate. See Migrate from Asterisk / FreeSWITCH.

Option B — Route through the built-in ACD

The ACD is Avaya-shaped. A VDN maps an inbound number to an entry point. A vector runs an IVR program. Skill queues distribute matched calls to agents. The ACD works for AI agents, human agents, or a warm AI→human handoff in the same queue.

The routing objects

VDN

Maps a DID to a routing entry point, plus a default_skill_id / default_hotline_id. An inbound number lands here before any IVR.

Vector

The IVR program: an ordered list of steps — announcement, wait, collect_digits, check_skill, queue_to_skill, route_to_vdn, goto_step, busy, disconnect.

Skill

A competency tag. Agents are members of skills. The ACD queues calls to a skill, and the picker matches the best available agent.

Queue / callback

A queued request carries a queue_priority (1–4). It moves through queued → matched → accepted → completed, or ends at abandoned / expired.

Wire up a queue

Define a VDN for the number

Point the DID at a VDN with a default skill. Manage VDNs, vectors, skills, and hotlines from the voice console at agent.clutchcall.dev. The corresponding admin API routers back the same objects.

Author the vector (IVR)

Sequence the caller experience: play an announcement, optionally collect_digits, then queue_to_skill. The prompt-playback service renders announcements from pre-recorded 8 kHz prompt clips. There is no TTS or GPU in the IVR path, so prompts are deterministic and low-latency.

// dim_vector_step (abridged) — greet, gather, queue
[
  { "kind": "announcement",   "prompt": "welcome" },
  { "kind": "collect_digits", "max_digits": 1, "timeout_ms": 5000 },
  { "kind": "check_skill",    "skill_id": "billing", "on_no_agents": 4 },
  { "kind": "queue_to_skill", "skill_id": "billing", "priority": 2 }
]

Choose a distribution algorithm

The picker supports Avaya-style algorithms: ead_mia (expected-agent-delay with most-idle-agent, the default), mia, ucd (round-robin), loa, lar, and manual. Set the algorithm per skill.

Let agents accept offered calls

The ACD offers a queued call to a picked agent. The agent accepts, and the media bridges. Browser softphone agents accept over their control channel. SIP deskphone agents are rung with an INVITE. The accept signal is unified across both endpoint types. Unaccepted offers re-queue (RONA) with a first-wins glare guard.

Human agent endpoints

An agent can be a browser softphone, a real SIP deskphone/softphone, or a PSTN callback. SIP-phone agents REGISTER to the internal registrar with their AOR credentials (sealed at rest). On an ACD claim, the gateway looks up the registration, sends the INVITE, and bridges RTP on the caller’s own shard. The ring strategy is all or first. The gateway transcodes PCMU↔PCMA as needed. This is how the ACD puts a call on a deskphone that your PBX would otherwise own — without the PBX in the path. See Number Provisioning for the per-tenant <workspace-id>.sip.clutchcall.dev domain that agents register against.

Let an AI agent hand off into a queue

A tool bridges the two worlds. An AI agent in the runtime can call the route-to-skill telephony tool to place the live caller into an ACD queue for a human. This is the platform’s warm-handoff pattern for regulated verticals: the LLM does intake, qualification, and compliance capture, then routes to a human before audio cuts in.

// Agent tool config — expose a live human-queue transfer to the model
{
  "type": "telephony",
  "name": "route_to_skill",
  "skill_id": "billing",
  "priority": 1
}

Under the hood, this posts to the ACD queue endpoint. When a human accepts, the AI leg’s egress pauses, and the caller is mirrored to the human agent. AI-to-Human Handoff covers the mechanics of pausing the AI leg and bridging the human. Tool definitions live in Tool Calling.

The ACD data model, picker algorithms, queue/accept flow, and SIP-phone agent endpoints are shipped. The DID “buy a number” catalog is currently a demo stub. Import existing numbers, or point real DIDs from your carrier / PBX. Do not rely on the in-console number search. See Number Provisioning.

Which one should you use?

Peer with your PBX

The PBX still answers the PSTN and owns extensions and voicemail. You hand selected calls to agents over a SIP trunk. You can transfer calls back to PBX extensions. This is the lowest-friction way to add AI to an existing deployment.

Built-in ACD

The platform owns the number, IVR, queues, and agents (AI + human). Use it when you want the contact-center brain — skills, VDN vectors, and warm AI→human handoff — to live here.

SIP Trunking

Trunk fields, realms, and carrier interop.

AI-to-Human Handoff

How the live-call handoff bridges audio.

Migrate from Asterisk / FreeSWITCH

Full cutover: re-point trunks and agents.

​Option A — Peer with a tenant PBX over SIP

​Option B — Route through the built-in ACD

​The routing objects

VDN

Vector

Skill

Queue / callback

​Wire up a queue

​Human agent endpoints

​Let an AI agent hand off into a queue

​Which one should you use?

Peer with your PBX

Built-in ACD

​Related

SIP Trunking

AI-to-Human Handoff

Migrate from Asterisk / FreeSWITCH

Option A — Peer with a tenant PBX over SIP

Option B — Route through the built-in ACD

The routing objects

Wire up a queue

Human agent endpoints

Let an AI agent hand off into a queue

Which one should you use?

Related