Set up a SIP trunk on FreePBX

Before you start

FreePBX is a graphical interface built on top of Asterisk: underneath it runs the same engine, so the values are identical to those in the guide to setting up the trunk on Asterisk, except that you enter them in a form instead of in pjsip.conf. The menu items mentioned here are those of FreePBX 15, 16 and 17; in other versions they may move slightly, but their meaning does not change.

Get these things ready:

• A SIP account dedicated to the PBX, created in the portal under SIP accounts, with its username and password. If you do not have access yet, sign up to the portal.
• One or more verified caller IDs: numbers bought on Vohippo already are, others are verified in the portal.
• Administrator access to the FreePBX web interface.
• The office's public IP address and internal network, if FreePBX sits behind a router.

For an office with six extensions, for example, one account with six channels is enough: channels are set on the account with «Simultaneous outbound calls» (from 1 to 1000, each extra channel €0.50 a month), and the limit only applies to outbound calls. What calls cost is shown in the rates list, billed per second with no connection fee.

1. Create the trunk

Connectivity → Trunks → Add Trunk → Add SIP (chan_pjsip). On the General tab give the trunk a name, then move to the pjsip Settings tab.

• Username: the SIP account username shown in the portal
• Secret: the password of the same account
• SIP Server: sip.vohippo.com — SIP Server Port: 5060
• Authentication: Outbound — Registration: Send
• Context: from-trunk (the one FreePBX uses for inbound calls)

On the General tab, the Trunk Name field is just a label: call it Vohippo, for instance, so you recognise it in the routes. The Maximum Channels field can stay empty, because the real limit is the one on the account in the portal; if you fill it in, make it equal to «Simultaneous outbound calls», otherwise FreePBX will refuse calls the platform would accept.

Authentication: Outbound means FreePBX authenticates towards us, not the other way round. Registration: Send makes FreePBX register with our server: it is essential for receiving calls, because the registration tells us which public address the PBX is at. The transport to use is UDP on port 5060.

2. Advanced settings

On the same tab, Advanced section: these are the items that make the difference between a clean call and one with one-way audio.

• Codecs: only alaw, ulaw and optionally g722
• DTMF Mode: RFC 4733
• Direct Media: No
• Rewrite Contact: Yes — Force rport: Yes — RTP Symmetric: Yes

Why these values

The codecs the platform accepts are G.711 a-law, G.711 µ-law and G.722: untick everything else and put alaw first. With other codecs, such as G.729 or Opus, the call cannot be negotiated. RFC 4733 is how the platform receives keypad tones: you need it for customer service menus and door entry codes. Details and bandwidth figures are in the VoIP codecs guide.

Direct Media: No keeps the audio on the PBX at all times. The next three options tell FreePBX to reply to the address and port the packets actually come from, ignoring the ones written in the SIP messages: this is what you need when there is a NAT router in between, which is almost always.

The other items on the tab

Leave Qualify Frequency at a value such as 60 seconds: FreePBX checks every minute that our server is answering. The registration expiry time can stay at the suggested value; the platform default is 600 seconds, and with a router that closes UDP sessions early a value between 300 and 600 seconds is advisable. You do not need to fill in Outbound Proxy.

3. Outbound route

Connectivity → Outbound Routes. The route decides which numbers go out over this trunk.

• Trunk Sequence: the trunk you have just created
• Dial Patterns: empty prefix and a match on X. to send everything, or patterns by country
• Route CID: your verified number, if you do not already set it in the portal

The X. pattern sends any dialled number to the trunk. Your users dial as on an ordinary phone: for Italy in national format (06 1234 5678, 345 218 0937), and for other countries with 00 or + in front. A number without an international prefix is read as belonging to the country of the mobile number you verified, so a foreign number dialled without 00 would be treated as a national one.

