Month: August 2010

How to forward a call if a remote extension is unreachable in FreePBX 2.x

 

Important
This is an edited version of a post that originally appeared on a blog called The Michigan Telephone Blog, which was written by a friend before he decided to stop blogging. It is reposted with his permission. Comments dated before the year 2013 were originally posted to his blog.

DISCLAIMER AND WARNING: This article contains EXPERIMENTAL code. DO NOT USE IT IN A PRODUCTION ENVIRONMENT until you have thoroughly tested it AND MODIFIED IT to meet your needs. It is guaranteed to NOT work (at least not in a way that will be useful to you) if you simply copy and paste it, and even if you read and follow the instructions below I don’t guarantee a thing (Asterisk can be funny, sometimes code that runs fine on one system will not on another). Anyway, you are NOT allowed to use this code unless you are willing to take ALL responsibility for modifying and testing it to make sure it will work in your situation. If you use this code and in some way it winds up not working and costing you money, don’t come after me because I’m warning you now that might happen, and it’s the risk you alone assume if you attempt to use this code!

FreePBX and Asterisk allow you to call forward a call on a busy or no-answer condition (as well as unconditionally), but there is no provision for specific forwarding if an extension (presumably an offsite one) is unreachable over the Internet. It is possible to do this, although in Asterisk 1.4 it’s not at all elegant. Some commercial VoIP providers offer a feature similar to this, calling it “Failover”, “Network Unavailable Forward” or just “Unavailable Forward”, “Network Availability Number ®” (Vonage trademarked that one!), or some similar name, but FreePBX and Asterisk do not offer similar functionality — there is no “Call Forwarding Unreachable” setting.  However, with a bit of work and a minimal amount of dialplan creation, you can emulate this feature.

Here’s an example that may work in many situations (as written it works with SIP extensions only, but maybe you can modify it slightly if you need to use it with IAX2 extensions or some other type):

First, if you are still using Asterisk 1.4 or earlier, add the following code to etc/asterisk/extensions_custom.conf:

[custom-unreachable-test] exten => _X!,1,Noop(Testing for unreachable extension ${EXTEN})
exten => _X!,n,TrySystem(asterisk -rx "sip show peers" | grep ^${EXTEN}/${EXTEN}[[:space:]] > /tmp/${EXTEN}.flag)
exten => _X!,n,ReadFile(reachable=/tmp/${EXTEN}.flag,1)
exten => _X!,n,GotoIf($["${LEN(${reachable})}" = "0"]?extoffline)
exten => _X!,n,Noop(Extension ${EXTEN} is reachable - sending to *${EXTEN} voice mailbox)
exten => _X!,n,Goto(from-internal,*${EXTEN},1)
exten => _X!,n(extoffline),Noop(Extension ${EXTEN} is NOT reachable)
;This is where you enter special forwarding conditionals for each unreachable extension
exten => _X!,n,GotoIf($["${EXTEN}" = "1101"]?from-internal,18005558355,1)
;This is the fallover (voicemail) destination in case no special destination is specified
exten => _X!,n,Noop(WARNING - no unreachable destination specified for extension ${EXTEN} - trying to send to voicemail)
exten => _X!,n,Goto(from-internal,*${EXTEN},1)

If you are using Asterisk 1.6 or later then use this instead:

[custom-unreachable-test] exten => _X!,1,Noop(Testing for unreachable extension ${EXTEN})
exten => _X!,n,Set(reachable=${SHELL(asterisk -rx "sip show peers" | grep ^${EXTEN}/${EXTEN}[[:space:]])})
exten => _X!,n,GotoIf($["${LEN(${reachable})}" = "0"]?extoffline)
exten => _X!,n,Noop(Extension ${EXTEN} is reachable - sending to *${EXTEN} voice mailbox)
;This is where you enter special forwarding conditionals for each unreachable extension
exten => _X!,n,GotoIf($["${EXTEN}" = "1101"]?from-internal,18005558355,1)
;This is the fallover (voicemail) destination in case no special destination is specified
exten => _X!,n,Noop(WARNING - no unreachable destination specified for extension ${EXTEN} - trying to send to voicemail)
exten => _X!,n,Goto(from-internal,*${EXTEN},1)

In both of the above examples, change the number 1101 to match an actual extension number on your system and change the 18005558355 to the actual number you want to send calls to (note this could be another extension on your system, including a custom extension or a ring group). Duplicate the line containing those values for each extension you may want to forward, changing those two vales in each line appropriately (also see the comment section for another possible approach).

