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

If you don't have an account yet, you can sign up for a free trial here.

TextMarks provides access to the shared shortcode 41411. Mobile phones can send to and receive text messages from shortcodes just like regular 7 or 10 digit phone numbers, but shortcodes are easier to remember and use.

To identify your application or campaign on our shared shortcode, register a keyword for your users to use when texting 41411. Your keyword is a bit like a domain name and should be short and meaningful. Some examples: CTABUS, JMCYOUTH, DALIS, KERNSON4TH... (You would tell people to "Text JMCYOUTH to 41411")

To register your keyword, make sure you're logged in to www.TextMarks.com. Then click the "Manage Keywords" tab, then click the orange "Create" button, type in your keyword, and assuming it's available, it's yours!

Next go to the API Settings panel for your keyword:

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:

In the next section, we'll walk through writing just such a basic 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 http://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:
http://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 41411, 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: http://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!

Because 41411 is a shared shortcode with other customers providing their own services at the same time as yours, users typically need to start each message to 41411 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 41411 to try it). If you'd like more help or a starting code template, take a look at the STATEINFO Example Source Code.

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:

• \p - replaced with the user's canonical phone number, e.g. "+14151234567".
• \0 - replaced with all of the text following your keyword in the message, e.g. \0 will become "this is a test" from the message "YOURKEYWORD this is a test".
• \u - replaced with a unique numerical identifier for the user's phone, e.g. "4789234".
• \n - replaced with the user's name (if known), e.g. "Jim Jones".
• \1 - \9 - replaced with the corresponding words following your keyword in the message, e.g. \1 will become "this" from the message "YOURKEYWORD this is a test".
• \k - replaced with the TextMark keyword requested, so you can serve multiple TextMarks with the same script, e.g. "MYKEYWORD".
• \a - replaced with the action identifier, "REQ" for regular requests.
• \t - time of request, in seconds since epoch (time_t format).
• \s - hash digest of message, for verification. See Cryptographically Signed Requests for more information.

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.

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