Coming from a PBX

If you run Asterisk, FreePBX, 3CX, Genesys or a hosted UCaaS, most of CallAgent will be familiar and a few things will not be. This page maps what you know onto what is here, and says plainly where the mapping breaks.

The mapping

Your world	CallAgent	Note
Trunk / peer	SIP trunk + one or more gateways	A trunk is the relationship; a gateway is a host. Several gateways give failover.
sip.conf / pjsip.conf peer	A trunk row; generated Sofia XML per gateway	GET /telephony/sip-trunks/{id}/config shows the generated XML before you apply it.
Dialplan context	Inbound routes, DIDs, number destinations	Ordered resolution, not pattern-matched extensions.
exten => pattern	A DID with pattern and match_type, or an inbound route
Extension	Extension	Same idea. SIP devices register against it.
Queue (queues.conf)	Queue	Nine distribution strategies.
ringall / leastrecent / fewestcalls / rrmemory	fifo / longest_idle / least_calls / round_robin	Close but not identical — read the strategy table.
Agent penalty	Queue member penalty	Same semantics: the first sort key in every strategy.
Wrap-up time	wrap_up_seconds	A server-side deadline, plus a required disposition.
IVR / auto-attendant	IVR flow, 16 node types	A published graph, versioned.
Time condition	Time condition	Weekly hours, holidays, manual override.
Ring group	Ring group
ChanSpy	Supervisor listen / whisper / barge	Audio is not proven.
MoH	music_on_hold_id on a queue
Voicemail box	Voicemail box	Greetings, transcription, notification, retention.
CDR	The calls table and GET /calls	Plus events, metrics, costs and artifacts per call.
AMI / ARI	The REST API and webhooks	Event-driven, signed, retried.
AGI script	A tool the model calls, or a phone-number hook
Conference bridge	Conference room	PIN-protected, optionally recorded, moderator-gated.

The four things that are genuinely different

1. There is no dialplan

A PBX dialplan is a program. CallAgent's routing is a fixed, ordered lookup:

1. an inbound route matching the number, by priority;
2. the number's dynamic hook, if enabled;
3. the number's static destination;
4. for a SIP-trunk call, the trunk's fallback destination.

First match wins. No Goto, no variables, no GotoIf.

If you need logic — route by caller history, by CRM state, by whatever — that is the dynamic hook: CallAgent asks your server at call time and you answer with a destination. It has a timeout of 200–3000 ms and an explicit fallback (static, reject or voicemail) for when you are slow. Choose that fallback deliberately; it is the difference between a forgiving system and a caller hearing silence.

An unmatched number is rejected, not sent to a default. Routing a call you cannot identify to a default assistant is how one tenant's caller reaches another tenant's agent.

2. The AI leg and the human leg are one call

There is no "the IVR handed off to the queue and now it is a different call". The assistant and the operator are legs of one record, and the call moves through states: assistant_speaking → human_queue → human_connected.

Practically:

• The caller is never re-dialled on handover. The existing carrier leg is redirected in place into a conference, or a second participant is added to the same live media session. Nobody's phone rings twice and no second call appears on your bill.
• One transcript covers both halves, with a handoff seam row where the change happened.
• The operator's screen already has the transcript, the summary and the reason.

3. Configuration is versioned and published

A PBX applies a change when you reload. CallAgent has a draft and a published version, and a call pins the version it started with. Editing an assistant during a call cannot reach that call.

That means:

• publish is a real step. An edit that is not published does nothing.
• GET /assistants/{id}/validate before publishing catches a configuration that would fail on a live call.
• Two calls with the same config_hash really did run the same configuration, which is what makes an incident investigation possible.

4. Latency is the product

A PBX cares about jitter and packet loss. A voice agent cares about those and about the gap between the caller finishing a sentence and hearing a reply. That gap is made of transcription, endpointing, a model call and synthesis, and CallAgent times each separately: GET /calls/{id}/metrics.

The setting that most changes how a call feels is not the codec. It is endpointing and barge-in. Budget an afternoon for it.

What you will miss

Honestly, before you commit:

A SIP trunk that carries a call to an assistant	Registration, IP auth and ACL admission work and are proven against a lab peer. The media handoff after that is not built, so no trunk call has ever reached an assistant. Twilio is the only carrier proven end to end. Detail.
A softphone in the browser	Specified, architecture settled, not built. Operators register a SIP device.
Warm transfer on a hosted carrier	Consultative transfer uses FreeSWITCH commands. On a Twilio call it becomes a conference join, and a private consultation between two operators is not offered rather than faked.
Reaching an internal extension from a hosted carrier	Refused with extension_not_reachable_from_carrier unless the extension has an always-forward destination.
Supervisor audio you can rely on	The permission gate and audit trail are proven. That audio actually bridges is not.
A dialplan-shaped escape hatch	The dynamic hook is the escape hatch, and it is an HTTP call with a 3-second ceiling.
G.729	Not in the default codec list and not in the shipped FreeSWITCH module set.
SAML SSO	Not implemented; OIDC is.

A migration that works today

Given the SIP state above, the path that actually gets a call to an assistant is:

1. Keep your PBX. Do not migrate it.
2. Get one number on Twilio, or port one.
3. Point it at a CallAgent assistant.
4. Give the assistant a transferCall tool whose destination is external — your PBX's existing number. Escalation goes back to the humans you already have.
5. Measure. GET /calls/{id}/metrics and GET /calls/{id}/costs per call.
6. Move more numbers when the numbers justify it.

This gives you the AI front door without betting your telephony on a media path that does not exist yet.

If you want the contact centre as well, run the operators inside CallAgent with SIP devices registered against extensions, and the handover stays inside one call record.

Numbers and identity

• Numbers are E.164 everywhere: +40712345678. Not 0712345678, not 0040…. Per-trunk normalisation (leading_plus, inbound_strip_digits, inbound_number_prefix, outbound_prefix) exists for carriers that disagree.
• You may only present a number your organization owns. Asking to present anything else is unverified_caller_id, a 403. Caller-ID policies let you pool several.
• Emergency calling is not addressed anywhere in this system. Do not assume it works.

Next

• SIP trunking — the trunk model in full, with the honest state.
• Contact centre — queues, operators, handover.
• What is not built — read this before the pilot, not after.
• Glossary — where our word and yours differ.