Asterisk Primer
This section is going to be a little different, because it can't really be a set of exact instructions. ITSPs each have slightly different ways of doing things and might require extra config options. So, the goal here really is to introduce you some general concepts to assist you in connecting to an ITSP. They usually have configuration guides of their own for specifics.
As ever, we start by configuring some SIP peers to use. Generally speaking, you will need 2 peers, one for incoming calls and one for outgoing calls. Again, this can vary between ITSPs; some use a single hostname for calls in either direction, while others have this separate setup.
Edit /etc/asterisk/sip.conf and let's add them:
First we have [TheITSP-In], our made-up peer for incoming calls. We've set it to type=peer which, if you remember, means incoming calls will get matched by IP/port. In this case our fake ITSP has a single IP address from which it sends out calls, which we've specified by hostname on the host line. However, an ITSP doesn't usually register to us, so we can't be sure what port number SIP packets might be coming from. The insecure=port,invite line takes care of this via the port option, which tells Asterisk to not pay attention to the port number while trying to match this peer. The other insecure option, invite, tells Asterisk that calls from this peer do not require authentication - which is also why, if you hadn't noticed, we have no secret set for this peer. It's fairly rare for an ITSP to let you configure authentication credentials for calls they send to you.
Finally, we've set context=incoming to send calls into a separate [incoming] context of our dialplan (which we'll make soon.) We don't want to use our existing "internal" context, because we want to keep calls from the outside world totally separate from our internal extensions (which will include the ability to dial back out shortly.)
For our [TheITSP-Out] peer, we've given a hostname for the host line, which could actually resolve to a number of different IPs. Just note that Asterisk only resolves the hostname and picks a single IP from the results at the time the peer is initially loaded (from starting Asterisk or reloading SIP while running.)
Another new option you haven't seen before is fromuser which may or may not be needed by your ITSP. The value of fromuser gets put in the From: header of the INVITE sent to your ITSP, which they may need to identify you by. Sometimes it's an account name or username of some sort, or could be the DID you have with them.
On this outgoing peer we have set a secret, which is used for authenticating the calls you send to them.
Finally, we've set context=incoming even though we don't plan to get incoming calls from this particular peer.. but in the event an incoming call somehow manages to match this peer and authenticate (which it shouldn't) it will get sent into the dialplan into our incoming context, which is a reasonably secure thing to do.
The last piece of the puzzle is that you usually need to register with the ITSP - much like the softphones we configured earlier register to Asterisk - in order to inform them that you are online, available to receive calls from them, and most importantly what your IP and port number are. To do this, you add a special line to /etc/asterisk/sip.conf at the end of the [general] section, before any of your peer definitions:
The syntax of the register line can actually be quite complex depending on the ITSP, which might require additional options when registering. Again, they should have some sort of guide to help you.
Now we just need to make some dialplan to let us make calls and handle receiving ones. We'll deal with accepting incoming calls first.
When you have a DID through an ITSP and someone calls it, they almost always send it to the extension matching your DID. For our example, we're going to pretend we have an assigned phone number of 555-111-2222 with our mythical ITSP. Edit /etc/asterisk/extensions.conf and add onto it:
When someone calls our 555-111-2222 phone number, the ITSP sends the call to us at extension 5551112222. We in turn match their peer from sip.conf by IP, and send the call into the dialplan to that extension in the [internal] context, as is configured by the TheITSP-In peer. In the dialplan we then have extension 5551112222 dial our TestPhone-A peer, causing it to ring. It's as simple as that.
Now let's setup an extension so we can make outgoing calls as well. Again edit /etc/asterisk/extensions.conf and add an extension to the end of the [internal] context, so that our TestPhone-A peer is able to access it:
OK, now we're seeing some strange new things!
First, our extension looks a little funky. Up until now we've been dealing with static extensions, a string of exact digits. But when dialing out, we need to be able to dial arbitrary numbers, and we don't want to have to make an extension for every single possibility.
In come patterns. The first character in the extension, _ (and underscore) signifies that this extension is a pattern, which enables special meta-characters in the rest of the extension for matching what was dialed - basically wildcards. There are several meta-characters, but for now we're just using N and X. N means "any digit between 2 and 9", while X means "any digit between 0 and 9." The pattern NXXNXXXXXX is a commonly-used pattern which will match any standard NANP 10-digit phone number in the USA. Consult the Asterisk Wiki for complete pattern matching syntax.
The next new bit of syntax is our Dial application. Unlike dialing devices directly, which is all we've done up to this point, we now need to pass along a number to the ITSP for them to actually place a call somewhere. This is done as an additional argument to the Resource part of the channel specification (which you should remember from the previous section when we explained channels.) The resource is the name of the peer we're using, TheITSP-Out, followed by / and the extension we wish to call on that peer.
${EXTEN} is a standard/built-in channel variable which gets replaced with the actual extension that was dialed. Remembering that our extension is actually a pattern of unknown digits, ${EXTEN} will represent the actual digits dialed that matched the pattern. So, assuming we dialed the number 2223334444, ${EXTEN} would be 2223334444, and our Dial line would expand out to Dial(SIP/TheITSP-Out/2223334444).
With all of that in place, dialing 2223334444 on our TestPeer-A phone will enter the dialplan in the [internal] context, match the _NXXNXXXXXX extension, and call 2223334444 on the TheITSP-Out peer.