FusionPBX Softphone Provisioning: From Device Record to First Call in Under 5 Minutes

You are onboarding 50 new users for a client. You are copy-pasting SIP credentials from the FusionPBX admin panel into emails, one extension at a time. Within the hour, three support tickets come in: a typo in the proxy address, a password with an ambiguous character, a user who pasted the credentials into the wrong field. This is Tuesday. FusionPBX softphone provisioning eliminates this entire category of pain, but if you have tried to set it up before, you probably noticed a gap: the documentation and tooling assume hardware desk phones with MAC addresses. Softphones are treated as an afterthought.

This guide closes that gap. By the end, you will know how to configure the FusionPBX provisioning engine specifically for softphones, lock it down with HTTP authentication, deliver QR codes to end users for zero-touch onboarding, wire in mobile push notifications so iOS and Android users never miss a call, and scale the entire workflow across dozens or hundreds of tenants with no manual per-user steps. Everything here is written for ITSPs, MSPs, and PBX administrators who already know their way around SIP, the Linux CLI, and the FusionPBX admin UI.

Why Softphone Provisioning Is Different from Hardware Phones¶

Hardware phone provisioning on FusionPBX follows a well-worn path. You plug in a Yealink or Polycom, it grabs an IP via DHCP, DHCP option 66 points it at your provisioning server, the phone sends its MAC address, and FusionPBX returns the matching configuration file. The MAC address is the anchor for the entire workflow: it uniquely identifies the device, it is printed on a sticker on the back of the phone, and it never changes.

Softphones have none of this. There is no MAC address. There is no DHCP option 66 because the softphone runs on a laptop, tablet, or mobile phone you do not control. There is no reboot cycle to trigger re-provisioning. The device lives outside your network, behind consumer NAT, on cellular connections, on Wi-Fi at a coffee shop.

The delivery mechanism for softphone provisioning is therefore the provisioning URL itself. Instead of the phone discovering the server through network-layer configuration, you hand the softphone a URL. FusionPBX uses the format:

https://<domain>/app/provision/?mac=<device-key>

The mac parameter is misleadingly named for softphones. It does not need to be a MAC address. You can set it to the extension number, a UUID, or any unique string. For softphone deployments, the extension number is the most common choice because it is human-readable and easy to troubleshoot.

Understanding these differences is essential because they dictate every decision downstream: how you secure the provisioning endpoint, how you deliver credentials, and how you handle incoming calls on mobile devices.

Step 1 — Prepare the Provisioning Engine¶

Before creating any device records, the provisioning engine itself needs to be enabled and secured. FusionPBX ships with provisioning disabled by default, and for good reason: the provisioning URL is unauthenticated out of the box. Leaving it open exposes SIP credentials to anyone who can guess or enumerate device keys.

Enable Provisioning in Default Settings¶

Navigate to Advanced > Default Settings and scroll to the Provision category. Find provision_enabled and set its value to true. This single toggle activates the provisioning endpoint at /app/provision/.

Next, confirm that your provisioning base URL resolves over HTTPS. Open the URL in a browser and verify you get a response. If you get a TLS warning or the connection fails, fix your certificate first. A valid TLS certificate is non-negotiable for mobile softphone provisioning. Both iOS and Android will refuse to fetch configuration over an untrusted HTTPS connection, and plain HTTP should never be used for transmitting SIP credentials.

Choose Your Security Model: HTTP Auth vs. CIDR¶

FusionPBX offers two built-in mechanisms to protect the provisioning endpoint, and you should use at least one of them. In many deployments, combining both with HTTPS-only enforcement at the web server layer provides the strongest posture.

HTTP Digest Authentication is the more flexible option. Enable it by setting provision_http_auth_enabled to true in Default Settings. Then configure provision_http_auth_username and provision_http_auth_password. When enabled, any request to the provisioning URL must include a valid HTTP Digest Authentication header. The softphone app handles this transparently once the credentials are configured — the user never sees a password prompt.

For ITSPs, the best practice is to set per-tenant HTTP auth credentials. Override the global defaults at the domain level (each FusionPBX domain can have its own Default Settings overrides), so that Tenant A's provisioning credentials are different from Tenant B's. This limits blast radius if credentials leak.

