The SMS Toolkit: Integrating Text Messaging into Asterisk

Unless you’ve been living under a rock, you probably already know that most folks spend a lot more time texting on their smartphones rather than talking. So it only made sense to develop some useful SMS tools to get the most out of your Asterisk® PBX. Today we’re pleased to introduce version 1 of an SMS Toolkit for Incredible PBX® using any SMS-enabled DID from either Vitelity or VoIP.ms. Just text a simple message to your PBX, and Incredible PBX will do the heavy lifting and either call you back with the results or reply to your text message. You can whitelist an IP address in your firewall or retrieve news headlines or a weather forecast. You can also look up a phone number in your AsteriDex phone book and place a call through your PBX using either the Voice Dialer or speed dial codes. You can enable call forwarding from your PBX extension to your smartphone, or a simple SMS command brings the calling flexibility of DISA to your smartphone. Here’s a list of supported SMS commands:

To get started, you’ll need a DID from Vitelity or VoIP.ms that supports SMS messaging. You’ll be hard-pressed to beat our Vitelity DID special which is summarized at the end of this article, but the choice is all yours. The way this works is you provide a forwarding email address in the Vitelity or VoIP.ms portal for delivery of incoming SMS messages. These emails will be sent to your PBX where we will use SendMail and our mailcall script to process the messages and deliver the results. SMS messaging is a free add-on with both Vitelity and VoIP.ms DIDs unlike some other providers.

Since Vitelity or VoIP.ms will be delivering incoming SMS messages by email, it means you’ll also need a dedicated account and fully-qualified domain name (FQDN) for your server, e.g. smsuser@mypbx.mydomain.com. While a dynamic IP address will work if you implement automatic FQDN updating on your PBX, a static IP address for your PBX is obviously preferable and all of our recommended cloud solutions provide that including RentPBX, Digital Ocean, Vultr, and HiFormance.

Let’s walk through the steps to put all the pieces in place for the SMS Toolkit:

To simplify the task of sifting through incoming emails, we’ll want to create a new Linux user account that can be dedicated to receipt of SMS email messages. The second and third commands will verify that the account has been created with support for incoming mail. Just log into your server as root and issue the following commands:

adduser smsuser --shell=/bin/false --no-create-home --system -U
ls /var/mail/smsuser
mail -u smsuser

By design, both SendMail and the Incredible PBX firewall block incoming email. We’re going to change that but, in doing so, we wish to caution that we don’t want to turn your server into an open mail relay for the spammers of the world. Once we’ve opened up your server to receive email, it’s important to test it to be sure it’s not insecure. Because the SMS Toolkit is intended to be a dedicated application just for you as administrator of your server, it’s equally important not to publicize the FQDN of your server. Once the spammers find your email address, incoming email can be just a big a problem as serving as an open mail relay.

To add a firewall rule in Incredible PBX to support incoming SMTP mail traffic, issue the following commands:

echo "iptables -A INPUT -p tcp -m tcp --dport 25 -j ACCEPT" >> /usr/local/sbin/iptables-custom
iptables-restart

Configuring SendMail to receive incoming email requires a few changes in /etc/mail/sendmail.mc followed by a restart of the SendMail service.

Using your favorite editor: nano -w /etc/mail/sendmail.mc

1a. Search for the following line:

DAEMON_OPTIONS(`Port=smtp,Addr=127.0.0.1, Name=MTA')dnl

1b. Replace that line with the following two lines:

dnl # DAEMON_OPTIONS(`Port=smtp,Addr=127.0.0.1, Name=MTA')dnl
FEATURE(`dnsbl',`dnsbl.njabl.org',`"550 Mail from " $&{client_addr} " rejected"')dnl

2a. Search for the following line:

FEATURE(`accept_unresolvable_domains')dnl

2b. Replace the line with the following and save the file:

dnl # FEATURE(`accept_unresolvable_domains')dnl

 
3. If you need an FQDN or dynamic DNS support, you can’t beat free. Here are some options.

4. Issue the following commands to complete the setup and restart SendMail:

yum -y install sendmail-cf
cd /etc/mail
make
echo "127.0.0.1 insert-your-server-FQDN-here" >> /etc/hosts
service sendmail restart

 
5. Using a browser from your desktop PC, test your server’s IP address to make certain it is not an open mail relay. All tests should report "Relaying Denied" or "Invalid route address."

6. Test your new mail account by sending an email to smsuser@your-server’s-fqdn. Wait a bit and check for email: mail -u smsuser. Then delete the email: > /var/mail/smsuser

With Vitelity DIDs, the first step is to order a DID that supports SMS, most do. Next, you need to decide whether this DID will be used for other purposes, such as serving as a trunk on your PBX for receipt of incoming calls. If this is your plan, then review the Vitelity offer at the bottom of this page. You’ll be hard-pressed to beat the price or the feature set. And you’ll also be providing support for our open source projects. Vitelity has been a Platinum Sponsor of Nerd Vittles for almost a decade.

If you only want to use the DID to support SMS messaging, then there’s little reason to sign up for the unlimited calling plan. Instead, choose the pay-per-minute (PPM) plan for your DID. It costs $1.49 a month. Don’t even both registering the trunk which will save your having to pay for misdialed calls and spam. SMS messages are free.

Once your DID is set up, go to My Numbers -> Local in the Vitelity web portal and choose SMS from the Action pull-down menu of your new DID:

In the SMS dialog, set up a password for messaging, disable international messages, and enter the email forwarding address for your incoming SMS messages. Save your settings, and you’re good to go.

If you plan to dedicate a DID to SMS messaging, two advantages of the VoIP.ms offering are (1) the price ($0.85/month on the pay by the minute plan with $0.40 setup fee and (2) you can forward incoming SMS messages to another SMS number (such as your smartphone) in addition to an email address if you want to use the DID for traditional SMS messaging while also deploying our SMS Toolkit. As noted above, there’s no charge for SMS messages at this time although VoIP.ms has warned (for years) that they may begin charging a penny a message. As long as Vitelity is free, I wouldn’t worry. 🙂

To get started, sign up for a VoIP.ms account and order a DID with SMS support. A cellphone is displayed beside each DID that supports SMS in their ordering page. As with Vitelity, there’s no need to register the trunk on your PBX if you only plan to use the SMS messaging component. Once your DID is provisioned, choose DID Numbers -> Manage DIDs in the VoIP.ms portal. Then edit the DID you just purchased. At the bottom of the form, fill in the SMS section as shown below:

MailCall was specifically designed for Incredible PBX 13-13 Full Enchilada but should work without modification with the latest version of Incredible PBX for Issabel 4. For other platforms including Debian, Ubuntu, and Raspbian, some adjustments may be necessary, and we have not yet had time to work out the kinks. There will be some so please hold off. Just to restate the obvious. Many of the MailCall features will not work until they are first configured on your server, e.g. Voice Dialing, Wolfram Alpha, and Voice SMS Messaging. All of the setups are covered in the Full Enchilada tutorial.

After logging into your server as root, issue the following commands to install MailCall:

cd /
wget http://incrediblepbx.com/MailCall.tar.gz
tar zxvf MailCall.tar.gz
rm -f MailCall.tar.gz

For the DISA and Firewall WhiteList components of MailCall, a 5-digit PIN is required for obvious reasons. This needs to be set in two places: (1) in two chunks of dialplan code (/tmp/sms-dialplan.txt) to be added and (2) at the top of the mailcall script itself (/root/mailcall). Just search for XXXXX and replace the five X’s with a 5-digit secure PIN in all three places. Then issue the remainder of the commands below:

nano -w /tmp/sms-dialplan.txt
nano -w /root/mailcall
cat /tmp/sms-dialplan.txt >> /etc/asterisk/extensions_custom.conf
echo "asterisk ALL = NOPASSWD: /sbin/iptables" >> /etc/sudoers
echo "*/2 * * * * root /root/mailcall > /dev/null 2>&1" >> /etc/crontab
asterisk -rx "dialplan reload"

As a security precaution, you can only use SMS Toolkit to forward and unforward calls to your cellphone from a PBX extension designated for your use. You can associate more than one cellphone with a given extension, but you can’t associate multiple extensions with a single cellphone. To set up the association between your cellphone and an extension on your PBX, issue the following command while logged in as root where 8431234567 is your cell phone number and 701 is the associated extension:

asterisk -rx "database put CELL 8431234567 701"

Sending an SMS message of CF ON to your DID from 8431234567 will automatically forward extension 701 calls to your cell. Sending CF OFF will disable call forwarding for extension 701. Sending CF STATUS will retrieve the current status of call forwarding for extension 701.

Finally, a few words about the SMS whitelist command. It can be used in two ways. If you just text whitelist, then you will get a call back that first prompts for your PIN. You then will be prompted for the IP address to whitelist. Using your cellphone, enter the IP address using * for periods, e.g. 1*2*3*4 becomes 1.2.3.4. The alternative whitelist option doesn’t require a callback. Just send a text message with whitelist pin ip-address using periods, not *, e.g. WHITELIST 98765 1.2.3.4 would whitelist 1.2.3.4 if your PIN was correctly entered as 98765 and matches the entry in /root/mailcall. Enjoy!

Published: Monday, February 26, 2018

NEW YEAR’S TREAT: If you could use one or more free DIDs in the U.S. with unlimited inbound calls and unlimited simultaneous channels, then today’s your lucky day. TelecomsXChange and Bluebird Communications have a few hundred thousand DIDs to give away so you better hurry. You have your choice of DID locations including New York, New Jersey, California, Texas, and Iowa. The DIDs support Voice, Fax, Video, and even Text Messaging (by request). The only requirement at your end is a dedicated IP address for your VoIP server. Once you receive your welcome email with your number, be sure to whitelist the provider’s IP address in your firewall. For Incredible PBX servers, use add-ip to whitelist the UDP SIP port, 5060, using the IP address provided in your welcoming email.

Here’s the link to order your DIDs.

Your DID Trunk Setup in your favorite GUI should look like this:

Trunk Name: IPC
Peer Details:
type=friend
qualify=yes
host={IP address provided in welcome email}
context=from-trunk

Your Inbound Route should specify the 10-digit DID.

Why not add 300 New Wholesale Providers to Make Asterisk Shine while visiting TelecomsXchange. Enjoy!

Need help with Asterisk? Visit the PBX in a Flash Forum.

Special Thanks to Our Generous Sponsors

FULL DISCLOSURE: ClearlyIP, Skyetel, Vitelity, DigitalOcean, Vultr, VoIP.ms, 3CX, Sangoma, TelecomsXchange and VitalPBX have provided financial support to Nerd Vittles and our open source projects through advertising, referral revenue, and/or merchandise. As an Amazon Associate and Best Buy Affiliate, we also earn from qualifying purchases. We’ve chosen these providers not the other way around. Our decisions are based upon their corporate reputation and the quality of their offerings and pricing. Our recommendations regarding technology are reached without regard to financial compensation except in situations in which comparable products at comparable pricing are available from multiple sources. In this limited case, we support our sponsors because our sponsors support us.

BOGO Bonaza: Enjoy state-of-the-art VoIP service with a $10 credit and half-price SIP service on up to $500 of Skyetel trunking with free number porting when you fund your Skyetel account. No limits on number of simultaneous calls. Quadruple data center redundancy. $25 monthly minimum spend required. Tutorial and sign up details are here.

The lynchpin of Incredible PBX 2020 and beyond is ClearlyIP components which bring management of FreePBX modules and SIP phone integration to a level never before available with any other Asterisk distribution. And now you can configure and reconfigure your new Incredible PBX phones from the convenience of the Incredible PBX GUI.

VitalPBX is perhaps the fastest-growing PBX offering based upon Asterisk with an installed presence in more than 100 countries worldwide. VitalPBX has generously provided a customized White Label version of Incredible PBX tailored for use with all Incredible PBX and VitalPBX custom applications. Follow this link for a free test drive!
 

Special Thanks to Vitelity. Vitelity is now Voyant Communications and has halted new registrations for the time being. Our special thanks to Vitelity for their unwavering financial support over many years and to the many Nerd Vittles readers who continue to enjoy the benefits of their service offerings. We will keep everyone posted on further developments.
 

Some Recent Nerd Vittles Articles of Interest…