The above code assumes that if an extension is reachable, but is busy or does not answer, you want the call to go to voicemail (* + the original extension number — obviously, this would be easy to change if that’s an incorrect assumption). However, if the extension is unreachable, you want to reroute it to the user’s cell phone or some other number. In the above example, if extension 1101 receives a call and is unreachable, it would be forwarded to TellMe at 1-800-555-TELL (18005558355) – obviously not practical in a real-world situation, but it’s just an example. Again, note you have to duplicate that line in the code for each extension that might be forwarded in this way.

In order to make this work, you need to go into the FreePBX Tools menu and select “Custom Destinations”, then add a new custom destination. The destination must be custom-unreachable-test,${EXTEN},1 and the description can be anything you want (I suggest “Unreachable Extension Test” or something similar).

For each extension you wish to use this with, you must have qualify=yes (or set qualify to a valid numeric value) in the extension settings.

Finally, for each extension you want to use this with, create a Follow-Me (or edit any existing one) for that extension. You can leave the defaults as they are (or change them if you want – maybe you want to change the Ring Time, for example) but the one thing you must change is the Destination if no answer. Change that to the Custom Destination that you just created. Also, don’t forget to add the line in extensions_custom.conf to actually do something with calls to that extension when the extension is unreachable.

The reason I say this code is not elegant is because it relies on a kludge. It does a “sip show peers”, then looks for the pattern ${EXTEN}/${EXTEN} (e.g. 1101/1101) at the start of a line, which on most systems indicates the extension is connected. This may not be the case if you are using what is known as “deviceanduser” mode (which you probably aren’t unless you’re running a call center) so in that case you may need to use a different pattern match, for example:

exten => _X!,n,TrySystem(asterisk -rx "sip show peers" | grep ^${EXTEN}[[:space:]] | grep OK > /tmp/${EXTEN}.flag)

The result of the system call will be written to the file /tmp/1101.flag (or a similar file with a different extension number) and will either contain the full line from “sip show peers” (if the device or phone is reachable) or nothing (it will be an empty file). So in the next line we read the file in (actually just one character) and test the length – if it’s zero, then that’s when we do the unreachable processing. If it’s non-zero, we send the call to voicemail. EDIT: In Asterisk 1.6 and later there’s no need to create a temporary file.

I’m not saying this is the best way to do this, or the only way to do it, but it is a way that seems to work in VERY limited testing (at least on a system running Asterisk 1.4.35 and FreePBX 2.5).

This was inspired by a thread I saw on the PBX in a Flash forum, which also notes that there may be an even better way to do this in Asterisk 1.8, but since I don’t have it and VERY few FreePBX users are running 1.8 at this time, I’m not even going to touch that one.

EDIT: I did a VERY limited test of this (and made one change in the above code as a result) on an Asterisk 1.8 system running F—PBX 2.8. There are now two code sections above, one for those running Asterisk 1.4 or earlier, and one for those running Asterisk 1.6 or later (only tested with Asterisk 1.8). And before you try that “even better way” mentioned in the last paragraph, note that “Having chan_sip set HASH(SIP_CAUSE,) on the channel carries a significant performance penalty because of the usage of the MASTER_CHANNEL() dialplan function” and that Digium has “decided to disable this feature by default in future 1.8 versions” (see this page for more information). So, probably best to stick with the method shown here, if you can get it to work for you.

Review of FreeSWITCH 1.0.6 by Anthony Minessale, Darren Schreiber, Michael S. Collins (Packt Publishing)

 

Important
This is an edited version of a post that originally appeared on a blog called The Michigan Telephone Blog, which was written by a friend before he decided to stop blogging. It is reposted with his permission. Comments dated before the year 2013 were originally posted to his blog. In order to comply with Federal Trade Commission regulations, I am disclosing that he received a free product sample of the item under review prior to writing the review, and that any links to Amazon.com in this article are affiliate links, and if you make a purchase through one of those links I will receive a small commission on the sale.
Cover of FreeSWITCH 1.0.6

In case you’ve never heard of FreeSWITCH, it is a “telephony software engine”, which means it’s in the same category as Asterisk. Over the years I’ve noticed that some Asterisk users have become frustrated with Asterisk due to unfixed bugs and design flaws that mean that the software doesn’t always work as it should. So, for quite some time, I’d hoped that a viable alternative to Asterisk might emerge, if only to keep the Asterisk developers on their toes. Competition between software projects tends to be a healthy thing, and from what I’ve read in this book, it appears that FreeSWITCH just may be the software product that eventually replaces Asterisk as the open source telephony software engine.

