PerfexVoIP setup guide

What you need

CRM

Perfex CRM 3.0 or newer

PHP

8.0 or newer

Database

MySQL 5.7 or MariaDB 10.3 and newer

PBX

Asterisk 13+ for AMI, or Asterisk 12+ for ARI (FreePBX and Issabel expose both)

PHP extensions

json, pdo_mysql, curl, sockets, openssl, mbstring (pcntl only for the background daemons)

Network

The CRM server must reach the PBX on AMI (5038) or ARI (8088), typically over a private network or VPN

Installation

1. 1. Install the module in Perfex CRM

   Upload the module zip under Setup → Modules → Upload Module and activate PerfexVoIP, or unzip it into application/modules and activate it from the same screen. The first activation takes 15–30 seconds while it creates its tables and default options.

2. 2. Connect your PBX

   Open PerfexVoIP → Settings, fill in either the ARI or AMI connection (or both — the transport selector accepts auto, ari or ami) and click Test connection. ARI is the newer interface and is recommended when your Asterisk supports it.

   [perfexvoip]
   secret = A_STRONG_RANDOM_PASSWORD
   deny   = 0.0.0.0/0.0.0.0
   permit = 127.0.0.1/255.255.255.255
   read   = system,call,user,cdr,dialplan,agent
   write  = system,call,user,originate

3. 3. Choose how call events reach the CRM

   Events can arrive three ways: the ARI events daemon (recommended, subscribes to Asterisk over WebSocket), a bridge worker that polls each PBX connection, or your dialplan posting events to the module's ingest endpoint — which is the option for shared hosting where no daemon can run. Screen-pops work either way: the in-page notifier uses a WebSocket when one is available and falls back to HTTP polling automatically.

   [Service]
   Type=simple
   User=www-data
   ExecStart=/usr/bin/php /var/www/perfex/application/modules/perfexvoip/ari_events_daemon.php /var/www/perfex
   Restart=always
   RestartSec=5

4. 4. Map extensions to staff and set permissions

   Under PerfexVoIP → Peers, add each SIP extension with its dial string and context and bind it to the staff who use it. This is what matches an incoming call to the right person and keeps click-to-call limited to a staff member's own extensions. Then grant the module's capabilities per role: view_own (own calls and the notifier), view_all (everyone's calls) and click2call.

5. 5. Turn on what you need

   Optional behaviour lives in Settings: create a lead automatically from an unknown inbound number, blacklist nuisance callers after a threshold, and register several PBX servers under Connections with one bridge worker per connection.

Security notes

• Use 24+ character random secrets for the AMI and ARI users.
• Never expose AMI (5038) or ARI (8088) to the public internet — bind them to localhost or a private network.
• Saved PBX credentials are masked in the settings screen, are never sent to the browser and are never written to logs.
• Click-to-call and hangup are restricted to the extensions assigned to the signed-in staff member.

If something does not work

The ARI connection test fails

Check the credentials in ari.conf. Verifying by hand: curl -u user:pass http://127.0.0.1:8088/ari/asterisk/info — an Unauthorized response means the password does not match.

The AMI connection test fails

nc -v 127.0.0.1 5038 should print the AMI banner. Connection refused means manager.conf is not enabled or a firewall is in the way.

Calls are placed but no events appear

Follow the daemon log (journalctl -u perfexvoip-ari-events -f). A rejected handshake usually means Asterisk's HTTP server is off or the ARI application name is wrong.

No screen-pop for the agent

Confirm the staff role has view_own, that the browser has been granted notification permission, and that the notifier icon is not red — a red icon means the WebSocket is down, and the module keeps polling instead.

A straightforward install on a server you already control usually takes under an hour. The package ships with the full installation guide, a testing guide and the systemd units quoted above; we help with PBX connection settings as part of onboarding.