Text Message Request/Response API
(“SMS Auto-Responder”)

Overview / How it Works

1. A user sends a text message to an SMS short code (like 72345) beginning with your keyword.
2. TextMarks makes an HTTP request to your server with the message.
3. Your server looks up/records information and responds.
4. TextMarks sends your response back to the user as a text message.

Getting Started

If you don't have an account yet, you can Contact Sales here.

TextMarks provides access to SMS short codes (like 72345). Mobile phones can send to and receive text messages from short codes just like regular 7 or 10 digit phone numbers, but short codes are easier to remember and use.

To identify your application or campaign on a short code, register a keyword for your users to use when texting the number (e.g. to 72345). Your keyword is a bit like a domain name and should be short and meaningful. Some examples: CTABUS, JMCYOUTH, DALIS, KERNSON4TH... (You could tell people to "Text JMCYOUTH to 72345")

To register your keyword, make sure you're logged in to www.TextMarks.com. Then go to your dashboard and click on the "Make New Group" button, type in your keyword, and assuming it's available, it's yours!

Next go to the API Settings panel for your keyword:

Click to view image

Here you'll activate API functionality on your keyword and provide the callback URL to your script that TextMarks will contact via HTTP on each inbound message:

Click to view image

In the next section, we'll walk through writing just such a basic callback handler script.

Writing your Callback Handler Script

TextMarks Text Message Request/Response API makes an HTTP GET request to your callback URL for each incoming text message that begins with your keyword. In this section we'll discuss how to write your callback script so you can get information (e.g. the user's phone#, the message she posted) and respond such that the user receives a text message back.

We're using PHP here for examples, but you can of course write your callback scripts in whatever language and environment you're comfortable with.

Whatever text (HTML encoded) you respond with will be sent back to the user as a text message, and if you don't want to send any message back, simply give an empty response. So let's start with the most basic callback script -- an HTML file!

We can accomplish the same thing by using PHP's echo to write text:

That's boring. Let's echo back the user's request. In our callback URL, we can use standard HTTP query parameters that are replaced at runtime. The value \0 (backslash zero) is the most common and will reveal the user's entire SMS request. If our script was at https://my-server.com/script.php then let's add the request message as a query parameter "msg" (call it whatever you want) by providing the callback URL in your keyword's API settings as:
https://my-server.com/script.php?msg=\0 Our callback script might look like this:

With a keyword "KEYWORD", if the user texted "keyword hi there" to 72345, they would quickly receive a text message back saying: "You said: keyword hi there".

Now maybe we want to identify the user and return information specific to her or even log the request associated with her phone number. Let's add the \p parameter to the callback URL: https://my-server.com/script.php?msg=\0&phone=\p. Here's an example of how a more complicated callback script might integrate with your back-end database and application layer:

Now that you see how easy dynamic text message auto-response can be, try it out yourself. You should be able to get a basic interaction up and running in just a few minutes!

Advanced: Contextual Responses

Because multiple campaigns may be running concurrently on the same short code, users typically need to start each message (e.g. to 72345) with your keyword to uniquely identify your application. But this can be cumbersome and repetitive. So to provide for a better user experience, TextMarks allows certain text messages ("contextual responses") to be automatically routed to the last keyword the user interacted with (either requested explicitly or received alert from):

Short contextual responses are defined as: i) single numerals 0-9; ii) single characters A-T (upper or lower case); iii) double characters containing any of A-Z (upper or lower) and 0-9; iv) the words "TRUE" and "FALSE"; v) 5-digit sequences (US zip codes). vi) e-mail addresses.
Some examples: 1, 4, CA, SF, X7, B, F, TRUE, 94117, myname@somewhere.com.

An example of how this feature might be used for a dating site would be to have a keyword FINDADATE that returns a profile summary of a random match for you (e.g. identified by your phone#, assuming you already have an account). The response might say:

"JenLuv717" is a match!
24yrs, in Palo Alto, likes tennis, movies.
Rply H to hotlist, N for next.

When the user replies "H", your keyword is assumed and TextMarks will contact your server as if the user had requested "FINDADATE H". Assuming you recorded the match you originally responded with, you would then recognize the user (e.g. by phone number) and act upon their new request.

TextMarks doesn't care about what your options are -- it's up to you to present a menu/multiple-choice as you see fit and process the responses appropriately.

The e-mail and zip code contextual responses are useful for the common cases where you want to ask a user to reply with their zip code (such as to narrow a search) or e-mail address (such as to register them).

There is a working demonstration of this functionality in the STATEINFO keyword (text STATEINFO to 72345 to try it). If you'd like more help or a starting code template, take a look at the STATEINFO Example Source Code .

Advanced: Other Parameter Substitutions

In addition to the \0 and \p parameters we already covered, you can include other special variables in your callback URL that get substituted with information about the request:

Very Advanced: Cryptographically Signed Requests

You may optionally specify a secret token (in your keyword's API settings page) to request TextMarks servers to digitally sign callback requests. This allows your servers to verify that requests actually came from TextMarks and are not spoofed by users who somehow obtained your callback URLs.

The string resulting from URL parameter substitution of \k\p\t (raw, not in URL-encoded form) is processed to generate a keyed-Hash Message Authentication Code (HMAC) digest by using the MD5 hashing algorithm with your private token as the key. This key is made available to you in the \s signature parameter.

Most modern languages have libraries available to perform this same hash on your side. In PHP, see the hash_hmac() function. In Python, see the hmac module.

Which TextMarks SMS API Is Right For Me?

Have questions? Ready to start?

Sign up today for a free trial and experience the power and simplicity of the best text message API you'll find.