Before I begin, as is my custom with such reviews, let’s start with a quick overview of what’s in each chapter (for the complete Table of Contents, see the Packt Publishing web site):

  • Preface
  • Chapter 1: Architecture of FreeSWITCH – includes notes on the FreeSWITCH design and important modules
  • Chapter 2: Building and Installation – how to build and run FreeSWITCH under Linux/Unix, Mac OS X, or Windows
  • Chapter 3: Test Driving the Default Configuration – here you learn how to control FreeSWITCH with the CLI and to make your first call
  • Chapter 4: SIP and the User Directory – includes adding users, setting up voicemail, and setting up a gateway to connect to the world (link is to sample chapter in PDF format at the Packt Publishing site)
  • Chapter 5: Understanding the XML Dialplan – this gets into the “meat” of FreeSWITCH dialplan creation
  • Chapter 6: Using the Built-in XML IVR Engine – here’s where you learn one way to build an IVR (auto-attendant)
  • Chapter 7: Building IVR Applications with Lua – really an example of using a scripting language with FreeSWITCH. A few other languages are supported
  • Chapter 8: Advanced Dialplan Concepts – if Chapter 5 was the hamburger, this is the sirloin
  • Chapter 9: Controlling FreeSWITCH Externally – explains the event system architecture, and how to read and send events
  • Chapter 10: Advanced Features and Further Reading – includes multi-user conferencing, billing, XML/Curl, alternative endpoints, and configuration tools and related projects

There are also two appendices:

  • Appendix A: The FreeSWITCH Online Community
  • Appendix B: The History of FreeSWITCH

The  Packt Publishing web site also has this to say about the book:

What you will learn from this book :

  • Set up a basic system to make and receive phone calls, make calls between extensions, and utilize basic PBX functionality
  • Avoid common implementation mistakes and deploy various features of this telephony system with best practices and expert tips
  • Perform routine maintenance for smooth running and troubleshoot the system when things are not going right
  • Apply regular expressions to unlock unique and powerful call routing scenarios
  • Call your own application(s) when particular events occur and control FreeSWITCH using the powerful Event Socket
  • Set up multi-party conferencing facilities for your system
  • Interact with callers, gather information, and route calls to the appropriate recipient using the automated, built-in XML IVR (Interactive Voice Response) engine
  • Create a flexible dialplan, and allow third-party tools to be quickly and easily created using dialplan parsers other than the default XML Dialplan
  • Park multiple calls in a FIFO queue and unpark them in the order in which they were received, using the mod_fifo module
  • Record an entire phone call or session using the call recording feature
  • Create advanced call control applications with the Lua scripting language
  • Take a peek into the vibrant online community and history of FreeSWITCH

Approach

This book is a step-by-step tutorial with clear instructions and screenshots to guide you through the creation of a complete, cost-effective telephony system. You will start with installation, walk through the different features, and see how to manage and maintain the system.

Who this book is written for

If you are an IT professional or enthusiast who is interested in quickly getting a powerful telephony system up and running using the free and open source application FreeSWITCH, this book is for you. Telephony experience will be helpful, but is not required.

Now, here are my impressions. Please bear in mind that I did not actually attempt to build a working FreeSWITCH installation (I would need yet another spare computer to do that), but I certainly feel as though I could after reading this book. One thing that is somewhat uncommon about this book is that the author of the software is also one of the authors of the book. Too often, when you see a book written about a piece of software, the writer doesn’t fully understand the software and therefore makes guesses and assumptions about how it works, that may lead to problems down the road if you follow their advice. When the software author collaborates on the book, that’s far less likely to happen, and indeed, at no point in this book did I get the feeling that the author was struggling to understand the subject. I will even go so far as to say that this is one of the best written technical books I have read in a long time.

The biggest complaint I had about this book — and it is a very minor one — is that it could have benefited from another proofreader. Occasionally I’d see an obvious error that the proofreader should have caught — nothing major, and nothing I couldn’t figure out with about two seconds of thought, with one exception.  On page 91 of the book, it appears to me as though there is some missing text at the bottom of the page.  It’s discussing making a test call to Music on Hold and then, suddenly and jarringly, it jumps into a time of day example.  I think the disconnect occurs in middle of a sentence: “In our example, call the debug output is as follows:”  The sentence as written does not make sense to me, and it appears a block of text (perhaps a large one) may have been omitted at this point. But that is the only place in the book where I encountered an error of that magnitude. I have submitted the error to Packt Publishing and I’m hoping they will figure out what was supposed to go there and place it in the errata section of their web site.

One other point I will make about a software author writing a book on his own creation is that I think sometimes, it’s difficult for the author to correctly envision how end users will want to use the software.  As an example, virtually all the dialplan examples in this book are in XML.  There may be advantages to using XML, but it’s not going to be very familiar to someone coming from an Asterisk background, and I might have wished for a few non-XML examples.  On pages 158-159, the author notes that,

