SmartAlex Documentation - AI Voice Assistant Platform

Audience: CTO, network engineer, voice engineer. This page is the technical truth.

The three participants

Every integration involves exactly three parties:

Caller, on any phone, anywhere
Customer’s phone system, the PBX or carrier the customer already owns
SmartAlex Voice Platform, the AI runtime, media routing, and SIP infrastructure

Once the AI has transferred the caller, SmartAlex is completely out of the media path. The caller and your team member are connected directly through your own PBX.

Two connection shapes

The SIP trunk between your PBX and SmartAlex runs in one of two directions, both first-class:

Shape	Who registers	When to use
Outbound trunk (default)	Your PBX registers (or IP-whitelists) to `sip.voice.getsmartalex.com` and ships INVITEs to us	You want a dedicated SmartAlex DID and don’t need the AI on your internal directory
Native Extension Mode (register direction)	SmartAlex registers as an extension on YOUR PBX, just like a softphone	The AI should be one of many phones on your PBX, dialable internally, includable in ring groups and queues

Both shapes use SIP REFER for transfers (same RFC 3515 mechanism, same caller ID preservation via P-Asserted-Identity). The runtime behaviour is identical from the caller’s perspective. See Native Extension Mode for the inverse-direction walkthrough.

Inbound call flow

The sequence when a caller dials a DID that routes to SmartAlex:

Transfer flow, SIP REFER

When the caller asks to be connected to a person or department, the AI issues a standard SIP REFER: Key properties of this flow:

The REFER travels on the existing SIP dialog, no new outbound trunk needed from our side
Your PBX handles the new INVITE using its own rules: ring groups, queues, busy-forward, no-answer-forward, all of it
The original caller’s number is preserved via the P-Asserted-Identity header (RFC 3325)
Once the transfer is accepted, SmartAlex is no longer in the media path

Trust boundaries

Customer-side credentials (your SIP auth, your PBX admin password) never leave your infrastructure.
SmartAlex-side credentials (the username and password we issue you for the SIP trunk) are stored encrypted in our secrets vault. Never logged, never visible to support staff.
All SIP signalling can be encrypted end-to-end using TLS (port 5061). Media can be encrypted using SRTP.

Authentication model

Two supported methods, you pick one or use both.

Method	How it works	When to use
Digest credentials	We issue a username and 24-character password. Your PBX registers or sends INVITEs with those credentials.	Most common. Works for any PBX with a public-facing SIP client. No need for static IP.
IP allowlist	Your PBX’s public IP is added to the trunk’s allowed source list. No credentials needed.	When your PBX has a static public IP and you want the simplest possible auth. Common with on-premise enterprise PBXes.
Both	Digest + IP allowlist. INVITEs must pass both checks.	Enterprise security postures that require defence in depth.

Where audio actually flows

Before transfer:

Caller <-RTP-> Your PBX <-RTP-> SmartAlex SIP Ingress <-RTP-> AI Voice Runtime

After transfer:

Caller <-RTP-> Your PBX <-RTP-> Extension 101

SmartAlex’s media path ends at the moment the REFER is accepted. We’re not a man-in-the-middle on the human-to-human conversation.

Failure modes and fallbacks

Failure	What happens	What the caller experiences
REFER timeout (30 seconds with no response from PBX)	Fallback speech triggered	”I wasn’t able to connect you to Sarah. Can I take a message instead?”
Extension unknown to AI	Tool raises validation error	AI asks clarifying question, offers alternatives
PBX unreachable entirely	Fall back to `call_forwarding_number` if configured, else take message	”I can’t reach our team right now. What’s the best number to call you back on?”
AI silent or confused	Caller can hang up; call records flagged for review	Standard disconnect

Codecs and media

Setting	Default	Configurable
Codecs	G.711 u-law (PCMU) first, G.711 A-law (PCMA), G.722 HD	Per trunk
DTMF	RFC 2833 (telephony-event)	Not configurable, standard
Jitter buffer	Adaptive, 20-200 ms	No
Packet loss concealment	Enabled	No
Noise suppression	Optional Krisp AI noise cancellation on ingress	Per trunk
MOS target	> 4.0 in normal network conditions	Network dependent

Concurrency model

Three layers cap concurrent calls:

Per trunk, configurable, default 10, maximum 1000
Per workspace, set on your account, typically matches your plan
Global platform, scales with infrastructure and is always higher than any single customer needs

When a limit is reached, new SIP INVITEs receive 503 Service Unavailable with a Retry-After header.

Regional routing

SmartAlex SIP ingress is geographically distributed. INVITEs are routed to the nearest region automatically based on your PBX’s public IP, keeping audio latency low. For South African customers, calls are typically routed via European ingress (120 to 150 ms one-way typical). Dedicated SA regional ingress is on the roadmap.

Next steps

Security & Compliance

Encryption, retention, POPIA, GDPR.

Network Requirements

Firewall rules, ports, NAT.

Call Routing & Transfers

Cold, warm, attended, what we support.

​The three participants

​Two connection shapes

​Inbound call flow

​Transfer flow, SIP REFER

​Trust boundaries

​Authentication model

​Where audio actually flows

​Failure modes and fallbacks

​Codecs and media

​Concurrency model

​Regional routing

​Next steps

Security & Compliance

Network Requirements

Call Routing & Transfers

The three participants

Two connection shapes

Inbound call flow

Transfer flow, SIP REFER

Trust boundaries

Authentication model

Where audio actually flows

Failure modes and fallbacks

Codecs and media

Concurrency model

Regional routing

Next steps