Logo-c

mData Web Services

mData lets you create dynamic, data-driven applications on our platform. The easiest way to create them is to upload a CSV with all your information, but for those of you who want something a little more complex, you can specify the URL of a web service.

Download mData User Guide (PDF)

 

Using a Web Service

When you setup your mData, specify a URL instead of "Upload CSV". We will ping that URL whenever we get a message and append ?args= to the end of the request. You can then parse the args parameter, generate a dynamic response, and return us text, XML, or JSON. We will parse your response and send the dynamic message back to the user. If the response is long, we will automatically paginate it for you like so: 1/2), 2/2). Note that we split 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, we will simply send that text back unchanged. Returning plan text is by far the easiest way to do it.

 

Request Parameters

We will pass the following url parameters to your web service

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 webservice
phone
The phone parameter will contain the phone number of the user who sent the message.
For example, we'll pass phone=2125551234 to your webservice.
keyword
The keyword parameter will contain the keyword that the user actually texted to query your service. You can setup multiple keywords for a single mData program and customize your service to behave differently for each. Using the example above, we would send keyword=celcius to your web service.
profile_first_name
The first name of the user who texted in, if it's in their Mobile Commons profile
profile_last_name
The last name of the user who texted in, if it's in their Mobile Commons profile
profile_email
The email of the user who texted in, if it's in their Mobile Commons profile
profile_street1
The first line of the address of the user who texted in, if it's in their Mobile Commons profile
profile_street2
The second line of the address of the user who texted in, if it's in their Mobile Commons profile
profile_city
The city of the user who texted in, if it's in their Mobile Commons profile
profile_state
The state of the user who texted in, if it's in their Mobile Commons profile
profile_postal_code
The 5 or 9 digit postal code of the user who texted in, if it's in their Mobile Commons profile
profile_CUSTOM_FIELD
If you have custom fields setup for your profiles, they will be prefixed with profile_, such as profile_favorite_color=red
longitude
If your mData uses location-based queries, we will geocode the user's query and send you the longitude/latitude, if available
latitude
If your mData uses location-based queries, we will geocode the user's query and send you the longitude/latitude, if available
 

Sample PHP Code

The following PHP code sample will take a value in Fahrenheit and convert it to Celsius.

<?php
  $msg = "";
  $fahrenheit = $_GET['args'];
  $phone = $_GET['phone'];
  $celsius = convert_to_celsius($fahrenheit);
  $msg = "$fahrenheit degrees Fahrenheit is $celsius degrees Celsius";

  echo $msg;

  function convert_to_celsius($f) {
    return ($f-32)*(5.0/9.0);
  }
?>

Legacy XML Format

In the early days, Mobile Commons recommended you return XML with the following schema:
<?xml version="1.0" encoding="UTF-8"?>
  <response>
    <reply>
      <text>
        <![CDATA[This is the response message]]>
      </text>
    </reply>
  </response>
</xml>

This format is still supported as the default XML response, but it is certainly not required.