Using SMS Short Codes And TextMarks To Send Text Messages With ColdFusion
Last night at the New York ColdFusion User Group (NYCFUG), Aaron Foss gave a presentation on using SMS short codes with the free service, TextMarks, to integrate text messaging into your ColdFusion applications. It was a really good presentation and one that inspired me to come home and immediately start trying out TextMarks (at least as a place to start). I don't have any great ideas for SMS integration at this point; but, it looked so easy, I had to give it a go.
Basically, TextMarks provides a shared short code - 41411 - that all members of the site must use. To differentiate one member service from another, you need to select a keyword. This keyword then must be sent with the text message as the first piece of data. So, for example, I obtained the keyword, "bennadel". As such, all users that want to access my services must send text messages that start out with "bennadel":
41411 >> bennadel ......
The "bennadel" keyword is just a routing device and is not part of the actual request data.
NOTE: The reason there are "shared" short codes is because having a dedicated short code is extremely expensive! I'm talking tens of thousands of dollars a year.
You don't actually have to put any of your processing on TextMarks. What TextMarks does is act as a proxy to your web-based application. When you create your keyword (routing value), you define a URL to which TextMarks should pass on the request as a GET post. You then accept the request, do whatever processing you need to do, and return a very simple HTML page. Here is a screen shot of the keyword setup form:
As you can see, very simple. For the keyword "bennadel," I defined the following URL:
http://www.bennadel.com/resources/demo/textmarks/index.cfm?smsdata=\0
In order to make the requests usable, TextMarks provides a number of variables that you can replace into your URL. So, for example, if you look at the URL that I provided, I am using the variable "\0". This \0 variable gets replaced with the entire request made by the user. There are a number of other variables available like Phone Number and unique ID, but for my testing purposes, the raw request was sufficient.
For my first SMS-enabled ColdFusion application, I kept it extremely simple: random number generation (do I know how to party or what?!?). Let's take a look at the page I have at the above URL:
<!---
Param the request data. In TextMarks, we are going to
set up "smsdata" to contain the "\0" data, which is the
entire request made by the user.
--->
<cfparam name="url.smsdata" type="string" default="" />
<!---
Now that we have the SMS data, let's break it up into
an array so that we can start to treat it like actions.
NOTE: I am using multiple delimiters because TextMarks
allows the user to use several different keyword delimiters.
--->
<cfset tokens = listToArray( trim( url.smsdata ), " ,*-" ) />
<!---
Now that we have the data collection, let's examine it to
see how we should process the given request. Of course,
before we start testing it, we have to make sure that at
least the first item exists.
--->
<cfparam name="tokens[ 1 ]" type="string" default="" />
<!---
Wrap the processing in a try/catch so if something does
go wrong, we can catch it and return a response.
--->
<cftry>
<!--- Check the first data item. --->
<cfswitch expression="#tokens[ 1 ]#">
<!---
The user wants to get a random value. For easy of use,
we are allowing the user to use any of the following
values to access this action.
--->
<cfcase value="r,rnd,rand,random" delimiters=",">
<!---
Now that we know we are in the "Random Number"
action, let's param our arguments.
--->
<cfparam name="tokens[ 2 ]" type="string" default="" />
<cfparam name="tokens[ 3 ]" type="string" default="" />
<!---
Check to see how many arguments the user passed.
To be simple, we will based this on the number of
numeric arguments they passed.
--->
<cfif (
isNumeric( tokens[ 2 ] ) &&
isNumeric( tokens[ 3 ] )
)>
<!---
We have both a lower and an upper limit to our
random range.
--->
<cfset randomValue = randRange(
tokens[ 2 ],
tokens[ 3 ]
) />
<cfelseif isNumeric( tokens[ 2 ] )>
<!---
We have only an upper limit to our random
range. As such, we will treat the lower range
as 1.
--->
<cfset randomValue = randRange(
1,
tokens[ 2 ]
) />
<cfelse>
<!---
We have no lower or upper limit on our range.
As such, we will assume that this person is
doing a boolean randomization between zero
and one.
--->
<cfset randomValue = randRange( 0, 1 ) />
</cfif>
<!---
At this point, we should have a randomly selected
value for the user. Create the reponse text.
Remember, we don't have to worry about white space
here as that will be cleaned later on.
--->
<cfsavecontent variable="responseData">
Random Value:<br />
<cfoutput>#randomValue#</cfoutput><br />
</cfsavecontent>
</cfcase>
<!--- ---------------------------------------------- --->
<!--- ---------------------------------------------- --->
<!---
The first argument that they passed was not
recognized by our system. Let's send back a default
instruction set.
--->
<cfdefaultcase>
<!---
When building the response data, don't worry
about leading / trailing white space - that will
be stripped out later on.
--->
<cfsavecontent variable="responseData">
Command list:<br />
rand<br />
rand N<br />
rand M N<br />
</cfsavecontent>
</cfdefaultcase>
</cfswitch>
<!--- Catch any exception. --->
<cfcatch>
<!--- An error occurred. Alert the user and. --->
<cfsavecontent variable="responseData">
Ooops<br />
An error occurred.<br />
Check your inputs.<br />
</cfsavecontent>
</cfcatch>
</cftry>
<!---
At this point, we should have a valid response in our
respondData variable. Now, we need to clean it up for
SMS response. Let strip out the extra white space,
including the leading / trailing line spaces.
NOTE: TextMarks will automatically take care of stripping
out our <BR /> tags and replacing them with text-valid
line breaks.
--->
<cfset responseData = reReplace(
trim( responseData ),
"(?m)(^[ \t]+|[ \t]+$)",
"",
"all"
) />
<!---
Convert the respond data into a binary variable so that we
can easily stream it back using CFContent without having to
be fanatical about clearing the content buffer.
--->
<cfset binaryResponse = toBinary( toBase64( responseData ) ) />
<!--- Set headers. --->
<cfheader
name="content-length"
value="#arrayLen( binaryResponse )#"
/>
<!---
Stream content back as HTML. By using the Variable
attribute, we are ensuring that no extra white space is
being passed back.
--->
<cfcontent
type="text/html"
variable="#binaryResponse#"
/>
As you can see, the above code produces a very simple HTML page. It's almost not even an HTML page at all; I call it HTML only because you can use the <br /> tags to define line breaks (TextMarks knows how to replace those with valid SMS-style line breaks).
Once the request starts, I take the raw request data submitted by the user and break it up into an array. Remember that your keyword ("bennadel" in my case) is not submitted as part of this request data - the keyword is simply a routing device used to point to the above URL. With the array of data in hand, I then check to see how the request needs to be processed. Because there is nothing on the TextMarks side that ties us to any particular type of request data, this URL can be used to handle all sorts of requests; in my example, I am randomly selecting a value, but, simply by using different CFCase values, I could start adding more functionality to this service at any time.
To show you that this is working, here is a screenshot of my iPhone:
As you can see, I texted "bennadel rand 1 100" to TextMarks. TextMarks, in turn, sent "rand 1 100" to my URL, and I returned the HTML page with the randomly selected value:
RandomValue:
59
As you can see, TextMarks put some ads at the bottom of the SMS response; this is just something you have to put up with if you want to use the free service. TextMarks offers Pro accounts that will get rid of the ads for a certain number of text messages per month.
You might ask yourself why not just use the CFMail gateways to send SMS text messages? There's nothing inherently wrong with doing that. However, those mail gateways are provided as a courtesy by the cellular carriers, and if you abuse them, they will have no problems shutting a particular address down. Also, monitoring an email inbox for SMS messages is not the easiest thing to do.
Right now, I don't have any really great ideas for adding SMS capabilities to my ColdFusion applications; but, knowing that these options exist plants the seeds for new ideas. I am sure I'll be looking into this service more deeply to see what other kinds of goodness I can get out of it's API.
Want to use code from this post? Check out the license.
Reader Comments
Hey great article Ben, I use outbound SMS all the time here using a similar kind of service but I've not really dealt at all with inbound messages to a short code like this.
Nice stuff, may have to get my thinking cap on as to the practical applications for this kind of thing.
Rob
@Robert,
Can I ask what you use for outbound SMS, if you don't mind sharing? I'm just curious and looking to learn more about this field.
I don't mind you asking at all.
Generally it's for keeping users involved with the application whilst they're away from their browser, see, our product is a tool which will only give the customer a decent ROI if they use it regularly and so getting them to adopt the product into their daily routine is right at the top of our priority list.
So, when a user first places an order with us we keep them upto date on the progress of the order with text messages, things like:
"Oh hey, our boffins have finished building your system, it'll be with you tomorrow morning."
and then once the service is up and running for them we use it as a continual prompt to use the service, we keep a track of how often they login to their account, if they haven't signed into the account for a week or so we send them a prompt saying we hope they haven't forgotten their password.
We also use it for reminders when they haven't been refreshing their campaign material or when they have overdue invoices ;-) On the most part these are things which 'could' be sent in an email but generally sending it to the users phone is a little more personal and they're more likely to read and take it on board, especially as you have the twitter effect of having to keep within a 160 character limit for a standard SMS, makes for very easy consumption.
Also, as we deal with mobile/cell content within the product we allow users to send MMS versions of their campaigns to their phones so they can quickly and effectively test the content to see how it renders on the screen.
I mean, perhaps I feel the value in this kind of thing more than others might due to the nature of my business and the fact that we're involved in the mobile marketing industry but I'm pretty sure most people could use it to great effect. In fact, British Telecom send me updates to my phone about billing and maintenance on my phone line quite regularly.
I know I've yarped on about my 'coming soon' blog but I've drafted a few articles about how we use these things to keep the user attached to the app whilst they're out and about, just so they don't forget about us :-) I'll get it up soon, promise.
Rob
I know this is more of a sms security issues but I wonder what possibilities there are for people to intercept your messages or mask the phone number. As I am in the middle of moving I think I will try to look into these afterwards.
@Robert,
Sounds very cool. I think keeping people involved in your apps is a most excellent thing and I agree that SMS is much more personal AND more likely to be read than email.
What service to you use to handle the SMS output?
@Daniel,
When you use the mail-gateways, there is basically no security. In fact, you could have the mail come from anyone you put in the FROM field.
When you use an online service, I am not 100% sure what is generally involved. When I signed up for TextMarks, they did send a pass code to my cell phone so that I could verify my account information before I finished setting up my "keyword" routing. So, at least they make sure you are a real cell phone user.
But, beyond that, not sure what other kind of measures are in place. I know that with the service I am experimenting with, you have no control over the To/From stuff since it all routes through the TextMarks proxy short code 41411.
Interesting post as usual Ben. I guess the carriers must not care too much what you do with the sms-email gateways (http://j.mp/eDznc), because I belong to a Google Group of well over 300 soccer players who no longer reserve fields in advance, but instead find and organize games on the spot by SMS'ing the Google group post address, which then distributes to email gateways to SMS everyone's cell phone.
@Ben, we use a bunch of different providers skipping back and fourth between them, the service they provide all seems to be pretty much the same.
http://www.txtlocal.co.uk/ have always been pretty good in the past, although they're a UK only service. Most of these providers give you a bunch of different ways to integrate with the service, REST and SOAP web service, email (shudder) and a bunch of others too.
One interesting point to make is that international services are very tough, all the aggregators I've found here won't let me send content to our customers based in the US as they have a totally different and apparently much more strict legal system around what and to whom you can send through their service. And likewise, the US aggregators won't let us set up an account with them as we're based in the UK.
Rob
@Jason,
Sounds like also have a cool setup over there. As far as whether the carriers care or don't care, I can't speak from experience. I can only pass on what I hear at BarCamp - those more versed in the SMS world said that using the mail carriers had risk since they could be shut down for abuse.
However, last night at the CFUG meeting, someone also said that they worked at a non-profit that contacts the cellular carries and got special permissions to use the mail gateways without issue and it was granted. So, I suppose it can be used quite dependably at that point.
@Robert,
Yeah, I gathered that from the meeting and from a bit of reading. It seems that every continent has their own way of doing things and their own rules.
@Ben,
I didn't think they were very secure in a way you could send private information. I guess more what I was thinking was could someone send a message and make the system think it was from another phone number so the response would go to that other number.
I would assume it is possible
@Daniel,
That I don't know about. I would also assume it's possible, but I don't know the details.
@Ben, great blog post. May we feature this on our TextMarks blog? Also check out "Contextual Responses" here, which you can use for multi-step request/response interactions that don't require the keyword to be sent on each request (e.g. you could reply back with "r 1 100"):
http://www.textmarks.com/dev/docs/recv/
@Daniel (re security): You can read about how our shared-secret signed request feature prevents spoofing here: http://www.textmarks.com/dev/docs/devext/
@Jason et al (re email gateways): E-mail/SMS gateways are notoriously slow, unreliable, subject to change, and intended for low volume use only. They also typically add all kinds of ugly header garbage on the messages, leaving you with very little room for content and a human-unfriendly message. TextMarks offers a clean, reliable, fast SMS-native conduit.
Note also that in addition to request/response SMS interactions (as covered in this blog post), one of the main uses of TextMarks is large group communications: one-to-many, many-to-one, and many-to-many. These services are available easily through the site, without writing any code.
In the other direction, we also offer a very robust API for more advanced integrations. If anybody in the CF community would like to port our lightweight API client to CF, we'd be happy to include it on our site. Currently we have PHP and Python clients, eg:
http://www.textmarks.com/dev/docs/api2client/php/
--
Dan Kamins
CTO, TextMarks
@Dan,
Yes, absolutely, please feel free to post this on your blog. As far as the API stuff, I got my developers API key last night, but have not had time to start playing with it.
Hey guys, Aaron here, the guy that did the presentation at NYCFUG. Glad I inspired you, Ben. I'm looking forward to seeing what everyone else comes up with. I'm going to look into the advanced API too...maybe then I can give an 'Advanced SMS Integration' presentation :)
@Dan
Great service! Keep up the good work. I've been a big fan for quite a while. I did the LIRR keyword - http://www.textmarks.com/LIRR - and it's just been a great tool for a lot of people.
@Aaron,
Yeah, definitely good stuff. I hope everyone else enjoyed your talk as much as I did.
Last night, I started playing around with the contextual requests and made a proof-of-concept Blackjack game that allows Yes/No type responses to play the game:
www.bennadel.com/blog/1705-Using-Contextual-SMS-Short-Code-Messages-With-TextMarks-And-ColdFusion.htm
I agree with most of the comments, but how long do you think SMS Marketing is going to last with the iPhone and applications. Short Code Services have been increasing in usage but I think it might be tapped out. One thing to remember is that millions of people don't have the advanced phones, but how long before they will?
@Ryan,
There are several people that I personally know that want nothing to do with a smartphone. So there will always be the people who will have the ordinary phone.
Ben, I have seen both your posts using CF and textmarks. I wanted to find out if you, or anyone you know had done any serious development using their API directly yet.
I know they offer quite a bit of functionality without needing the API, but I may be looking at some further development with them and I was curious as to how anyone else has fared with them . . .
thanks again for the great posts.
@Paul,
I have not fooled around much more than this. I did get an API key, but have not had much time to kick it around yet. When I do, I will certainly blog about it :)
Glad to run across this post, once again Ben, you are my never-ending source of great CF material! This saved me having to figure out a couple steps myself as I'm actually in the process of building an SMS plugin for a client to use with their restaurant site so a user can order from the menu just by texting the keyword, receiving a list of their favorites, and texting back the number of their selection. These types of uses are ideal for SMS because it saves tons of time for a busy person that doesn't want to have to bring up their web browser, browse to the site, logon to their account, pick their item, complete the checkout process, etc. when they can do it through a text message in seconds. You can validate the user just by matching their cell number which is provided by the API (TextMarks also provides an encryption key to help prevent spoofing). I'm not sure how much the idea will catch on, but I do think the potential is there once people start to use it. I know I could get too easily addicted to being able to order my favorite pizza with a simple text message. ;-)
@Mary,
Sounds like a cool idea. To be honest, I didn't there that there was / would be much use for SMS, especially with so many smart phones out there. But, at the last RIA Unleashed conference, I talked to a guy who does a lot of SMS work and he said that that market for SMS-based apps is in the millions and millions of dollars! It totally changed the way I felt about it. Isn't that wild?
It might be some time before the mass market is primarily smartphones...right now they are still considerably more expensive not just for the initial purchase, but certainly monthly costs as well. There may be some generational issues as well, certainly for many of us, text messaging wasn't something we grew up with, so it isn't our first thought when it comes to conducting a business transaction. Not so with the kids coming up, text messaging is something they use heavily and are comfortable with.
Development costs are certainly hugely different as well. An app has to be developed for multiple platforms if you want it used across the board...iPhone, Windows Mobile, Nokia, Palm, Symbian, etc. With SMS, it's just one standard that works for all phones. That's a huge cost savings.
Having finished my SMS app, I'm impressed with how easy it was to do. I definitely will keep it in the back of my mind as an option for other clients. And it does have a bit of a "cool" factor too, everyone that demos our SMS app loves it....it will of course remain to be seen if they actually USE it!
@Mary,
Another thing to consider is the mode of interaction. With a smart phone and an App, people have to actively engage the app. With text messaging, however, they get *interrupted*. I think people are more likely to interact when interrupted rather than when having to be proactive.
I'm continuing my exploration of SMS/Voice Driven Apps with a presentation this Tuesday at the NYCFUG: http://www.nycfug.com/Meetings.cfm#NextMeeting
@Aaron,
This is very exciting. Really looking forward to tomorrow!
it only has a free trial
@Marcus,
It looks like their pricing model must have changed. It used to be Free with ad-supported messages (ie. there was a huge ad at the bottom of your SMS). They must have changed it to be more in alignment with things like Twilio which offers a pay-as-you-go model (3 cents / SMS).
Twilio charges per message. TextMarks chargers per user (or groups of user) with unlimited messages). Two different approaches; but , at the end of the day, you still got to pay someone, somehow.
Thank you:)
The pricing model in Egypt actually is regulated by the NTRA i.e. the telecom regulatory
the maximum is 5 LE which is really low for subscription services.
MT is only allowed for operators branded services
how to used this code
Anyone know a reliable sms gateway and sms short code service in UK?
my sms text# +639192616111---textonly .NO CALLING
SUMMER S.
A.C PH
Assalam U Alaikum All!!!!
Please visit below mention site.
https://www.eocean.pk
Assalam U Alaikum All!!!!
Please visit below mention site.
https://www.eocean.pk
Eocean is a leading Mobile Value added Services company that provides comptetitive edge to enterprises by blending the power of mobile communication technology with mobile/web applications." http://www.eocean.pk/