CIDR Restriction (provision_cidr) locks the provisioning endpoint to specific IP ranges. This works well for corporate deployments where all users are behind a known NAT gateway. For ITSPs with consumer or remote users on variable IPs, CIDR restriction is generally impractical as the sole security mechanism, but it can serve as an additional layer for admin-side access.

As a third layer, enforce HTTPS-only access at the nginx or Apache level. Redirect all HTTP requests on port 80 to HTTPS, and consider adding HSTS headers. This prevents credential interception even if a client misconfigures the provisioning URL with http:// instead of https://.

Verify the Provision Template Directory¶

Provisioning templates live at /var/www/fusionpbx/resources/templates/provision/. Confirm that your web server can serve files from this path and that the directory contains subdirectories for your target softphone brands. Check file permissions: the web server user (typically www-data on Debian/Ubuntu) must have read access to all template files.

Verify the template path serves correctly by testing a known device key in a browser. If you get a 404, the template directory is misconfigured or the provisioning app cannot find a matching template for the device profile you selected.

Step 2 — Create a Softphone Device Record¶

With the provisioning engine enabled and secured, you can now create device records for individual softphones. Each device record maps a unique key to a SIP extension and a provisioning template.

Navigating to Devices¶

In the FusionPBX admin UI, go to Accounts > Devices > Add Device. You will see several fields:

MAC / Device Key: For softphones, enter the extension number (e.g., 1001) or a UUID. This value becomes the ?mac= parameter in the provisioning URL. Using the extension number is the simplest approach and makes troubleshooting straightforward.

Profile / Template: Select the provisioning template that matches your softphone. This determines the format and content of the configuration file returned to the app.

Line 1 — Username / Password: Map these to the SIP extension credentials. You can pre-fill them from the extension record.

Description: Use something meaningful like "John Smith — SessionTalk iOS" so you can identify devices at a glance in the admin UI.

Assigning the Correct Provisioning Template¶

The out-of-box provisioning templates in FusionPBX are hardware-centric: Yealink, Polycom, Grandstream, Fanvil. For softphones, you need a template designed for your specific app. Some softphones have official FusionPBX provisioning documentation. Others rely on community templates or dedicated FusionPBX app modules.

A provisioning template defines the full SIP configuration the softphone receives: SIP server address, SIP port, transport protocol (TLS, TCP, or UDP), SRTP preference, codec priority list, voicemail access URI, STUN/TURN server settings, and display name. The template uses FusionPBX variables that get replaced with the actual values from the device record at render time.

Verifying Template Rendering with the Provision Editor¶

Before deploying a provisioning URL to end users, always verify that the template renders correctly against the device record. A misconfigured template or a missing variable will produce a broken configuration file that either fails silently or causes registration errors that are difficult to diagnose from the user's side.

Navigate to Advanced > Provision Editor in the FusionPBX admin UI. Select the softphone template you assigned to your device record and open the primary configuration file.

Every FusionPBX variable in a successfully rendered template is replaced with its concrete value. In a failed variable substitution, raw variable tags pass through unchanged — strings like {$line_1_password} appear literally in the configuration, causing authentication failures. Common causes: variable name misspelled in the template, field left blank in the device record, or the variable belongs to a Default Settings category not configured for this domain.

Testing before deployment: fetch the provisioning URL with curl and scan the output for unresolved {$...} tokens. If you find any, go back to the device record and domain Default Settings to populate the missing values. Make this verification a standard step before distributing QR codes to any tenant.

Generating the Provisioning URL¶

Once the device record is saved, the provisioning URL is deterministic. For example, if your PBX domain is pbx.example.com and you used extension 1001 as the device key:

https://pbx.example.com/app/provision/?mac=1001

When a softphone fetches this URL (with valid HTTP auth credentials, if enabled), FusionPBX looks up the device record matching mac=1001, loads the associated provisioning template, substitutes all variables, and returns the rendered configuration in the format the softphone expects — typically XML, JSON, or a proprietary config format depending on the template.

