Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.getsmartalex.com/llms.txt

Use this file to discover all available pages before exploring further.

Organised by symptom first, SIP response code second. If you know the SIP code, use the second table. If you just know what the caller experienced, start with symptoms.

​
Quick diagnosis , by symptom

Most common causes (in order):
  1. Wrong credentials , re-copy username and password from SmartAlex
  2. SIP ALG enabled on firewall , disable it
  3. Outbound UDP 5060 blocked , check firewall rules
  4. Wrong transport , verify UDP vs TCP vs TLS matches both sides
Verification: your PBX’s activity log or SIP trace will show the exact response (401 Unauthorized, 403 Forbidden, or timeout).
  • The DID is not registered to the trunk. Add it under the trunk’s DIDs list.
  • Your inbound route doesn’t send the DID to the SmartAlex trunk. Update the rule.
  • Agent not linked to the trunk. In Agent Studio → Telephony tab → select the trunk.
  • Wallet empty (test-mode workspaces). Top up in Settings → Billing.
  • Agent has no configured first message AND no system prompt — the AI has nothing to say.
  • The call exceeded the workspace’s max-call-duration (default 300s).
  • Voice runtime dispatch failed — check the call detail page or contact support.
  • The agent isn’t linked to the SIP trunk — set this in Agent Studio → Telephony.
  • Extensions not populated — add them in Settings → PBX.
  • The extension has no aliases and the caller isn’t using the exact display name — add aliases via CSV upload.
  • The trunk is suspended — reactivate it.
  • Target extension doesn’t exist on the PBX , verify in the PBX admin console.
  • Wrong pbx_domain , the AI is sending sip:101@wrong-hostname. Fix in the trunk settings.
  • PBX is accepting REFER but rejecting the target , check for 486 / 603 in the PBX SIP log.
  • Firewall blocking inbound SIP from our IP range (shouldn’t be, since we use the existing dialog , but some very aggressive firewalls may block).
Almost always SIP ALG on a router between your PBX and the internet. Disable SIP ALG and reboot the router. If that doesn’t fix it:
  • Check that your PBX’s external / public IP is correctly set in its network settings
  • Verify RTP port range (9000–10999 typical) is open both ways on the firewall
  • Try TCP transport instead of UDP as a test
  • Some endpoint (softphone, desk phone, or PBX) is double-applying echo cancellation. Disable on one side.
  • On calls traversing a carrier with poor echo handling, enable Krisp noise cancellation on the trunk.
Firewall UDP session timeout is too short. Increase to at least 1800 seconds (30 minutes) on the firewall between your PBX and the internet.
The workspace’s max_duration is set to 300 seconds. Increase it in the agent settings if longer calls are expected.
  • Packet loss in transit , run a mtr or traceroute from PBX to sip.voice.getsmartalex.com and look for loss or high jitter hops
  • Insufficient bandwidth , each concurrent call needs 90–100 kbps sustained
  • Wrong codec , G.711 requires ~90 kbps; if you’re on G.729 with poor implementation, switch to G.711
  • Enable Krisp noise cancellation on the trunk
  • Agent’s voice_accent is not set or is set to something that doesn’t match , reconfigure in Agent Studio → Voice.
  • Some agents hard-code accent in the system prompt; check for conflicting instructions.
  • Some PBXes only surface the first leg by default. Check PBX CDR settings to enable “transfer leg” reporting.
  • 3CX: enable Call reporting → Advanced options.
  • FreePBX: enable CDR reporting under Reports → CDR Reports.

​
By SIP response code

Your PBX sent an INVITE without authentication, or with the wrong credentials. Verify SIP username and password exactly match what’s configured in SmartAlex. Passwords are 24 random characters , a single mis-typed character will cause this.
PBX authenticated but is not authorised for this action. Causes:
  • IP allowlist mismatch (if using IP auth) — verify your public IP is listed
  • Trunk suspended — check trunk status in Settings → PBX
  • Account in read-only mode
The DID being dialled is not registered to any trunk. Add the DID to the trunk’s numbers list, or contact support to register it on the inbound side.
PBX didn’t respond in time. Most often a network/firewall issue. Check:
  • Outbound UDP 5060 not blocked
  • SIP ALG disabled
  • PBX is reachable from the public internet
Target extension exists but isn’t registered (phone offline, network down). PBX is responding correctly; fix on the PBX side.
Target is on another call. Your PBX’s busy-forward rules apply (usually voicemail or ring-group fallback). This is expected behaviour, not an error.
Codec mismatch. The target side won’t accept the codecs offered. Reconfigure the trunk to advertise G.711 u-law first. If the target PBX requires G.729, enable it on the trunk (note: licensed codec, requires enablement).
Either:
  • Concurrent call limit reached , increase max_concurrent_calls on the trunk
  • Platform-wide rate limit hit , extremely rare; if it persists, contact support
All alternative routes are busy. PBX-side issue; adjust hunt groups or voicemail fallback.
The target explicitly declined the call. Most often means the extension number doesn’t exist in the PBX. Verify extensions are provisioned.

​
Diagnostic commands

On your PBX:
  • 3CX: Admin → System → Activity Log (or Event Log on v18/v19)
  • FreePBX: Admin → Reports → Asterisk Log Files → /var/log/asterisk/full
  • Asterisk raw: asterisk -rvvvv then pjsip set logger on
  • Yeastar: System → Event Center → SIP Logs
On the SmartAlex side:
  • The Phone Numbers page has a Diagnostics button on each number , click it to see a live health check (active status, agent assignment, voice engine registration, credentials).
  • Call records show SIP disconnect reasons in the Call Logs page.
  • For deeper debugging, contact support with the call ID from the call record.

​
Verifying DNS and reachability

From any machine with dig: 
dig +short sip.voice.getsmartalex.com
If the lookup succeeds, you’ll see one or more A records pointing to SmartAlex SIP infrastructure. If it fails, your DNS is the issue — check upstream resolvers. Test reachability: 
# UDP ping (requires netcat with UDP support)
nc -u -v -z sip.voice.getsmartalex.com 5060

# TLS connection test
openssl s_client -connect sip.voice.getsmartalex.com:5061 -servername sip.voice.getsmartalex.com

​
When to escalate

Open a support ticket with:
  • Your workspace ID
  • The SIP trunk ID (visible in Settings → PBX)
  • The call ID of a failing call (from Call Logs)
  • A SIP trace from your PBX covering 30 seconds before and after the failure
  • The error symptom in plain language
Email: support@getsmartalex.com.

​
Next steps

Testing & Validation

Proactive test procedures to catch issues before customers do.

Observability

Monitoring and alerting.