Messaging on the TextMarks platform operates around the concept of keywords. You'll want to register a keyword for your use by creating a TextMark. Register a new TextMark (click on this link, or the link in the site's footer). You should create one of the type "Respond to a keyword with text from a web page".

When users send a text message to 41411 starting with your keyword (or subsequent contextual multiple choice responses without a keyword), our Text Request Proxy Server will make an HTTP request to the URL you specify. The URL should either reference an existing HTML web page (in which case the clipping feature is useful), or should reference a script written specifically for processing these TextMark requests.

You can include special variables in the 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".

Additional less commonly used special variables are available for more advanced developers:

• \u - replaced with a unique numerical identifier for the user's phone, e.g. "4789234".
• \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 Developer Management Extension.

A common template for dynamic URLs looks like:

To return (respond with) content from an existing web page, you should use the text clipping feature in conjunction with the preview buttons to identify and specify the text you wish to respond with.

You may find it helpful to temporarily include explicit text on the URL rather than dynamic variables (e.g. \0) for testing purposes.

To handle text requests programmatically (i.e. rather than scraping web content), you can write a script or servlet in any language and host it on any publicly accessible server. Your script will capture the user's request via HTTP GET parameters using the dynamic variables mentioned above.

Your script should parse the request, perform whatever actions are indicated, lookup whatever data is requested, and return raw text that you wish to send back to the user as a text message. (Or return an empty HTTP 200 response to skip the text response). Yes, it's that easy!

When you have your script up and running on your server, you should make sure the correct URL is associated with your TextMark in the "TextMark Response" panel on the management page.

Your script must complete its processing and return a response within a few seconds, or the callback will terminate and an error will be shown. If you require more time for processing, consider queuing the request and using the XML-RPC API to send a response later.

There are numerous ways of testing your TextMark. Using the TextMarks simulator (available on the TextMarks home page), you can simulate mobile requests and observe the responses.

Since your custom scripts operate just like regular HTML form processors, you can even write an HTML form to submit the same data you're expecting to your script and test without invoking the TextMarks system at all.

And of course, why not just test from your own phone!

If you find your TextMark isn't working as expected, you can always edit it using the TextMarks management console by clicking on the "Manage" tab in the nav bar above.

If you are providing multiple options for users via your keyword or are expecting users to make multiple sequential queries, you may wish to take advantage of an advanced feature of the TextMarks platform called "Contextual Response Handling". With this feature, users no longer need to start messages to 41411 with your keyword.

Any time a user requests your keyword (or receives an alert from you), your keyword takes over that user's context. Until another keyword knocks yours out of context, short contextual responses from that user will be delivered to your keyword.

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 the Text Request Proxy Server 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 appropritaely.

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 TextMark. If you'd like more help or a starting code template, feel free to view the STATEINFO Example Source Code.