If you want to be stricter, create separate patterns: for instance one for Italian numbers starting with 0 or 3, and nothing for abroad. It is a good idea for an office that never calls outside its own country, together with the enabled destinations on the account in the portal («Only the selected destinations»): two barriers are better than one.

4. Inbound route

Connectivity → Inbound Routes: this is where you decide where the numbers you have bought ring.

• DID Number: the number as it arrives from the platform
• Set Destination: an extension, a ring group or an IVR
• If you are not sure of the DID format, leave the field empty and use the route as a catch-all until you see it in the logs

In the portal, the number needs a routing flow with a «Ring SIP accounts» step pointing to the trunk account: that is how the call reaches FreePBX. A number without a flow ends up as «Calls rejected». Building the steps is explained in the guide on how to set up an inbound number, and you can search for available numbers among the virtual numbers in 232 Italian cities.

Ring groups, IVR, queues and time conditions are FreePBX features, not platform features: Vohippo delivers the call to the PBX, and FreePBX decides what to do with it. To see the format in which the call arrives, test with the catch-all route and look at the log under Reports → Asterisk Logfiles, or from the console with pjsip set logger on.

Caller ID

Every outbound call must present a verified caller ID: if the number is not among your caller IDs, the call is rejected and the call reports show «Caller ID not allowed». You cannot call out anonymously. There are two ways to go.

• Fixed caller ID on the account in the portal: it always wins, whatever FreePBX sends. It is the simplest choice if everyone calls out with the same number.
• «Taken from the call (must be one of your caller IDs)»: the platform reads the number from the call, in this order: P-Asserted-Identity, Remote-Party-ID, From. This way you can give different departments different numbers, as long as they are all verified.

In FreePBX the number can be set in several places: on the extension (Outbound CID), on the route (Route CID) and on the trunk (Outbound CallerID). Write it with + or 00 in front, for example +39 06 1234 5678, or in national format. FreePBX puts the caller ID in the From; if the trunk's Advanced tab has an option to send P-Asserted-Identity as well, you can turn it on, but it is not required: the account is recognised from its credentials, and the number in the From is enough.

Numbers bought on Vohippo are already caller IDs; a number from another carrier is verified by SMS, WhatsApp or voice call and costs €0.02 per answered call. All the rules are in the guide on caller ID.

NAT, firewall and ports

An office FreePBX almost always sits behind a router. To avoid one-way audio, tell FreePBX its public address: Settings → Asterisk SIP Settings, in the NAT settings section.

1. In External Address enter the office's public IP address (or use the detect button).
2. In Local Networks add the internal network, for example 192.168.1.0/24.
3. Save, apply the configuration and restart Asterisk if asked to.

Then, on the router, turn off SIP ALG: it rewrites SIP packets and causes dropped registrations and one-way audio. Our server uses port 5060 UDP for SIP and ports 10000-20000 UDP for audio; FreePBX's own ports are on the same page, under the RTP settings.

If you use the FreePBX Firewall module, add sip.vohippo.com to the trusted networks, otherwise the firewall may block inbound calls. The rest (port forwarding, keepalives, when you really need to open ports) is in the guide on NAT, firewalls and ports.

Check that it works

After saving and pressing Apply Config, run the tests in this order.

1. Reports → Asterisk Info, Registries section: the trunk must show as Registered. The account must also appear as registered in the portal.
2. Call a mobile from an extension: you must hear and be heard.
3. Call your virtual number from a mobile: it must reach the inbound route's destination.
4. During a call to a service with a menu, press a few keys to check the tones.
5. Check the call reports in the portal: every test must appear with its outcome.

If you prefer the console, the commands are the Asterisk ones: pjsip show registrations and pjsip set logger on. In the portal you also have the account's SIP log for the last 7 days.

If something goes wrong

The most frequent problems, in order of likelihood.

The platform firewall blocks an address after 5 authentication errors in 10 minutes, with progressively longer blocks: so whenever you change the password in the portal, update it in the trunk straight away.

Frequently asked questions