How to Configure SIPdia with FreePBX

SIPdia registers with FreePBX as a normal PJSIP extension. Create the extension under Applications > Extensions, copy its number and secret, check the PJSIP port and codecs under Settings > Asterisk SIP Settings, and click Apply Config. Then enter the server address, transport, extension number and secret on SIPdia's Account page. When the dot turns green, the extension is registered. The FreePBX steps below are general guidance based on the FreePBX documentation; the SIPdia fields are verified against the app.

What is FreePBX?

FreePBX is an open source web interface for the Asterisk PBX, maintained by Sangoma. It writes the Asterisk configuration for you, so extensions, trunks, ring groups and feature codes are managed from a browser instead of text files. FreePBX is not affiliated with SIPdia. The menu names below are from the FreePBX administration interface; the exact wording can differ slightly between versions, so refer to the FreePBX documentation for your release.

What you need before you start

• Administrator access to the FreePBX web interface.
• The FreePBX server's hostname or IP address as seen from the devices.
• A firewall path from the Mac or iPhone to the server for SIP and RTP (see below).

Create the extension in FreePBX

1. Sign in to the FreePBX administration page.
2. Go to Applications > Extensions.
3. Click Add Extension and choose Add New SIP [chan_pjsip] Extension. If you still see a chan_sip option, do not use it for new devices; chan_sip was removed in Asterisk 21.
4. On the General tab, enter:
   • User Extension: the number, for example 1001.
   • Display Name: the name shown on other phones.
   • Secret: FreePBX generates a long random secret. Keep it. This becomes SIPdia's Password.
5. Open the Advanced tab and review the settings that matter for a softphone:
   • Max Contacts: 1 for one device. Set 2 if the same extension should register from a Mac and an iPhone at the same time.
   • DTMF Signaling: RFC 4733 (also shown as RFC 2833 in some versions). SIPdia sends keypad tones as RTP events.
   • Direct Media: No. Audio then flows through Asterisk, which avoids one-way audio between networks.
   • Rewrite Contact, Force rport, RTP Symmetric: Yes. These handle devices behind NAT.
   • Transport: Auto, or pick the specific transport you want this extension to use.
   • Media Encryption: None for a plain setup, or SRTP via in-SDP for encrypted audio with TLS.
6. Click Submit, then click the red Apply Config button at the top of the page. Nothing takes effect until you apply.

Codecs

FreePBX sets codecs globally under Settings > Asterisk SIP Settings, on the General SIP Settings tab, under Audio Codecs. Make sure ulaw or alaw is enabled. If opus is listed and the codec module is installed, you can enable it too. SIPdia offers Opus, G.711 ulaw and G.711 alaw. It does not offer G.722 or G.729, so disabling those for the extension avoids pointless negotiation.

Find the PJSIP port

1. Go to Settings > Asterisk SIP Settings.
2. Open the SIP Settings [chan_pjsip] tab.
3. Look at the Transports section. Each enabled transport shows a protocol, an address and a port. The UDP transport is normally on 5060. TLS, if enabled, is normally on 5061.
4. Note the port for the transport you will use. If it is not 5060 (UDP or TCP) or 5061 (TLS), you will add it to the Server field in SIPdia as host:port.

The SIP port reference lists the standard ports if you are unsure what you are looking at.

NAT settings

On the General SIP Settings tab, under NAT Settings, set External Address to the server's public IP or hostname and add every LAN subnet under Local Networks. Without these, Asterisk puts a private IP in its SIP messages and remote devices get no audio. Also note the RTP Port Ranges, by default 10000 to 20000.

Feature codes

Open Admin > Feature Codes. The defaults match SIPdia's defaults:

Feature	Code
Call Forward All Activate / Deactivate	*72 / *73
Call Forward Busy Activate / Deactivate	*90 / *91
Call Forward No Answer Activate / Deactivate	*52 / *53
DND Activate / Deactivate	*78 / *79
My Voicemail	*97

If an administrator changed or disabled any of them, update the matching code in SIPdia under Settings > Feature Codes. Forwarding and Do Not Disturb are SIPdia Premium features.

Firewall and intrusion detection

FreePBX ships a firewall module under Connectivity > Firewall. Add the networks your devices connect from as Local or Trusted. Responsive Firewall, when enabled, lets unknown addresses attempt to register a few times and blocks them if they fail, which is useful for remote users. Intrusion detection (fail2ban) is found under Admin > System Admin > Intrusion Detection or as a tab in the Firewall module, depending on the version. Keep it on.

Between the devices and the server, allow the SIP port (UDP 5060 or your TLS port) and UDP 10000 to 20000 for RTP.

Enter the account in SIPdia

1. Open SIPdia, sign in, and go to Account.
2. Fill in:
   • Server: the FreePBX hostname or IP, with :port if the PJSIP port is not standard.
   • Transport: UDP for most LAN or VPN setups. TLS if you enabled the TLS transport with a public-CA certificate.
   • Username: the extension number, for example 1001.
   • Password: the extension's Secret.
   • Display name: your name.
3. Leave Domain, Outbound proxy and Auth username empty unless the administrator gave you separate values. FreePBX uses the extension number as the auth username.
4. If the extension uses SRTP, set Encrypt audio to Required. Otherwise leave it Off.
5. Click Save and Register (Mac) or Add and Register (iPhone).
6. Allow the microphone, local network and notification prompts.

Verify registration

The account's dot turns green when FreePBX accepts the registration. To confirm on the server:

1. In the FreePBX interface, open Reports > Asterisk Info and look at the Peers or Registries section. The extension should appear with the device's IP address.
2. Or on the server console:

asterisk -rx "pjsip show contacts"

The contact for 1001 should show Avail. If the dot in SIPdia stays red, read the error text under the account. For a 401 answer, check the secret. For a timeout, re-check the port and firewall. SIP registration keeps failing has a longer checklist.

Place a test call

1. On SIPdia's Phone page, dial *97 to reach your voicemail box. Enter a digit when asked. If the prompt reacts, keypad tones work.
2. Dial another extension. The other phone should ring and show your Display name.
3. Call your extension from another phone. On the Mac a floating window appears; on iPhone the call shows on the system call screen.
4. Check hold, transfer and audio in both directions.

Troubleshooting

• "Could not reach the server". Wrong port or transport, or a firewall in the way. On the Mac, allow SIPdia under System Settings > Privacy & Security > Local Network. For TLS, make sure port 5061 is open.
• Registration rejected. The secret or extension number does not match. See SIP 401 Unauthorized.
• One-way or no audio. Set the NAT fields under Asterisk SIP Settings, open UDP 10000 to 20000, and turn on STUN server and ICE in SIPdia when outside a VPN. See one-way audio.
• Blocked by Responsive Firewall. After several failed attempts the device's IP gets blocked for a while. Fix the credentials, then unblock the address in the Firewall module or wait.
• Logs. In SIPdia turn on Settings > General > Save detailed logs (Mac) or Settings > Save detailed logs (iPhone). On the server, asterisk -rvvv with pjsip set logger on shows the same exchange.

Security notes

Do not expose the SIP port to the internet without the firewall and intrusion detection enabled. Keep the generated secrets; do not replace them with short passwords. Prefer a VPN or an IP allow-list for remote users. For TLS, FreePBX can request a Let's Encrypt certificate under Admin > Certificate Management, which SIPdia accepts because it chains to a public CA.

Next steps

• SIPdia for macOS and SIPdia for iPhone.
• How to configure a SIP extension in FreePBX for the PBX side in more detail.
• How to configure SIPdia with Asterisk (PJSIP) to see the configuration that FreePBX generates.