Step 3 — QR Code Delivery: Zero-Touch Onboarding¶

QR code provisioning is where the operational efficiency gains become tangible. Instead of emailing credentials or walking users through manual configuration screens, you hand them a QR code. The softphone app scans it, fetches the provisioning URL, pulls the configuration, registers with the SIP server, and the user is making calls.

The QR Code Workflow¶

FusionPBX can render a QR code directly from a device record. In the admin UI, navigate to Accounts > Devices, select the device, and click the QR code icon. The generated QR code encodes the provisioning URL (and optionally the HTTP auth credentials, depending on the softphone and template).

Admin creates device record — 30 seconds in the FusionPBX UI

Admin shares QR code — via email, Slack, a customer portal, or even printed on a welcome sheet

User downloads the softphone app from the App Store or Google Play

User opens the app and taps "Scan QR Code"

App fetches the provisioning URL, pulls the full SIP configuration, registers with the server

First call ready — typically under 60 seconds from scan to dial tone

This is what zero-touch provisioning looks like for softphones. No credential emails. No ticket-based setup. No support call. The user scans a code and they are live.

Re-Provisioning and Configuration Updates¶

The provisioning URL is not a one-time-use mechanism. Modern softphones re-fetch their configuration on a configurable interval. This means you can push changes to codec preferences, server addresses, transport settings, or any other configuration parameter by updating the provisioning template or device record. The next time the softphone checks in, it picks up the new configuration automatically.

This is powerful for ITSPs managing hundreds or thousands of endpoints. Need to migrate users from UDP to TLS transport? Update the template, and every device re-provisions on its next check-in. No per-user touchpoints required.

Step 4 — Mobile Push Notifications: The Missing Piece¶

You can have provisioning working perfectly — QR codes scanning cleanly, SIP registration completing in seconds — and still have a broken mobile deployment if you do not address push notifications. This is the single most common failure mode for ITSP softphone rollouts, and it has nothing to do with FusionPBX configuration.

Why Push Notifications Are Non-Negotiable on Mobile¶

iOS aggressively suspends background apps to preserve battery life. When a softphone is not in the foreground, iOS kills its network connections within minutes. The app cannot maintain a persistent SIP registration. Without a push notification mechanism, the SIP server has no way to reach the device when an incoming call arrives. The call goes to voicemail, the user never knows it happened, and the support ticket says the softphone does not ring.

Android is more lenient but has been tightening background restrictions with every release. Starting with Android 12 and continuing through subsequent versions, background SIP registration is increasingly unreliable without push notifications. Treating push as optional on Android is a mistake for production deployments.

How SIP Push Notifications Work¶

