How to Connect a Softphone to an Asterisk PBX

Connecting a softphone to Asterisk takes five values: the server's address, the SIP port and transport, the extension number, and the extension's password. Enter them in the softphone's account or registration screen, save, and confirm the registration with pjsip show contacts on the Asterisk console. If the softphone is on a different network from the server, add NAT handling on both ends. The steps below apply to any SIP softphone; the last section lists the exact fields in SIPdia for macOS and iPhone.

Step 1: Collect the extension details

Ask the Asterisk administrator, or read pjsip.conf yourself, for:

Value	Where it comes from in Asterisk
Server address	The hostname or IP of the machine running Asterisk
Port and transport	The bind and protocol of the transport section, typically UDP 5060 or TLS 5061
Extension number	The endpoint name, for example 1001
Password	The password= of the matching auth section
Auth username	The username= of the auth section, only if it differs from the endpoint name
Codecs	The allow= lines of the endpoint

If the PBX is managed through FreePBX or Issabel, these are the extension number, the secret, and the port shown under Asterisk SIP Settings. How SIP extensions work in Asterisk explains the endpoint, auth and AOR objects behind these values.

Step 2: Map the values to the softphone's fields

Softphones use different labels for the same things. The usual mapping:

1. Server, registrar, SIP server, domain, or host: the Asterisk address, with the port if it is not the default.
2. Transport: UDP, TCP or TLS, matching the Asterisk transport. Pick UDP unless the server has a TLS transport with a certificate from a public certificate authority.
3. Username, user ID, or account: the extension number.
4. Password or secret: the auth password.
5. Auth username or authentication ID: leave empty unless the auth section uses a different username.
6. Outbound proxy: leave empty for a plain Asterisk server.
7. Display name or caller ID name: the name to show on other phones. Asterisk may override it with the endpoint's callerid setting.

Save the account. Most softphones register immediately and show a status indicator, often a green dot or the word Registered.

Step 3: Make sure the network allows SIP and RTP

Between the softphone and the server, two kinds of traffic must pass:

• SIP signalling on the transport's port: UDP 5060 by default, TCP 5061 for TLS.
• RTP audio on UDP 10000 to 20000, the Asterisk default range from rtp.conf.

On the Mac, a softphone also needs the Local Network permission to reach a PBX on the office LAN. On any platform, a VPN is the safest way to reach a PBX from outside.

Step 4: Handle NAT on both sides

When the softphone sits behind a home router or on mobile data, both the softphone and Asterisk have to cope with address rewriting:

1. On the Asterisk endpoint, set rtp_symmetric=yes, force_rport=yes and rewrite_contact=yes. These tell Asterisk to answer to the address and port the softphone's packets actually came from. If Asterisk itself is behind NAT, also set external_media_address, external_signaling_address and local_net on the transport. See the Asterisk NAT documentation.
2. In the softphone, set a STUN server (RFC 5389) such as stun.l.google.com:19302 and turn on ICE (RFC 8445). STUN finds the public address; ICE tries every candidate path and uses the one that works.

Skip this step on a flat office LAN or a VPN where both ends see each other's real addresses.

Step 5: Match the codecs

Asterisk offers only the codecs in the endpoint's allow= lines, in that order. The softphone offers its own list. The call fails with No joint capabilities in the Asterisk log if the lists do not overlap. G.711 ulaw and alaw are included in standard Asterisk builds and supported by nearly every softphone, so allow at least one of them as a common baseline. Opus gives better quality on bad connections and is worth allowing when the Asterisk server has the codec module installed.

Step 6: Verify the registration

On the server:

asterisk -rx "pjsip show contacts"
asterisk -rx "pjsip show endpoint 1001"

The contact should show the softphone's IP address and the status Avail after the first qualify. If it does not appear, watch the exchange:

asterisk -rvvv
pjsip set logger on

Normal registration is a REGISTER, a 401 Unauthorized challenge, a second REGISTER with credentials, and 200 OK. A 401 with no 200 OK means the password is wrong. Nothing at all means the request never arrived: check the port, transport and firewall. Work through SIP registration keeps failing if you get stuck.

Step 7: Place a test call

1. Dial a test extension. If the dialplan has an echo test (for example 600 running Echo()), you should hear your own voice, which proves two-way audio.
2. Dial another extension and check audio both ways.
3. Press keypad digits during a call. The Asterisk console shows DTMF events when the endpoint's dtmf_mode matches the softphone (RFC 4733, often labelled RFC 2833).
4. Call the softphone from another phone and confirm it rings.

SIPdia specifics

SIPdia uses the standard model above. The field names on its Account page are:

1. Server: the Asterisk hostname or IP, with :port if the transport is not on 5060 (UDP/TCP) or 5061 (TLS). Without a port, SIPdia does a DNS SRV lookup first.
2. Transport: UDP, TCP or TLS.
3. Username: the extension number.
4. Password: the auth password. It is stored in the Keychain.
5. Display name: the name shown to other extensions.
6. Advanced: Domain, Outbound proxy and Auth username stay empty for a plain Asterisk server. STUN server and ICE are the NAT settings from step 4. Encrypt audio is Off, Optional or Required; use Required with a TLS transport and media_encryption=sdes on the endpoint.
7. Click Save and Register on the Mac or Add and Register on iPhone. The dot next to the account turns green when registered.

SIPdia supports Opus, G.711 ulaw and G.711 alaw, so make sure the endpoint allows one of them. Forwarding and Do Not Disturb use the PBX feature codes under Settings > Feature Codes; if your Asterisk dialplan has no such codes, clear them. Note that SIPdia must be running to receive calls, because push notifications for incoming calls are not implemented. For a complete server-side example with transports, TLS and SRTP, read How to configure SIPdia with Asterisk (PJSIP).

Next steps

• How to configure SIPdia with Asterisk (PJSIP) for the full pjsip.conf example.
• SIPdia for macOS describes the Mac app.
• How SIP extensions work in Asterisk if you want to understand what the server is doing.