mdata from Mobile Commons enables organizations to make any data accessible to the public via text message, no programming required.

Transcription

1 mdata Web Services mdata from Mobile Commons enables organizations to make any data accessible to the public via text message, no programming required. How it Works 1. A user sends a text message with a keyword and/or a search term to a short code, such as The text message is delivered through the wireless carriers network to Mobile Commons. 3. Mobile Commons instantly processes the text message and sends a request to your web server. 4. Your web server processes the request and sends a response back to Mobile Commons. As a Mobile Commons customer, this is the only part of the process you need to create Mobile Commons automatically does the rest. 5. Mobile Commons gets the response, formats it into 160 character text message(s), and sends the response back to the user. 6. Moments after sending the initial text message, the user gets a text message response with the answer. No additional programming is required, and if you already have the web page up and running, it can be set up in minutes. Technical Details mdata was designed to be flexible enough to work with a new web service, or any existing legacy web services, whether it returns XML, JSON, or just plain text. Response Formats Your web service can send data back to Mobile Commons in 3 ways: 1. Plain Text: if your web page just returns text, we'll just read it and send it back to the user's handset, intelligently splitting it up into separate 160 character messages if necessary. 2. Structured Data: Your web service can return structured data such as XML or JSON. In this mode, you can edit a template that tells us how to interpret the XML/JSON and turn it into a response. Mobile Commons will parse the data, apply the template, and send the response to the handset. 1

2 3. A blank response: If you send back a blank HTTP body, we won't send anything to the handset. This is useful if your web service is very slow to generate a response or if a human manually writes the responses. Typically this mode is used in conjunction with our API to send messages. Figure 1 Easily specify the URL, HTTP request method, and response format through our web interface If your web service returns structured data, we support the Liquid Markup Language ( to compose the response messages. Liquid enables you to take your structured data and optionally apply filters, loops, and if/else logic to turn it into a friendly customizable text message. Simply edit your template directly in our web interface and we'll take care of the rest. Full documentation is available here: Figure 2 mdata Supports the Liquid Template Language for Composing Sophisticated Responses 2

3 The HTTP Request mdata was designed to work with legacy web services with no development required. Using our web interface, you can specify all the details of the web request: the URL, GET or POST and the response format (Text, XML, or JSON). When a text message is received, Mobile Commons will look up your URL and make the HTTP request. We automatically append the following parameters to the request URL: Default Parameter Description args The args parameter will contain the body of the message sent by the user, with the keywords removed. For example, with a mdata campaign that has a keyword CELSIUS, if a user sends CELSIUS 100, we'll pass args=100 to your web service. phone The phone parameter will contain the phone number of the user who sent the message. For example, we'll pass phone= to your web service. keyword The keyword parameter will contain the keyword that the user actually texted to query your service. profile_first_name The first name of the user who texted in, if it s in your Mobile profile_first_name The last name of the user who texted in, if it s in your Mobile profile_street1 The street1 of the user who texted in, if it s in your Mobile profile_street2 The street2 of the user who texted in, if it s in your Mobile profile_city The city of the user who texted in, if it s in your Mobile profile_state The state of the user who texted in, if it s in your Mobile profile_postal_code The postal code of the user who texted in, if it s in your Mobile profile_custom_field If you have custom fields setup for your profiles, they will be prefixed with profile_, such as profile_favorite_color=red. profile_id Mobile Commons internal ID number of this profile. This is unique and always the same for a given phone number. It is most useful if you do NOT want to see the user s phone number for privacy reasons. longitude If your mdata is setup to expect location-based queries, we will geocode the user s query in real-time and send you the longitude/latitude, if available. latitude If your mdata is setup to expect location-based queries, we will geocode the user s query in real-time and send you the longitude/latitude, if available. 3

4 When designing a web service from scratch, we recommend using the default HTTP parameter names we've provided above. However this isn't always an option when connecting to a legacy web service. In this situation, you can easily setup mappings between our parameter names and yours. For example, if you have an existing web service that expects a parameter called 'query' instead of 'args' and a parameter called 'number' instead of 'phone', you can easily specify this mapping in our web interface and we'll send you the parameter names you requested. Figure 3 Interacting with legacy web services is easy -- just setup a mapping from our default parameter names to yours Also note that you can selectively enable or disable parameters. For example, if you do not want any phone numbers for privacy reasons, you can configure mdata to only send the unique profile_id and never send a phone number. Keywords, Short Codes, and User Interaction Models Over the past 5 years, Mobile Commons has analyzed millions of text messages to understand user behavior. Our platform has adapted to provide the best end-user experience possible of any application provider. mdata leverages Mobile Commons industry-leading keyword matching, session management, and natural language processing. You can configure the ways users interact with your mdata in a variety of ways, but the most common is to make it sticky. After a user texts a keyword the first time, we will continue to send all subsequent text messages to your URL, even if they do not prepend a keyword. Mobile Commons keeps track of users sessions and manages them for you. Note that sticky sessions are useful on both shared and dedicated short codes. On shared short codes, they let users interact with your service the way they would expect it to, without any crossover between customers. For dedicated short codes, organizations can run many different mobile campaigns simultaneously. For example, you can run a list building campaign, a contest, and an mdata lookup service at the same time on a single short code. Each mdata can be associated with one or more keywords, which you can configure through our web interface. 4

