Intro to Flowroute SMS

Flowroute has added SMS functionality to their arsenal of quality communication services. For enhanced usability in the open source community, Quentus wrote native support for Flowroute SMS in FreeSWITCH through the new mod_sms_flowroute.

Installing mod_sms_flowroute

Mod_sms_flowroute is currently available in the FreeSWITCH source repo. Support in packages will be announced soon!

On your Debian Jessie server, first clone the h2o libraries needed for the module.

 apt-get install -y cmake build-essential libssl-dev pkg-config git
 cd /usr/src/
 git clone https://github.com/h2o/h2o.git
 cd h2o
 git checkout 2841315cd23d5d8cb7b257f239d5b48c4f6994b0
 mkdir build && cd build && cmake -DBUILD_SHARED_LIBS=YES ../ && make install && ldconfig

On the same server, install FreeSWITCH from source following the steps for Building from source.

 wget -O - https://files.freeswitch.org/repo/deb/debian/freeswitch_archive_g0.pub | apt-key add -
 echo "deb http://files.freeswitch.org/repo/deb/freeswitch-1.6/ jessie main" > /etc/apt/sources.list.d/freeswitch.list
 apt-get update
 apt-get install -y --force-yes freeswitch-video-deps-most
 git config --global pull.rebase true
 cd /usr/src/
 git clone https://freeswitch.org/stash/scm/fs/freeswitch.git freeswitch.git
 cd freeswitch.git
 ./bootstrap.sh

After running bootstrap.sh, open /usr/src/freeswitch.git/modules.conf and uncomment or add:

 applications/mod_sms
 applications/mod_sms_flowroute

Then proceed with the configure, make, and make install commands.

 ./configure
 make
 make install

Configuring mod_sms_flowroute

On your router, forward a port to your FreeSWITCH instance. The external port can be the same as the port FreeSWITCH will be listening on, such as external:8080 pointing to internal:8080, or if desired, they can be different, such as accepting 9023 on your external IP pointing to 8090 on the FreeSWITCH instance.

You can then set the SMS CallBack IP and port on your Flowroute account at https://manage.flowroute.com/accounts/preferences/api/ then click "+Enable SMS" to apply it.

On the FreeSWITCH server in the FreeSWITCH config directory (/usr/local/freeswitch/conf/ when installing from source), open autoload_configs/sms_flowroute.conf.xml and configure based on your Flowroute API credentials and SMS CallBack port:

 <configuration name="sms_flowroute.conf" description="SMS_FLOWROUTE send configs">
   <profiles>
     <profile name="default">
       <params>
         <param name="host" value="https://api.flowroute.com/v2/messages"/>
         <param name="debug" value="1"/>
         <param name="port" value="8090"/>
         <param name="access-key" value="ACCESS-KEY"/>
         <param name="secret-key" value="SECRET-KEY"/>
       </params>
     </profile>
   </profiles>
 </configuration>

If you want mod_sms_flowroute to automatically load whenever FreeSWITCH starts, make sure it is present and uncommented in autoload_configs/modules.conf.xml.

 <!-- Applications -->
 ...
 <load module="mod_sms"/>
 <load module="mod_sms_flowroute"/>

Start FreeSWITCH and connect with fs_cli. Since we installed from source:

 /usr/local/freeswitch/bin/freeswitch -nonat -ncwait
 /usr/local/freeswitch/bin/fs_cli

If FreeSWITCH is already running and you update mod_sms_flowroute configs, apply those changes in fs_cli with:

 reloadxml
 reload mod_sms_flowroute

Receiving Messages with mod_sms_flowroute

The default chatplan in the FreeSWITCH configs is where you can specify what action you want FreeSWITCH to take when a text is received on one of your Flowroute DIDs. Opening chatplan/default.xml shows a template that can be easily modified, similar to a dialplan extension. The "reply" action automatically sends a response to the sender. Let's add an info application as well.

 <?xml version="1.0" encoding="utf-8"?>
 <include>
   <context name="default">

     <extension name="demo">
       <condition field="to" expression="^(.*)$">
         <!-- <action application="lua" data="test.lua"/> -->
         <action application="info" />
         <action application="reply" data="Hello, you said: ${body}"/>
       </condition>
     </extension>

   </context>
 </include>

If left as "^(.*)$", FreeSWITCH will perform the action(s) that follow for texts to all recipients. This can easily be changed to apply texts to a single DID, or to a particular area code, etc. The line that is commented out demonstrates how to tell FreeSWITCH to run a lua script on receiving a text to a particular recipient. The template includes an "info" application, which prints information about the message to the FreeSWITCH console, fs_cli.

In fs_cli:

 reloadxml

Next, let's update the chatplan to run a simple lua script that grabs a few fields from the message and prints them to the FreeSWITCH console. We will call it parse_message.lua and place it in the FreeSWITCH scripts directory (/usr/local/freeswitch/scripts since we installed from source).

 local sender = message:getHeader("from");
 local recipient = message:getHeader("to");
 local body = message:getHeader("body");

 freeswitch.consoleLog("INFO","Message received from " .. sender .. " to " .. recipient .. "\n");
 freeswitch.consoleLog("INFO","Message body: " .. body .. "\n");

NOTE: the message headers are stored under the lua global variable "message" not "event."

If you are using emacs-nox as your text editor, you can make lua scripting easier by running:

 apt-get install lua-mode

Now, with a little rearranging and removal of the "reply," the chatplan demo extension now looks like this:

 <extension name="demo">
   <condition field="to" expression="^(.*)$">
     <action application="info" />
     <action application="lua" data="parse_message.lua"/>
   </condition>
 </extension>

To apply, open fs_cli and enter the command:

 reloadxml

Our fs_cli output now looks like this:

Now that you have access to the header fields of the text in the lua script, you can do anything you like with that data. You can insert it into a database, pass it as a parameter to a separate API, or generate an outbound sms to deliver it to a new recipient.

Sending Messages with sms_flowroute_send

Use this API and format for sending an outbound SMS from fs_cli, remembering that the sender/source must be one of your Flowroute DIDs:

 sms_flowroute_send <sms_flowroute_profile>|<recipient>|<sender>|<message>

If the above format is not used, the message will not send and will print:

 [ERR] mod_sms_flowroute.c:517 Invalid format. Must be | separated like: profile|destination|source|message

You can generate SMS messages from the dialplan as well, useful if a bridge is not answered or you want to send out auto-alerts via SMS.

 <action application="sms_flowroute_send" data="profile|destination|source|message"/>

Replies and Relays

You have already seen how to reply direclty in the chatplan. To send a reply from the parse_message.lua script used above, add the following API lines after you've parsed the message:

 local api = freeswitch.API();
 -- format: sms_flowroute_send profile|destination|source|message
 -- since it is a reply, use the original message's Sender as the destination
 ---- and the Recipient (your Flowroute DID) as the source
 api:executeString("sms_flowroute_send default|" .. sender .. "|" .. recipient .. "|Message received.");

You can also implement a relay of sorts to pass the original text message along to an alternate number:

 -- for a relay, keep the original Recipient as the source and add a new destination.
 local new_destination = "12535551234";
 api:executeString("sms_flowroute_send default|" .. new_destination .. "|" .. recipient .. "|" .. body);

Conclusion

You should now have a basic understanding of how to use mod_sms_flowroute to integrate your Flowroute SMS capabilities with your FreeSWITCH platform, though the applications go far beyond what was covered in this short article.