SIP Gateway from Us to the ITSP to the World

FreeSWITCH simplifies SIP for us, with the concept of "gateway".
That "gateway" in FreeSWITCH lingo is just a glorified automation provided to us, so we can use a simplified syntax meaning: "check whether this particular Internet Telephony Service Provider (ITSP) is up and reachable, send this call out to it, give the ITSP the login and password to authorize our call if needed, and wait for the ITSP to connect our call to the wide world".

All of those mechanisms and actions are performed transparently to us, and the monitoring of the ITSP availability is performed routinely even when we don't use it, so if ITSP is down we don't even try it, but we'll be able to use it when it is back.

By the way, what happens under the hood is that FreeSWITCH uses the SIP concept of "proxy" to ask our ITSP to route our outbound call. The ITSP then use some method opaque to us to terminate, eg to connect to final destination, our call. That termination method can be a direct link ITSP has with the final or intermediate carrier, or maybe ITSP has hardware to interface to PSTN, such as Sangoma cards and Patton boxes, or even our ITSP is then rerouting our traffic to another upstream ITSP. We don't know.

Each ITSP has slightly different methods for accepting our requests for them to route our outbound calls. It is important that ITSPs take security seriously. We must TAKE SECURITY in connecting to our telephony provider VERY SERIOUSLY: it MAY COST US THOUSANDS OF DOLLARS IN FRAUD. It is as easy as: someone else, maybe a rogue ITSP, route its outbound calls (its "traffic") using our account at our telephony provider. We end up paying the bill, that can be dramatically high.

So, before setting up our first gateway, let me repeat this: we must take security and fraud prevention very seriously.
Telephony fraud is a huge industry, an incredible number of frauds are continually perpetrated, and someone is definitely going to pay for that traffic. Keep our password complex and unguessable, ask our ITSP for the traffic to be allowed only from our IP address, ask for whitelisting destination countries (that is, traffic will only be accepted if directed to countries we authorized, such as USA, Europe, and Asia, but not to Oceania and satellite phones), block for pay numbers (for example, 188 and similar). If possible at all, use SIPS via TLS and SSL certificates to be sure only traffic actually generated by us will be accepted and acted upon by our ITSP.

Let's assume we've done our due diligence and secured ourselves against fraud at the best of our possibilities.

Edit the /usr/local/freeswitch/conf/sip_profiles/external/example.xml XML file, and add a "gateway" container before the ending </include> tag. We can search FreeSWITCH documentation at http://freeswitch.org/confluence looking for an example configuration of a gateway to our ITSP, or we can look into our ITSP website, send ITSP's support a mail, or ask in FreeSWITCH mailing list. Anyway, usually is very easy, and boils down to a user/password couple, and to specify whether registration is needed or not.

In our example we'll use Telnyx, a sponsor of 2017 ClueCon conference (eg, our conference, each year in August in beautiful Chicago). First of all we create a "connection" username/password using the Telnyx website. Our newly created "connection" has "freeswitchuser" as username and "huikyfruywedgweicguwy" as password. Then, we edit the /usr/local/freeswitch/conf/sip_profiles/external/example.xml XML file, and add a new "gateway" container before the ending </include> tag:

That's it. We can restart FreeSWITCH, or issue "reload mod_sofia" from command line, and FreeSWITCH will register itself to the Telnyx SIP proxy, and we'll be ready to send calls to the outside world.

We can check how our new gateway is going by issuing "sofia status gateway telnyx" from FreeSWITCH command line.

In our case, we see we've been successful in registration ("State" line is "REGED", eg registered), that this gateway is up since 61 seconds, we'll register again in 1 hour, and so on:

Now, let's edit the /usr/local/freeswitch/conf/dialplan/default.xml dialplan XML file, so we will be able to send calls through Telnyx gateway.

At the beginning of the file, we add a new extension that will route our calls through Telnyx to the USA PSTN:

Here, look the regular expression cleverness: "destination_number" must begin with 9, then 1, then ten digits, and no more. Of the whole "destination_number" string, we use parenthesis to select starting from the 1 after the 9, up and included the following ten digits (eg, we "discard" the initial 9 from selection).
We will find our selection in the next line, inside the "data" arguments passed to the "bridge" action": will be substituted to the "$1" placeholder (representing what was selected by the first couple of parenthesis. If there was a second parenthesis couple, we would be able to refer to what this second couple had selected using the "$2" placeholder).

After issuing a "reloadxml" from FreeSWITCH command line, we can dial 918005551212 from one of our registered phones, and have a call to 18005551212 (9 is discarded by dialplan) sent to USA via Telnyx.