Setting up mData on a web service

You can set up a number of different web service mDatas on your website with any plain text, JSON, or XML tool.

Note: Mobile Commons offers a Polling Place Locator mData, which we can set up for you. For more information, contact your customer success manager.

To set up mData on a web service:

1. Select Text Messaging in the left pane, and then select mData.

2. At the top of the page, select New mData.

   The New mData form opens.

   

3. In the mData Details section, enter a descriptive name for the mData.

Note: Even though this name is available to internal users only, take the opportunity to assign a descriptive name that is meaningful to your organization.



4. In the How do you want to build your application? section, select Use a Web Service.

5. Fill in the web service URL.

6. Select the Request method: GET or POST.

7. Select the Response format: xml, text, or json.

8. Select the request timeout: 5, 10, 15, 20, 25, or 30 seconds.

9. If you would like results returned in a format other than our specified mData format, you can compose the response using Liquid Template Language, in the Template box.

10. To set up custom parameters, select the Assign Custom Web Service Parameters checkbox.

    Note: For assistance with setting up custom parameters, work with you customer success manager.

    

11. In the How will users interact with your service? section, select the search/response interaction for this mData:

    Interaction options

    Search method	Result
    Text a keyword	Returns the response that corresponds to that keyword in your spreadsheet.
    Text a keyword and search term, for example,	(default) mData returns the search results. For example, if a user texts weather new york, weather is the keyword and new york is the search term. mData returns the weather for New York. You can also set up this option to return an automatic response to a keyword alone. For example, if a users texts the keyword weather, mData returns an automatic response asking for a search term, such as What city would you like the weather for? If the user texts New York in response, mData returns the weather for New York.

12. (Recommended) Leave the Send all future replies to this mData, even without a keyword option selected.

    This option allows users to send consecutive searches for the same keyword for up to 72 hours. For example, if a user texts Boston veterinary clinics, mData returns a list of veterinary clinics in Boston. If the same user then texts animal shelters, mData returns a list of animal shelters in Boston.

    

13. In the Response Defaults section, review each of the default error messages and make any changes in the corresponding text box.

    • The Default/Error response is sent when mData does not recognize the search query sent by the user.

    • The No Results Found response is sent when the search query sent by the user does not return a result.

14. When you are done, select Create.

Configuring responses from your web service

You specify the URL for your web service when you set up your mData. Mobile Commons will ping that URL whenever a message is received and append ?args= to the end of the request. You can then parse the args parameter, generate a dynamic response, and then return text, XML, or JSON.

Mobile Commons will parse your response and send the dynamic message back to the user. If the response is long, Mobile Commons will automatically paginate it for you as follows: 1/2), 2/2).

Note: Mobile Commons splits messages intelligently and will never break words in half.

You can return any arbitrary XML or JSON and compose the response with the Liquid template language. Any key/value pair in your web service response can be used directly in the template as a variable. This makes it very easy to integrate with your existing web services, no coding required.

If you specify response format Text, Mobile Commons will send that text back unchanged.

Tip: Returning plain text is by far the easiest way to do it.