A Conversation About Conversations

David Pitt JavaScript, Keyhole Creations, Mobile, Node.js, React, Technology Snapshot Leave a Comment

Just about everyone has a mobile phone; the vast majority have smartphones with the ability to install and use mobile applications. iOS and Android app stores are choked with applications. With a handful of top-100 exceptions, most applications have very few downloads — if they have a lot of downloads, it’s more likely than not that they don’t live long on a user’s device before they get deleted or replaced by another application.

Also, building installable mobile applications can be expensive, and in many cases too much functionality is added to maximize the effort of uploading to an app store. Then you have to get users to download and install, and there are only so many apps user can have installed on their devices. I often wonder why some companies, such as a credit score company thinks users would clutter up and use valuable storage space for a credit score app. Maybe users will download, use, then delete, but developing mobile apps are not cheap.

So, what would you say is the most universally popular mobile application? My answer would be the SMS (Short Message Service) or text messaging applications. It’s kind of the original Twitter, since the protocol is limited to 160 characters, before being broken up into multiple parts. Next time you’re out and about, look at how many peoples’ heads are down looking at their mobile device; the app they are using, most likely text messaging.

This Post

Why conversational applications are handy, examples of conversational applications we have created, and a walkthrough of the application architecture used to develop those SMS applications. Includes how to make texting a richer experience, state, and session handling insights.

SMS Conversational “Apps”

This is why we created a platform that supports developing a “conversational” type application through SMS. Organizations can use this capability to provide utility features to existing applications.

The user experience between a user and an SMS application can be thought of as a conversation. A user texts a question or topic, and a reply is returned, then another question and reply is performed until a desired result is accomplished.

Now, this is not a universal user experience, but for many use cases it can provide an easy to deliver users functionality quickly and conveniently. There is no need to install or download apps, or pop open a browser and type in a URL; just have a conversation through your texting app. Which you probably do many times a day, so you don’t require user training.

Example Apps and Conversations

Before I get into the application architecture, let me first introduce a couple of example conversational applications we have created and use here at Keyhole Software.

We have established a dedicated number for our text message application capabilities: 913-270-0360.

Tip Calculator

Text “tip 49.95” and a tip percentages with totals will be returned.

Text “tip 49.55” to 913-270-0360
Phone Numbers

Keyhole employees can text to obtain employee phone numbers, which has turned out to be very convenient. The architecture can authenticate a valid phone number, so non-employees can’t get phone numbers.

Fly Fishing Knots

My hobby is fly fishing, so we created a application that allows users to get images on how to tie common fishing knots. This example introduces how a mobile web app can be introduced into the conversation. Select the type of knot and you will be provide a link that when touched will display a graphic on how to tie.

Text “knots” to 913-270-0360
Metric/English Conversion

Text utility that converts numbers from Metric to English units and vice versa. In doing so, it also, provides access to a mobile web user interface.

Text “convert 125.55” to 913-270-0360

These are just a couple of ideas for text message application utilities. There are all kind of other possibilities for enhancing application with text messaging features. Now the application architecture behind this SMS platform will be walked through.

Application Architecture

Our SMS application platform is named khs-convo. It is built upon both client side and server side as JavaScript, React.js and Node.js respectively. The data store is a NO-SQL base is MongoDB and we use Twilio for SMS support. A diagram is shown below.

SMS messages via Twilio access an API HTTP post command with a text message from a phone. khs-convo performs a weight regular expression search against all the SMS event handlers that are defined. Event handlers are implemented as JavaScript Require.js modules.

Here’s an example event definition of the tip event:

