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!

NOTE: You may wish to test your keyword at this time using the basic "Automatic Response" feature (in the keyword's "Settings" menu). Enter a message there, and when you text your keyword to 72345 (or whatever number it is associated with), you'll get the message sent back to you automatically. For dynamic automatic responses, read on.
NOTE: Keywords have "auto-subscribe" enabled by default to automatically add every user who requests them to a "group" (which you can later broadcast text messages to). This feature also results in users receiving an extra welcome message back the first time they request your keyword. If you don't want this, you can disable it in "Group Membership" settings.

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.

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:

\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.

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?

Features

SMS Auto Responders

SMS Sending API

Advanced Deep Integration
Capture text messages sent by users

Yes

No

No

Send individual text messages to users

Yes

Yes

Yes

Send mass text messages to users

No

Yes

Yes

Compliance
SMS Auto Responders
SMS Sending API
Advanced Deep Integration
Fully carrier and TCPA compliant

Yes

Yes

Yes

Phone# list uploads allowed

N/A

No

No

Pricing
SMS Auto Responders
SMS Sending API
Advanced Deep Integration
Free version?

Sorry, we offer a paid service only

Sorry, we offer a paid service only

Sorry, we offer a paid service only

Billing

Easy automatic monthly credit card billing

Easy automatic monthly credit card billing

Easy automatic monthly credit card billing

Price

Pricing plans starting at $199/mo

Pricing plans starting at $199/mo

Pricing plans starting at $199/mo

End users pay?

Msg & data rates may apply, but service is otherwise free to end users

Msg & data rates may apply, but service is otherwise free to end users

Msg & data rates may apply, but service is otherwise free to end users

Integration
SMS Auto Responders
SMS Sending API
Advanced Deep Integration
Technical Challenge

Easy

Medium

Hard

Can Be Used Without API Key

Yes

Yes

No

Works with other TextMarks services

Yes

Yes

Yes

Easy web-based admin UI and reporting

Yes

Yes

Yes

Can be used without client library?

Yes

No

No

Client libraries available

Yes

Yes

Yes

More Info
SMS Auto Responders
SMS Sending API
Advanced Deep Integration
All Major U.S. Carriers Supported

Yes

Yes

Yes

International Support (Non-U.S.)

No

No

No

High volume support

Yes

Yes

Yes

Rapid rate support

Yes

Yes

Yes

99.9% uptime guarantee

Yes

Yes

Yes

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.

Want us to set up a demo for you? Call us at:

(800) 696-1393