What is AiPBX and what core technologies power it?

AiPBX is an open-source enterprise IP PBX uniting Asterisk 22, Nginx L4 ALPN stream multiplexing, PHP 8 MVC web management, a high-concurrency Go WebSocket chat daemon, and native Android (Kotlin) / iOS (Swift) softphones.

Is AiPBX truly 100% free and open source?

Yes. AiPBX is released under the permissive MIT license. There are zero license keys, zero per-user or per-extension recurring fees, and zero feature paywalls.

How do Passkeys (WebAuthn) and Google OAuth enhance PBX security?

Traditional passwords are prone to phishing and credential stuffing. AiPBX supports FIDO2 asymmetric cryptographic verification using Touch ID, Face ID, Windows Hello, and YubiKey, alongside Google Workspace corporate OAuth 2.0 single sign-on.

Why is Port 443 ALPN stream multiplexing critical for enterprises?

Firewalls at hotels, airports and client offices often block every port except 443. AiPBX carries the web portal, WebRTC calls from browsers and the mobile apps, chat and the TURNS media relay over that single port, so remote staff can still place and take calls. Desk IP phones and carrier trunks keep using the standard SIP ports (5060/5061).

Does Microsoft Teams Direct Routing require third-party hardware or SBCs?

No. AiPBX incorporates a built-in SIP TLS & SRTP gateway fully compatible with Microsoft Teams Direct Routing specifications, eliminating the need for expensive third-party SBC appliances.

Do the mobile softphone applications drain battery life?

Not at all. AiPBX native Kotlin and Swift apps utilize High-Priority Push Notifications (FCM / APNs) instead of sustaining battery-draining continuous background sockets. Battery consumption is practically zero.

How do supervisor listening and whispering work?

A user with the supervisor or admin role dials the code and then the extension: *90 listens silently, *91 talks to the agent only (the caller cannot hear), *92 joins the call as a third party. The same actions are available from the Listen / Whisper / Barge buttons on the call center board.

How can I install AiPBX on my server?

On a clean Ubuntu 26.04 LTS machine, run our one-liner turnkey script: curl -fsSL https://raw.githubusercontent.com/mahirgul/AiPBX/main/install.sh | sudo bash The installer compiles Asterisk 22 and configures Nginx stream, MariaDB, PHP 8, and Go chat automatically.

Troubleshooting

Apply succeeds but nothing changes

Check Pending Changes: a change that could not be written or loaded stays in the list; the error is shown on Apply and kept in the audit log.
The portal must be able to write /etc/asterisk/pbx/. If Apply reports "Read-only file system", the Apache override is missing — run sudo bash /opt/aipbx/install.sh --upgrade (see Security → Apache sandbox).
Regenerate every configuration from the database: cd /opt/aipbx/web && sudo php src/asterisk_sync.php (reloads only, calls are not dropped).

Portal actions fail with "sudo: I'm sorry www-data"

Ubuntu 26.04 uses sudo-rs, and the Apache unit hides /etc/sudoers. The installer's Apache override fixes it; run install.sh --upgrade if the override is missing.

A call is answered and immediately hung up

Usually an IVR/announcement sound is missing. Look for "does not exist in any format" in /var/log/asterisk/messages.log and see Sounds.

A number is not routed ("No matching inbound route", congestion)

Find out what the trunk actually sends (next section), then check:

the trunk's DID trimming — it also shortens transit numbers;
that an inbound route exists in exactly that format, or an outbound route pattern matches it in the trunk's route group (asterisk -rx "dialplan show <number>@from-trunk-<trunk>-route").

Browser or app calls have no audio

Audio works on the server's LAN but not from a phone on mobile data, or calls through the relay are silent: check the external IP under PBX Settings, the certificate (Security → Certificates — TURNS fails silently with a self-signed one) and relay-ip in /etc/turnserver.conf. Full checklist: WebRTC, NAT and TURN.

Capturing SIP

sudo timeout 120 tcpdump -ni any -s0 -w /root/sip.pcap "portrange 5060-5062"   # make the call meanwhile
sudo tcpdump -nr /root/sip.pcap -A | grep -E "^(INVITE|BYE|CANCEL|SIP/2.0) |^(From|To|Reason):"

The INVITE line shows the number a trunk sends, From the caller ID, and a 4xx/5xx response or Reason header why the other side rejected a call (e.g. 403 No Rates Found = the carrier has no route for that number). Open the file in Wireshark for RTP/audio analysis.

Phones stop registering after a wrong password

fail2ban bans the address after repeated failures. Check fail2ban-client status asterisk, unban with fail2ban-client set asterisk unbanip <ip> and add internal networks to the ignore list on the fail2ban page.

The mobile app does not ring

A call to an extension rings its mobile app only while the app is registered (or, with push set up under System → Push, after the push wakes it). Check the registration:

asterisk -rx "pjsip show contacts" | grep <ext>-mob-webrtc
grep '<ext>-mob-webrtc' /var/log/asterisk/security.log | tail

No contact and no recent SuccessfulAuth: the app is not connected. Without push the call ends at once (CDR NO ANSWER, last application Hangup).
The app refreshes its registration every 2 minutes. A ChallengeSent that is never followed by SuccessfulAuth means the app's SIP engine stopped answering; Android 1.0.65–1.0.69 could do this after a video call. 1.0.70 restarts the engine by itself within about 2 minutes; on an older version close the app (Force stop) and open it again.
Xiaomi and some other phones also need Autostart allowed and battery saving set to No restrictions for the app.

No notification for a new voicemail in the app

The notification needs the Android app 1.0.63 or newer (older versions ignore it) and, while the app is not connected, push set up under System → Push. Every new message writes one line saying what happened:

journalctl -t aipbx-voicemail -n 20
# new voicemail for 1001: app not connected; push to 1 device(s)

"push off" means push is not set up, "push to 0 device(s)" that the extension has no registered phone (open the app once after signing in), and "failed: ..." carries Firebase's error.

System Update fails with "Code was modified by hand"

aipbx-update refuses to update when files under /opt/aipbx were changed. Installations on 1.34.0 – 1.34.2 hit this without anyone editing anything: their installer made web/bin/aipbx_ops.php executable, and the updater of those versions counts that as a change. Restore the file once, then update as usual:

sudo git -C /opt/aipbx checkout -- web/bin/aipbx_ops.php
sudo aipbx-update

From 1.50.2 on the updater ignores file mode changes. For any other file listed by the error, keep your change outside the code (portal, /etc/ai-pbx.env, *_custom.conf) and restore the file the same way.

Useful commands

asterisk -rx "pjsip show contacts"         # registered phones and trunk reachability
asterisk -rx "pjsip show endpoint <name>"  # endpoint settings
asterisk -rx "core show channels"          # active calls
tail -f /var/log/asterisk/messages.log
systemctl status asterisk apache2 nginx mariadb coturn aipbx-chat