1. A user sends a text message to 41411 starting 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.
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!
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 41411, you'll get the message sent back to you automatically. For dynamic automatic responses, read one.
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.
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.
\0 (backslash zero) is the most common and will reveal the user's entire SMS request.
If our script was at
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
to the callback URL:
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, email@example.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
\p parameters we already covered,
you can include other special variables in your callback URL that
get substituted with information about the request:
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.
Sign up today for a free trial and experience the power and simplicity of the best text message API you'll find.