There is a common misconception that the FreeSWITCH Dialplan is based on, and requires, XML. That is simply not true. If you prefer flat files, you could use them to store your Dialplan configuration. If you prefer YAML, you could use that, too. You just need to load the correct C-based Dialplan module to interpret your stored logic for the particular type of configuration file you want FreeSWITCH to utilize.

This aside, the most common (and currently, the most robust) Dialplan processing mechanism in FreeSWITCH is still the XML-based Dialplan module. Most Dialplan examples that are shipped with FreeSWITCH, or those scattered on the Web are in XML, therefore, they will remain the focus of this chapter. …..

Indeed, there is even an Asterisk dialplan module, albeit with limited capabilities.  From page 199:

If you are used to the Asterisk Dialplan, some basic functionality is provided by the Asterisk Dialplan module, although it is not nearly as feature-rich as the XML engine. You can process contexts and route calls to phones using the Asterisk Dialplan. This module, again, is more of a sample on how to build an alternate Dialplan processing module and should not be utilized as a full, feature-rich Dialplan system.

Yet you won’t find examples using flat files, YAML, or Asterisk Dialplan in the book.  However, the XML examples were clearly written and easy to understand, so I don’t think that there would be a steep learning curve to start writing dialplans in XML, assuming you are a proficient enough coder to write dialplans in the first place.  And, I suspect that XML would be easier for a new user to pick up than any of the other options.

I mention the above to emphasize two points:  FreeSWITCH is different from Asterisk. If you are thinking about moving from Asterisk to FreeSWITCH, you need this book to get you up to speed on the differences.  And second, FreeSWITCH is both more capable than Asterisk, and arguably easier to use, once you get used to the differences (or if you have no prior experience with similar software). FreeSWITCH appears to have been designed from the ground up to avoid the issues that have plagued Asterisk, particularly those that cause Asterisk to fall to its knees under heavy load or heavy call volumes. Even if you’re a long-time Asterisk user, you may want to get this book just to see what you’re missing.  You might decide that it’s worth your effort to set up a test system using FreeSWITCH, to help you understand how much better the next generation of telephony software engines can be.

One other point, in case you are reading this review several months after I wrote it — the author notes this in the preface:

At the time of this writing this book, the FreeSWITCH developers were putting the finishing touches on FreeSWITCH version 1.2. While the examples presented in this book were specifically tested with version 1.0.6, they have also been confirmed to work with the latest FreeSWITCH development versions that form the basis of version 1.2. Do not be concerned about the fact that this material does not cover version 1.2—it certainly does. The FreeSWITCH user interface is very stable between versions; therefore, this text will be applicable for years to come.

There will no doubt be some of you who are reading this that wonder if there are any Web GUI “front ends” (dialplan and configuration file generators) for FreeSWITCH.  Indeed there are, and they are covered in Chapter 10, which briefly explains the differences between WikiPBX, FreePBX v3, FusionPBX, and 2600hz.  Even if you plan on using a Web GUI, there may be times when you find the need to write a bit of custom code, and in that case having this book available would definitely be helpful to you.

One other thing I personally found interesting in this book was Appendix B, “The History Of FreeSWITCH.”  This explains how FreeSWITCH came to be, and along the way offers further explanation on how it is different from Asterisk and why the developers felt the need to start a new project.  What I think I found most interesting (and perhaps unfortunate, depending on your point of view) is that FreeSWITCH could have been the basis for Asterisk version 2, had only the Asterisk developers reacted positively to the idea. I see this sort of thing happen occasionally in the open source community, where the lead developers of a project start to develop an attitude that does not encourage outside contributions (or, they treat contributions or suggestions for improvement as if they were piles of steaming dog poo on their doorstep). Perhaps this should serve as a cautionary tale to such developers that your project can always be replaced by something better, if you do not encourage contributions to your own project from those not currently in your “inner circle” of developers.

As you may know if you have read my previous reviews, it’s rare that I get wildly enthusiastic about a book.  In this case I’ll make an exception, because overall the book is that well-written (my comments above notwithstanding). If you have any interest at all in using FreeSWITCH, or are even just curious about it, you really should buy this book.  It’s available in both traditional softcover dead-tree format, and as a DRM free Adobe PDF eBook, and there’s even a package deal if you want both formats. Don’t forget that you can view a sample chapter (PDF format) prior to purchase. EDIT: Also, there is an online article by the book’s authors entitled FreeSWITCH: Utilizing the Built-in IVR Engine.

FreeSWITCH 1.0.6 by Anthony Minessale, Darren Schreiber, Michael S. Collins (Amazon affiliate link)

Related: Review of FreeSWITCH Cookbook by Anthony Minessale, Michael S Collins, Darren Schreiber, Raymond Chandler (Packt Publishing)