module.exports = function (events) {

   var event = {};
   event.isAuth = false;
   event.description = "Tip Calculator";
   event.words = [{
       word: 'tip',
       value: 10
       word: 'tips',
       value: 10
   event.threash = 10;
   event.run = function (result) {

       var tips = "Bill Amount Please, example... \n tip 100.00";

       return new Promise(function (resolve, reject) {

           var decimal = ".00";
           if (result.question.length > 1) {

               if (result.question[1] > 2  ) {
                     decimal = "."+result.question[2];
               console.log(result.question[1] + decimal);

               var amount = parseFloat(result.question[1] + decimal);
               if (!amount) {
                   tips = "Use a number please, example...\ tip 100.00";
               } else {
                   var fifteen = amount * 0.15;
                   var twenty = amount * 0.20;
                   var twentyfive = amount * 0.25;

                   tips = "15%  = " + fifteen.toFixed(2) + " ($"+ (amount + fifteen).toFixed(2) + ") \n";
                   tips = tips + "20%  = " + twenty.toFixed(2) + " ($" + (amount + twenty).toFixed(2) + ")  \n";
                   tips = tips + "25%  = " + twentyfive.toFixed(2) + " ($" + (amount + twentyfive).toFixed(2) +")\n";


           return resolve(tips);




Events define an array of word objects that provide a “word” to match on and a weight for relevance. This allows an actual word to be entered and matched, or for a term to be picked out. Also a run function is defined that executes the event logic, the case above calculates the tip amount for the supplied amount.

The framework supplied the text message question the user entered from their text application, which comes through the Twilio API. Results are returned via a Promise which khs-convo uses the JavaScript Twilio API to return to the user.

Finite State Machine

Consider the process of responding to a question or word supplied by a user, then replying with a series of choices for the user to input. It is generalized into a series of states that a specific khs-convo event goes through until some of the result is displayed to the user.

The tip utility does not have multiple states defined, it just accepts a single command of tip with a numeric value argument. So, let’s look at the English/Metric conversion Convo Event where a set of states are defined.

The conversation app will prompt for a number to convert, then ask a question to convert to Metric/English. Based upon the reply, the conversion will be displayed.

Here are the states that are defined in the conversion khs-convo event module.

module.exports = function (events) {

   var event = {};
   event.states = [
       { reply: 'Number to Convert?', validator: 'number', desc: 'Number' },
       { reply: '(E)nglish or (M)etric?' , validator: 'choice:E,M', desc: 'Choose English or Metric' },
           { choices:[ { choice: 'e', reply: 'Unit of Measure in Metric Units? '+metricunits(), validator: validUom } ,
                       { choice: 'm', reply: 'Unit of Measure in English Units? '+units(), validator: validUom}] },
       { reply: convert }

   event.isAuth = false;
   event.description = "Metric/English Conversion";
   event.words = [{

Notice the first states prompts and validates a number to be input.

     { reply: 'Number to Convert?', validator: 'number', desc: 'Number' },

The next state prompts for an (E)nglish or (M)etric choice. This state is followed by a choices state that will capture a unit of measure (i.e. inches, feet, centimeters, kilometers, etc) that the input number is in, so a conversion to the corresponding unit can be determined.

  { reply: '(E)nglish or (M)etric?' , validator: 'choice:E,M', desc: 'Choose English or Metric' },
      { choices:[ { choice: 'e', reply: 'Unit of Measure in Metric Units? '+metricunits(), validator: validUom } ,
      { choice: 'm', reply: 'Unit of Measure in English Units? '+units(), validator: 

The final state will use the number input and the unit of measure and perform and output the converted number.

  { reply: convert }

The framework’s generalized state machines simplifying implementation of requesting and validating input.

Session Handling

Text input for each state is persisted in a MongoDB session collection by a user’s phone number. The current state, along with all state input data, is stored in a JSON document until the last state is executed. Then it is removed. This makes the server framework stateless allowing it to be restarted and scaled.

Here is a screenshot of the English/Metric state session object:

The framework automatically stores this state information based upon the phone number supplied by the text messaging API.

Make Texting a Richer Experience

The text messaging applications can be enhanced by delivering a URL that renders a web-based HTML user interface to provide a more dynamic, rich user experience. The English/Metric conversion event will provide a link to an HTML user interface that allows users perform different unit of measure conversions.

This provides an improved mobile experience without having to build a native mobile application. Also, this allows more directed and smaller feature/function that can be delivered and tested quickly. New versions don’t have to be uploaded to app stores and users don’t have to download upgrades. Also, domain names don’t have to be registered and server infrastructure set up. A single khs-convo instance can serve multiple SMS events and HTML UIs.

The khs-convo framework has a generalized way to quickly build and produce an HTML interface for text messaging event. Event definitions can implement an html() function that utilizes the PUG templating framework to produce an HTML user interface. The framework senses this method definition; and if the user texts a “U” for User interface, a link will be produced to a dynamic HTML.

You can see this working by texting “knots” to 913-270-0360.

Then, if you enter a U, a UI link will be returned. Clicking the link opens the following HTML interface up in your browser.

Here is the PUG template for the KNOTS UI. It essentially is provided a JSON structure of KNOT images and descriptions and renders the above HTML. I like the way PUG minimizes HTML templates.

//- knots.pug
doctype html
 title Knots
 style (rel='stylesheet',href="https://maxcdn.bootstrapcdn.com/bootstrap/latest/css/bootstrap.min.css")              
 each val in knots
         h1 #{val.desc}
       img(src= url+val.image width="800" height="700")

This technique merges the ubiquitousness of text messaging a rich user interface, and can provide a quick and easy way to deliver mobile functionality and enhance applications with alternative ways to interact with them.

Administration User Interface

We also created an administration dashboard using React. The dashboard captures and graphs user analytics, manages user authentication, blacklists, and provides an Emulator.



More Conversations…

The limit to how SMS text messaging can be merged with small mobile browser applications is limited only by imagination.

We are in the process of adding the ability for employees to quickly add and manage their time with our timesheet application through SMS. Other ideas such as gathering information in order to provide quotes for insurance , providing account balances, or reporting shipping information, order numbers, or monitoring wait queues are all use cases that a text messaging feature could add value and convenience to our users.

If you would like a demo or to find out more about our khs-convo SMS platform, give us a shout.

About the Author
David Pitt

David Pitt


David Pitt is a Sr. Solutions Architect and Managing Partner of Keyhole Software with nearly 25 years IT experience. Recent projects involve speaking, writing, and training developers in enterprise JavaScript​/single-page application​ development best practices​, as well as the development of GrokOla, the Q&A-based wiki software​ for development teams.​

Share this Post

Leave a Reply