The push notification flow for mobile softphones involves four actors: the softphone app, the SIP server (FreeSwitch, in FusionPBX's case), a push gateway, and Apple Push Notification Service (APNS) or Firebase Cloud Messaging (FCM).

Registration: The softphone registers with the SIP server as usual. Simultaneously, it registers its device token (an APNS or FCM token) with the push gateway.

Incoming call: FreeSwitch receives an inbound INVITE for the extension. It notifies the push gateway that a call is waiting.

Push delivery: The push gateway sends an APNS push (on iOS) or FCM push (on Android) to wake the device.

Call completion: The device wakes, the softphone re-registers with the SIP server, and FreeSwitch delivers the call. This entire sequence happens in under two seconds on a good network connection.

Two Implementation Approaches¶

There are fundamentally two ways to implement push notifications for softphones on FusionPBX:

Approach A: Softphone-Managed Push Server. The softphone vendor hosts and operates the push gateway. SessionTalk uses a cloud-managed push infrastructure that registers APNS and FCM tokens as part of the provisioning profile. With this approach, FusionPBX needs zero extra configuration for push — the softphone vendor handles everything between the SIP server and the mobile OS push services.

Approach B: Self-Hosted Push Gateway. You deploy a push gateway alongside FusionPBX. Options include Flexisip (a mature SIP proxy with built-in APNS and FCM support) and Kamailio with push modules. This gives you full control over the push infrastructure but adds significant operational burden: managing APNS certificates, FCM server keys, gateway uptime, and the SIP integration between FreeSwitch and the gateway.

For most ITSPs, Approach A is the right choice. Push infrastructure is operationally complex, and the failure modes are subtle (expired certificates, rate limiting, token invalidation). Outsourcing it to the softphone vendor lets you focus on your core business: selling and managing voice services.

The SessionTalk Approach¶

SessionTalk's cloud provisioning handles APNS and FCM registration as part of the provisioning profile itself. When a user provisions their softphone via the FusionPBX device record, push notification registration happens transparently — no extra configuration steps, no separate push gateway to deploy, no APNS certificates to manage. The fusionpbx-app-sessiontalk integration module wires this into the FusionPBX admin UI natively, so push is simply part of provisioning rather than a separate operational concern.

Step 5 — Multi-Tenant Provisioning for ITSPs and MSPs¶

If you are an ITSP or MSP running FusionPBX, you are almost certainly running a multi-tenant deployment. Each customer gets their own FusionPBX domain, their own extensions, their own dial plans. The good news is that FusionPBX's provisioning engine is domain-aware by default, which means most of the multi-tenant provisioning workflow works without extra configuration.

Domain-Scoped Provisioning URLs¶

FusionPBX's domain-based multi-tenancy means provisioning URLs are automatically scoped to the correct domain. When a device record exists under customer1.pbx.example.com, the provisioning URL returns configuration specific to that domain — the SIP server address, registrar, outbound proxy, and all other domain-level settings are resolved for that tenant.

For DNS architecture, subdomain-based tenancy is the recommended approach. It scales cleanly, simplifies TLS certificate management with wildcard certs, and makes provisioning URLs self-documenting.

Per-Tenant Security¶

As mentioned in the security section, you should override the global HTTP auth credentials at the domain level. Navigate to the domain's settings, find the Provision category, and set domain-specific values for provision_http_auth_username and provision_http_auth_password. This ensures that a credential leak in one tenant does not compromise provisioning for all tenants.

You can also set per-tenant provisioning templates if different customers use different softphone brands or require different codec configurations. Domain-level Default Settings overrides take precedence over global defaults, giving you fine-grained control per tenant.

Bulk Device Creation¶

Creating device records one at a time in the admin UI is fine for a 10-user customer. For a 500-user rollout, you need bulk import. FusionPBX supports CSV-based device import. The typical column schema includes: mac (the device key), template (the provisioning template name), line_1_user_id (the SIP username), line_1_auth_id, line_1_password, and description.

Prepare the CSV, navigate to Accounts > Devices, and use the import function. For updating existing records, the Bulk Account Settings tool under Advanced > Bulk Account Settings is more appropriate.

Automation with WHMCS and ictVoIP Billing¶

For ITSPs who want fully automated provisioning tied to their billing system, ictVoIP Billing bridges WHMCS and FusionPBX with RESTful APIs. The provisioning flow becomes: customer places order in WHMCS, ictVoIP Billing's FusionPBX module creates the tenant domain, provisions extensions, generates device records, and can email provisioning URLs or QR codes automatically. No admin intervention required for standard orders.

FusionPBX Softphone Provisioning Support: A Comparison¶

Not every softphone integrates with the FusionPBX provisioning engine equally. The depth of integration varies from dedicated admin UI modules to manual XML template editing. For ITSPs deploying at scale, the differentiators that matter most are: native FusionPBX module support, managed push notification infrastructure, and white-label capability.

SessionTalk offers FusionPBX provisioning via a dedicated app module, QR code support, cloud-managed APNS/FCM push, white-label capability, and a native FusionPBX app on iOS, Android, macOS, and Windows. Acrobits/Groundwire uses a community template with SIPIS-based push. Zoiper has official OEM portal provisioning with QR code support. Bria (CounterPath) uses a manual XML template with CounterPath cloud push. Ringotel provisions via an iframe portal.

Managed Push means the softphone vendor hosts and operates the push notification gateway. Native FusionPBX App means a dedicated module in the FusionPBX admin UI. White Label is critical for ITSPs who want their softphone to carry their own brand. For ITSPs evaluating softphones for FusionPBX deployment, the combination of a native admin module, managed push, and accessible white labeling makes the selection straightforward.

Troubleshooting: Common FusionPBX Provisioning Errors¶

When provisioning fails, it almost always falls into one of a handful of well-defined categories.

401 Unauthorized on provision URL: HTTP Auth credentials not configured on client side. Add provision_http_auth_username and provision_http_auth_password to the device record or softphone app config.

403 Forbidden: CIDR restriction blocking client IP. Add the client's IP range to provision_cidr in Default Settings, or disable CIDR restriction if using HTTP Auth as primary security.

404 Not Found on provisioning URL: Provisioning not enabled, or device key mismatch. Set provision_enabled to true in Default Settings; verify device key matches the ?mac= parameter exactly.

App registers but misses incoming calls: Push notifications not configured or broken. Verify softphone push credentials; check APNS/FCM certificate expiration.

Config fetched but wrong codec or server: Template variable not resolving for domain. Check domain-level Default Settings overrides; test template rendering in Provision Editor.

TLS handshake failure on iOS or Android: Self-signed certificate on provisioning endpoint. Install a valid Let's Encrypt certificate; iOS and Android reject self-signed certs.

Re-provision loop / repeated config fetches: Provision check interval too aggressive. Increase check_expiry or equivalent interval value in the softphone template.

Always test the provisioning URL in a browser first. If it returns valid XML or JSON, the server side is working. If it returns an error, you have a server-side configuration problem.

SessionTalk + FusionPBX: The Integrated Path¶

The fusionpbx-app-sessiontalk module installs as a native FusionPBX application, adding a SessionTalk menu to the admin UI and handling APNS/FCM registration transparently.

Installation¶

cd /var/www/fusionpbx/app
git clone https://github.com/demonspork/fusionpbx-app-sessiontalk
mv fusionpbx-app-sessiontalk sessiontalk

Create template directories:

cd /var/www/fusionpbx/resources/templates/provision
mkdir -p sessiontalk/windows sessiontalk/android sessiontalk/ios

Set permissions:

chown -R www-data:www-data /var/www/fusionpbx/app/sessiontalk /var/www/fusionpbx/resources/templates/provision/sessiontalk

Navigate to Advanced > Upgrade and run Schema Defaults, App Defaults, Menu Defaults, and Permission Defaults. Log out and back in. The SessionTalk menu appears in the admin UI.

Configuration¶

In the SessionTalk cloud dashboard, set the External Provisioning URL to:

https://<your-pbx>/app/sessiontalk/provision.php

Once the External Provisioning URL is saved and the upgrade defaults have been applied, the SessionTalk menu will appear in the FusionPBX admin sidebar. This menu provides a dedicated interface for creating and managing SessionTalk device records without needing to work through the generic Devices page. When you create a device record from the SessionTalk menu, the module automatically generates a provisioning URL pre-configured for SessionTalk's cloud push infrastructure — APNS and FCM token registration is embedded in the provisioning profile, so push notifications work out of the box with no additional gateway setup.

To verify the integration is working, create a test device record from the SessionTalk menu, fetch its provisioning URL with curl or a browser, and confirm the rendered output contains valid SIP credentials and push configuration parameters. If the SessionTalk menu does not appear after running the upgrade defaults, log out completely, clear your browser cache, and log back in — FusionPBX caches menu structures aggressively and a stale session will hide newly installed modules.

Conclusion¶

An ITSP implementing this workflow can onboard a new softphone user in under five minutes: create the device record, generate the QR code, send it to the user. No credential emails. No copy-paste errors. No support tickets about typos.

The gap between a softphone that works and a softphone that works reliably at ITSP scale is almost entirely a provisioning and push notification problem. FusionPBX's provisioning engine handles the first half. Managed push infrastructure from the softphone vendor handles the second.

SessionTalk is built specifically for this workflow. The dedicated FusionPBX app module, cloud-managed push notifications, and white-label capability mean you get the full provisioning pipeline without bolting together community templates and self-hosted push gateways. Start your free trial of SessionTalk today. Have your first FusionPBX extension provisioned in minutes — no manual config, no credential emails, no missed calls.