Using FreePBX with Twilio Elastic SIP Trunking FreePBX works great with Twilio! We support it, it is what many of us use. There are a few tricks, especially for Origination, that are documented here, that one would probably not know about. This is a fairly long document, but that is because it is thorough, not difficult! Do not let the length intimidate you, this doc will walk you through each step. Definitions Origination Termination Termination Calls Configuring your trunk in the Twilio Portal Basic Configuration Authentication IP Access Control Lists Credential List Summary Configuring Your Twilio Trunk in FreePBX Creating the Trunk Creating the Outbound Route Summary Origination Calls Firewall Settings Configuring Your Origination Settings in the Twilio Portal Configuring Your Twilio Origination (inbound) Trunks in FreePBX IP Addresses for each region: Creating an Inbound Route for your Twilio Number Summary Definitions Origination Origination refers to calls from the PSTN, to a Twilio Number that are redirected to your SIP PBX. Termination Calls from your PBX to the PSTN, via Twilio. Termination Calls Configuring your trunk in the Twilio Portal First we need to configure your Trunk in the Twilio Portal. Basic Configuration Log in to your Twilio account, then in the upper left corner pulldown choose "Elastic SIP Trunking"
Now that you are in the Elastic SIP Trunking scree, click on Configure, Trunks, and click the "Create SIP Trunk" button in the upper right of the page as shown here: Give the trunk a "Friendly Name" to identify it, click "Create"
In the next screen, click on the "Termination" tab. Give your termination trunk a name. This, combined with.pstn.twilio.com will be the Host name you are going to configure in your trunk. In this case, I will be setting my host in FreePBX to "my_company.pstn.twilio.com". Note this name, you will need it when you configure your trunk in FreePBX. Authentication Now we need to add an Authentication method. You MUST configure at least one method, you MAY configure both for additional security. IP Access Control Lists This allows you to configure one or more IP Addresses your SIP Signaling traffic will come from. Only do this if your IP address is static. Click on "Create IP Access Control List" in the lower part of the Termination page:
You will then get this popup box. Give the list a name, then add the first IP address. You can add more addresses to the list later, in most cases you are done with 1 IP Address. Credential List If your IP address is not static, or you want an additional layer of security, you can create username(s) and and password for the account. Click "Create Credential List" in the authentication section of the page.
Note the strict password complexity requirements: Note the username and password your created, you will need this info when creating your trunk in FreePBX! Summary You should be done in the Twilio Portal now, and have a trunk that looks something like this: Configuring Your Twilio Trunk in FreePBX This part is very straightforward for Termination trunks. If you have done this before, very easy. One trick is making sure the outbound number is coded in E.164 format with a leading + sign. This will be demonstrated below. Creating the Trunk In the FreePBX GUI, go to Connectivity/Trunks/Add Trunk/SIP Trunk
Let's step through each of the settings in the screen above: Trunk Name: set as you see fit Outbound Caller ID: Set this with the full E.164 format (with leading + sign) of a Twilio Number or Verified number in your account if you have a Free Trial account. You can set this more freely in a paid account, but E.164 format with the + is recommended for best results. CID Options: For a free Trial account, set this to forced. For paid accounts, set this as you see fit. Dialed Number Maniuplation: is going to vary by system. The objective is to get the number into E.164 format (for example: 15005551212 for a US number, 441234567 for UK number, etc.) Outbound Dial Prefix: Set this to "+". This will add the + sign to the E.164 number. This is REQUIRED! Outgoing Trunk Name: Set this as you see fit Outgoing Host: Set this to the Terminating Trunk URI you created in the Twilio portal earlier Username. Set this to the username if you created credentials. Omit this line if you did not create credentials Secret. This is the password matching the username. Same as above. Type: Set this to peer as shown
Leave Incoming settings along for now Leave Registration String empty, we do not use that in our system. Save your trunk. Creating the Outbound Route Now we need to create an Outbound Route to send calls to the Trunk we created Go to Connectivity/Outbound Routes/Create Route Name is as you see fit Create Dial Patterns to match your system. The settings shown above will work with a US/Canada Dial plan (Dial 1 for a domestic call, 011 for an International Call. Note the rules in the trunk we created above will remove the 011 if you added that manipulation rule. Select the trunk you created as the Trunk sequence for Matched routes Submit Changes to save your route
Summary You should now be configured to send calls to the PSTN via Twilio. Remember, the objective is to get calls out in E.164 format. Depending on how you configured your dial plan, you may need to dial the 1 for US/Canada call, or something else outside US/Canada. Dialpans are beyond the scope of this document, though basic US/Canada usage are shown in the screen captures above. Origination Calls Origination calls are calls coming in from the PSTN through Twilio, to your PBX. Firewall Settings That is a bit beyond the scope of this document. You will need to open holes, and, if NAT is in use, forward to the internal address of your PBX the addresses shown in the section" IP Addresses for each region" Ports to be allowed/forwarded are: 5060/udp for signaling 10000-20000/udp for media Configuring Your Origination Settings in the Twilio Portal Go back to your trunk, we are now going to configure one item in the Origination tab: Configure your IP or machine name, prefixed with "sip:". For example: sip:1.2.3.4 if your IP is 1.2.3.4 or sip:freepbx.example.com if you prefer to use a machine name. For now, leave the Disaster Recovery empty unless you are familiar with TwiML. That is it for the Twilio Portal part of this. Configuring Your Twilio Origination (inbound) Trunks in FreePBX Twilio sends calls from 3-4 IP addresses, depending on your region. We are going to create a separate peer for each IP address, something similar to this:
Trunk Name: As you see fit, I chose a scheme to make it simple. This must be unique in your system. Outgoing Trunk Name: We are not going to use this peer for outgoing, but FreePBX will force this to be filled in. As above, I chose a scheme to keep them unique and simple. Leave the rest of the peer settings for Outgoing empty (clear the filler out) Incoming User Context: Again, this must be unique in the system. I chose TwilioIn1, 2, etc. Host: Set this to one of the IPs in the list below for your region. You should cover each IP address in your region in a separate trunk. so you will end up with 3-4 peers depending on your region.
IP Addresses for each region: UNITED STATES ( YOURTRUNKNAME.pstn.us1.twilio.com) 54.172.60.0 54.172.60.1 54.172.60.2 54.172.60.3 54.172.60.0/23 AUSTRALIA ( YOURTRUNKNAME.pstn.au1.twilio.com) 54.252.254.64 54.252.254.65 54.252.254.66 54.252.254.64/26 IRELAND ( YOURTRUNKNAME.pstn.ie1.twilio.com) 54.171.127.192 54.171.127.193 54.171.127.194 54.171.127.192/26 SINGAPORE ( YOURTRUNKNAME.pstn.sg1.twilio.com) 54.169.127.128 54.169.127.129 54.169.127.130 54.169.127.128/26 JAPAN ( YOURTRUNKNAME.pstn.jp1.twilio.com) 54.65.63.192 54.65.63.193 54.65.63.194 54.65.63.192/26 BRAZIL ( YOURTRUNKNAME.pstn.br1.twilio.com) 177.71.206.192 177.71.206.193 177.71.206.194 177.71.206.192/26 Creating an Inbound Route for your Twilio Number You need to tell FreePBX what to do with a call from your trunk. Go to Connectivity/Inbound Routes/Add Incoming Route
It is VERY important to put the DID number in E.164 Format, WITH the leading + sign! Set the appropriate destination (ring group, IVR, extension, as per your needs Create an inbound route, with appropriate destination settings, for each Twilio number Summary That should do it! Happy calling!