5 Figure 4 You can add as many keywords as you want for your mdata, such as homophones, misspellings, and A/B testing If you have multiple data sources you want to make accessible, you can do this in two ways: 1. Multiple Keywords, One URL: With this option, you can setup a single mdata program to connect to a single URL. You can then associate multiple keywords to it. When a user texts one of your keywords, we will include it in the HTTP request parameters. It is then up to your application to decide what information to return based on the keyword. This is illustrated in the image above. 2. Multiple Keywords, Multiple URLs: Alternatively, you can setup a separate mdata for every one of your URLs. You can then associate one (or more) keyword to each mdata and we'll make the request to a different URL depending on what the user texted in. Figure 5 If you have multiple data sources, you can setup as many mdata URLs as you need, one for each 5

6 If your application requires a search term or query, the user can include it in their original text message e.g. Text EURO and an amount to OR you can ask the users to just text a keyword and we ll automatically prompt them to reply with their search term. Both models work at the same time, and it only depends how you want to advertise the call-toaction. Finally, note that Mobile Commons will prioritize keywords over replies every time. (on a shared short code, only your organizations keywords are considered). You can use this fact to set up complex interactions, whereby sometimes users are texting keywords and jumping between mdata programs and other times they are texting search terms. If you would like recommendations on the best way to configure your account, please don t hesitate to ask your account manager. Figure 6 You can customize your help messaging, giving more details about the service or prompting the user to reply with a query Error Handling In the event that your web service is unavailable or responds with an error code, Mobile Commons will send the user a customizable error message. This can be configured through our web interface: Figure 7 You can customize the error message a user gets if your web service is unavailable or returns an error 6

7 Testing Mobile Commons provides a web-based testing tool that you can use when setting up your program. You can also run it in debug mode, which will show you exactly what your server sent to us, which is invaluable for debugging. Figure 8 Web-based mdata Testing Tool, including debug mode mdata Examples For these examples, we will be using mdata + web services to create a currency converter that anyone can access from a text message. For simplicity, it will convert from US Dollars to Euro and use keyword EURO. Note that HTTP parameters with blank values have intentionally been left out for clarity. Example 1: Simple Currency Converter with Plain Text Response. First Time User: In this simple example, the customer s web service is up and running on their server at example.com. The response is plain text and is exactly what the user should get back on her handset. 1. User texts EURO 10 to Mobile Commons makes an HTTP request to the specified web service: Customer s web server responds with text: 10 US dollars are 6.95 Euro 4. Mobile Commons sends the response 10 US dollars are 6.95 Euro to the user 7

8 Example 2: Currency Converter with Profile Data: In this example, the customer s message flow asks the user for their name and zip code. When the user responds, Mobile Commons extracts the data, looks up the city and state, and stores all the information in their profile. When the user later sends a text to the currency converter, Mobile Commons will include all the profile information in the HTTP request. 1. User texts JOIN to MC responds Please respond with your full name and zip code 3. User texts Michael Jordan MC responds Thanks. Please text a dollar amount to convert to Euro 5. User responds Mobile Commons makes an HTTP request to the specified web service, this time including all known profile data: 1212&profile_first_name=michael&profile_last_name=jordan&profile_postal_code =11201&profile_city=brooklyn&profile_state=ny 7. Customer s web server responds with text: 10 US dollars are 6.95 Euro 8. Mobile Commons send the response 10 US dollars are 6.95 Euro to the user Example 3: Currency Converter, Repeat Usage: 1. User texts EURO 10 to Mobile Commons makes an HTTP request to the specified web service: Customer s web server responds with text: 10 US dollars are 6.95 Euro 4. Mobile Commons send the response 10 US dollars are 6.95 Euro to the user 5. User responds Mobile Commons detects the user s current session and makes an HTTP request to the specified web service with the new query. No keyword was required 7. Customer s web server responds with text: 20 US dollars are 13.9 Euro 8. Mobile Commons send the response 20 US dollars are 13.9 Euro to the user Example 4: Currency Converter with XML Response: In this example, mdata is configured to support an XML response from the Web Server. The format of the response message can be completely customized with the Liquid Template Language through our web interface. For example: "{{source.value}} {{source.currency}} are {{target.value}} {{target.currency}}" 8

9 1. User texts EURO 10 to Mobile Commons makes an HTTP request to the specified web service: Customer s web server responds with XML: <source><currency>us dollars</currency><value>10</value></source><target><currency>euro</currency><value>6.95< /value></source> 4. Mobile Commons parses the XML, applies the Liquid template, and send the response 10 US dollars are 6.95 Euro to the user Example 5: Custom URL Parameters In this example, we are interacting with a legacy web service that cannot be changed. As such, the parameters names must be converted before making the HTTP request. 1. User texts EURO 10 to Mobile Commons looks up the custom HTTP parameter mapping for the customer s legacy web service. 3. Mobile Commons makes an HTTP request to the web service with modified parameters 4. Customer s web server responds with text: 10 US dollars are 6.95 Euro 5. Mobile Commons sends the response 10 US dollars are 6.95 Euro to the user Example 6: Simple Currency Converter with Long Responses 1. User texts EURO 10 to Mobile Commons makes an HTTP request to the specified web service: Customer s web server responds with extra long text: At the current exchange rate of 1 to , 10 US dollars are Euro. This represents an decrease of 0.02% from last week's exchange rate and a decrease of 0.04% from last month. 4. Mobile Commons intelligently splits the long response into multiple messages, being careful not to split any words in half. Page numbers are also added 5. Mobile Commons sends the first message to the user 1/2) At the current exchange rate of 1 to , 10 US dollars are Euro. This represents an decrease of 0.02% from last week's exchange rate and a 6. Mobile Commons waits for confirmation from the wireless carrier that they received the first message and immediately sends the second message (2/2) decrease of 0.04% from last month. 9