Using PJSIP_DIAL_CONTACTS in Asterisk.

This article is for the phone system engineer who is running an installation with the Asterisk VoIP system at its core.  Asterisk is the most widespread software in use today running telecom solutions, so chances are good that your phone system uses Asterisk, even if it goes by a different name.

1.1 - Telephony System – The Major Players

If your voip system isn’t running Asterisk, then it is likely using FreeSwitch, as these two titans make up the vast majority of installations available on the internet today.

You can learn more about either of these core products by visiting their web pages.  FreeSwitch information can be found off their portal:

• https://freeswitch.org

and Asterisk users, for whom this article is written, can find a wealth of information from the asterisk portal:

• https://asterisk.org

1.2 - What is Asterisk?

So what is Asterisk, exactly?  Asterisk lies at the heart of many phone systems today, making possible the creation of phone systems ranging from the simple to the highly complex.  It allows the phone administrator to create a viable phone system with only 10 or 20 lines of code.  This code is called ‘dialplan’ code, and paired with a few key configuration options, it can produce a working phone system in a very short amount of time and effort.

A core strength of the Asterisk software is its flexibility, coupled with an open source approach to the development ensuring that problems are identified and fixed rapidly by a large community of volunteers.

A few years ago the Asterisk system was updated in a major way:  It switched its default voip library away from the original module known simply as ‘sip’ and based on the sofia software package, to a more modern and flexible system known as ‘pjsip’.

This change meant that sooner or later, if your phone system is running under Asterisk, you will want to make the switch to using this ‘pjsip’ library instead of the older, now deprecated ‘sip’ module.

The pjsip library is configured to more closely match the concepts found in the official SIP documentaton – far better than the older sip library.  A good overview of how pjsip works within Asterisk can be found here, in the official documentation:

• https://wiki.asterisk.org/wiki/display/AST/PJSIP+Configuration+Sections+and+Relationships

Most of the advantages you will find when switching to using pjsip are outlned in the main stream articles about the topic.  These advantages include:

• A more modern code architecture
• A library that continues to enjoy active development and bug fixes
• Soon to be the dominant library used for VoIP products.
• Better overall compatibility with hardware as time goes on, as this is the standard now that devices will be designed against.

Hidden among these advantages is a powerful concept that may be easily overlooked.  If you dig, or come across the right documentation, you will clearly see that the pjsip system can support multiple contacts for a single extension.

We expand upon what this concept means in the next section.

If you administer a phone system, you will inevitably find that someone wants to have a home and an office phone that both ring when you dial their extension.  From the user’s point of view, they simply want to have two phones that are “connected” to the phone system as their single extension number.  This concept is what is meant by “Multiple Contacts per Extension”.

3.1 - The Old Way: Faking Multiple Contacts

In the bad old days of the original sip library that Asterisk came with, this concept did not exist, and it made for some awkward setups and configurations.

You could make the system seem to work this way but it required trickery using follow-me like functionality or ring groups carefully crafted so that any call to one extension actually rang a list of several extensions, each arranged to seem to be a single extension number.   Let’s not even start on how to make sure the mailboxes lined up and BLF keys mapped properly.. *shiver*.

The bottom line was you could do this well enough that a user would typically not realize their phones were not all truly the same extension, but it was convoluted, messy, and difficult to maintain.

People of course realized this limitation, and were hard at work finding the better way to do things.  Enter the new, improved ‘pjsip’ library.

3.2 - PJSIP – The New, Elegant Way of Handling Multiple Contacts

The pjsip library is built from the ground up to support the concept of a single extension having numerous contacts.  You can still do things the old fashioned way, but you are no longer required, nor even encouraged to.   The pjsip library provides all the support you need to allow multiple devices to register as a single extension, and almost all of the work is done when you switch to using pjsip.

There is one key to making this work, however, and it has not really received the amount of attention it deserves.  Without this little gem of a function, you can register multiple contacts but only the first one that did so would respond to the standard commands like ‘Dial’ and ‘Page’.

The function you need to know about is PJSIP_DIAL_CONTACTS. This function is the key to being able to support multiple phones registering to a single endpoint (extension) in asterisk.

Such an important function would, you might expect, receive more attention that it does in the documentation available.  In fact, there is no mention of the function at all in the revised Asterisk: The Definitive Guide – nor does it get called out specifically in the upgrade guide you’ll find most refer you to when making the switch to using the pjsip library.

This article is here to give PJSIP_DIAL_CONTACTS its due, and to show you exactly how simple it is to use it and how powerful its effect can be.

To see the power this little function unlocks, let us start with the basic dialplan code that we would have used for our original, old-style ‘sip’ based phone system.

4.1 - Dialing the Old Way

In this case, we have an extension ‘100’ that is defined to Dial the phone for 30 seconds, then drop into voicemail for that extension if it is not answered. For core, old-style Asterisk this dialplan might look very similar to the code below:

Notice the highlighted Dial() command that handles the ringing of the phone connected to the extension, as this is the only part of  the dial plan that will need to change!

4.2 - Dialing With PJSIP_DIAL_CONTACTS

To support multiple devices per endpoint, the previous extension handler’s Dial command then becomes simply:

As you can see from the highlighted line, the only difference is the invocation of the PJSIP_DIAL_CONTACTS function inside the dial command.  Yet, with this single change, you unlock the capacity to have numerous phone devices all registered as a single extension.

Now your code will generate the Dial() command needed to contact every valid registered contact for your extension.  With no further effort, you can now register a plethora of extensions.  For example, one can be a test phone, another a softphone, and two of them could be “hardware” phones – one at work and another at home.

All unlocked with this unassuming, simple function.  I love it when a system is written so well that this kind of power flows out from it as if it is the most natural thing in the world.

Now that you have seen the dial plan code, let me summarize how simple it is to make use of the function.  To make proper use of the pjsip capability to support multiple contacts per endpoint, you just need to ensure two things:

1. You need to modify your Dial() command to invoke PJSIP_DIAL_CONTACTS as shown above, to ensure you ring all associated contacts for the endpoint.
2. You need to set the max_contacts value for the endpoint’s AOR to ensure that it allows more than one contact to register.

We already covered the PJSIP_DIAL_CONTACTS function, so let me quickly mention the max_contacts value.  This is set up inside the AOR definition for an endpoint.  A simple example is shown in setup for extension 6001, taken from the Asterisk sample configuration and tweaked to up the max_contacts to 5:

This is all that is needed to allow you to register up to five devices per extension.  Change it to 20 and you could support a score of them, it is up to you.