Skip to main content

Mobile Commons: Advanced Web Forms

Eric Shin
Updated
Resolution Summary

Provided information on Advanced Web Forms




Answer

Mobile Commons provides a simple HTTP POST interface to enable your users to opt-in to mobile campaign(s), trigger phone calls, tell-a-friend, donate money, and more from the web.

The most common use-case is to host a web form on your site that POSTs to our listener, as explained below, but server-to-server submissions are possible. In the latter case, your developers should just mimic the same HTTP POST that the form would do. Alternatively, developers can use our profile_update API.

 

Form Actions

First, let's just look at a simple example form:

<form action="https://secure.mcommons.com/profiles/join" method="POST">
  Phone Number: <input type="text" name="person[phone]" /><br />
  <input type="checkbox" name="opt_in_path[]" value="OP111111B4567890123456" >Sign up for SMS Alerts<br />
  <input type="hidden" name="redirect_to" value="http://yoursite.com/your_submission_confirmation_url" />
  <input type="submit" value="Submit" />
</form>
<a href="http://www.yoursite.com/terms" style="font-size:75%">Msg & Data Rates May Apply</a>.<br />
Text <b>STOP</b> to opt-out. No purchase necessary. Expect 4 msgs/mo.<br />
<a href="http://yoursite.com/your_terms_and_conditions" style="font-size:75%">Terms & Conditions</a>

To use this form, change the bold values to match your desired business logic, then paste it into your HTML page.

You can make updates to the submit button stylings as well:

<ul>
    <input  style="background: yellow ; font-size: 20px; font-family: Tahoma" class="button" value="Submit!" type="submit">
 </ul>

Triggering an mConnect:

As another example, you might want to trigger an mConnect. Be sure to build a follow up text for callers that prompts an opt-in to convert non-subscribed callers into subscribers! If you attempt to trigger an invalid mConnect you will receive a "Validation failed: mConnect ID was not found, Please contact system administrator to fix that" error.


<form action="https://secure.mcommons.com/profiles/join" method="post">

<input type="hidden" name="redirect_to" value="http://yoursite.com/your_submission_confirmation_page" />

<input type="hidden" name="mconnect" value="Mconnect Key" />



<label>Phone Number:</label>

<input type="text" name="person[phone]" /> <br/>

<br/>

<label>Street Address:</label>

<input type="text" name="person[street1]" id="person_street1" /> <br/>

<br/>

<label>City:</label>

<input class="city" type="text" name="person[city]" id="person_city" /> <br/>

<br/>

<label>State: </label>

<input class="state" size="2" type="text" name="person[state]" id="person_state" /> <br/>

<br/>

<label>Zip code: </label>

<input class="postal_code" size="10" type="text" name="person[postal_code]" id="person_postal_code" /> <br/>

<br/>



<input type="submit" value="Call Me!" />

</form>

This is a more complex example, highlighting more available form parameters:

<form action="https://secure.mcommons.com/profiles/join" method="POST">
  Phone Number: <input type="text" name="person[phone]" /><br />
  First name: <input type="text" name="person[first_name]" /><br />
  Last name: <input type="text" name="person[last_name]" /><br />
  Email: <input type="text" name="person[email]" /><br />
  Postal code: <input type="text" name="person[postal_code]" /><br />
    
  <input type="checkbox" name="opt_in_path[]" value="OP111111" checked="true">Sign up for SMS Alerts<br />
  <input type="checkbox" name="opt_in_path[]" value="OP222222" checked="true">Sign up for SMS Coupons<br />
  <input type="checkbox" name="fundraising" value="MG333333" checked="true">Donate $5<br />
  <input type="checkbox" name="mconnect" value="VO444444" checked="true">Call Me Now<br />

  Tell a Friend: <input type="text" name="friends[]"/><br />
  Tell another Friend: <input type="text" name="friends[]"/><br />
  Tell one more Friend: <input type="text" name="friends[]"/><br />
  <input type="hidden" name="friends_opt_in_path" value="OP555555" />

  <input type="hidden" name="redirect_to" value="http://yoursite.com/your_submission_confirmation_url" />
  <input type="submit" value="Submit" />
</form>
<a href="https://uplandsoftware.com/mobile-messaging/terms-and-conditions/" style="font-size:75%">Msg & Data Rates May Apply</a>.<br />
Text <b>STOP</b> to opt-out. No purchase necessary. Expect 4 msgs/mo.<br />
<a href="http://yoursite.com/your_terms_and_conditions" style="font-size:75%">Terms & Conditions</a>

 

Parameters and Variables

To configure the landing page that subscribers get redirected to, change the redirect_to= parameter to a Thank You page on your web site.
If you are making a server-to-server POST, you likely want to remove the redirect_to= parameter. In this case, we will send back a 200 OK response.

To specify the desired actions, you should include one or more of the following parameters:

  • opt_in_path – for a single opt in (note this is your opt-in path key, not the campaign key).
  • opt_in_path[] – this parameter should be repeated to opt in to multiple campaigns. See sample above. 
  • fundraising – to donate money. Only one fundraising program per form.
  • mconnect – to connect to an mConnect program. Only one per form.
  • friends[] – to invite friends. Multiple fields per form. This parameter may be repeated to invite more friends. See sample in above example form.
  • friends_opt_in_path –the opt in path to use to invite friends. This is optional. opt_in_path or opt_in_path[] will be used if this is not present.
  • company_key – to update a profile without triggering any actions. You can find your Company Key on your company setup page.

The value(s) associated with each parameter can be found underneath the Actions box on the right hand side of each web page. It will look like a long string of 34 random letters and numbers. Note that we continue to support the legacy ID parameters (the number found in the URL) but you should switch to using Key wherever possible.


Currently, Mobile Commons allows mapping to things that are recognized as attributes of profiles within our system. As per the code example above, the form field names should have values that correspond to the general scheme person[attribute]. The values which we currently recognize are:

Mobile Phone Number:
person[phone]
First Name:
person[first_name]
Last Name:
person[last_name]
Email:
person[email]
Street Address:
person[street1], person[street2], person[street3]
City:
person[city]
State:
person[state]
Postal Code:
person[postal_code]
Country:
person[country]


If you are using any custom fields, simply place the name of the column in the form like so:

Favorite Color (sample custom field):
person[favorite color]



If you have a CRM integration setup, you can send us the constituent's ID from your database

External / Constituent ID:
person[external_id]



We also support a number of advanced form settings:

  • referer – by default, we set the origin_description on subscriptions/calls to the referer URL, but you can override this with the referer parameter
  • annotate_last_call – annotate the last mConnect call the user made with a free text field. Requires opt_in_path, mconnect, or company_key
  • annotate_last_call[key1],annotate_last_call[key2] – you can add multiple annotation parameters (e.g. 'stance' and 'comment')and we will store as JSON.
  • mconnect_legislator_id – override which legislator is called during an mConnect using Mobile Commons legislator ID
  • mconnect_actionkit_legislator_id – override which legislator is called during an mConnect using ActionKit legislator ID
  • mconnect_convio_legislator_id – override which legislator is called during an mConnect using Convio legislator ID



Dual-POST to Mobile Commons with Javascript/AJAX

While cross domain POST requests are presently not allowed, you can use an intermediary iframe to make it appear these requests are happening in the background. The trick is to create an empty iframe that does the work of posting to our server. The challenge with this work around, is that it is difficult to render our servers' response to your end user. You will need to write javascript to validate data before sending it to our server.

The recommended proccess is as follows:

  1. User clicks submit.
  2. Javascript intercepts the submit event to validate the submission.
  3. If valid, the javascript submits the user visible form, like any other form.
  4. The form posts it's parameters through the hidden iframe, to our server.
  5. The page's javascript assumes a successful post, hides the form, and displays a thank you message to the end user.

Basic code Example:

<form action="http://anotherdomain/save" method="post" target="myiframe" id="myform">
  <!-- standard form here -->
</form>
<iframe src="about:blank" name="myiframe" style="display: none;"></iframe>

<!-- With jquery, something like: -->
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.1/jquery.min.js"></script>
<script>
$(document).ready(function(){
  $('#myform').on('submit', function(e){
      e.preventDefault();
      //if(validates){
        $(e).submit();
      // }
    });
});
</script>
 

For validations we recommend: http://jqueryvalidation.org/


POST Opt-Outs


To create an opt-out web form, use following code as a guide:

<form action="https://secure.mcommons.com/profiles/opt_out" method="POST">
  Phone Number: <input type="text" name="person[phone]" /><br />
  <input type="hidden" name="company_key" value="CO12345" />
  Mobile:<br /><input type="text" name="person[phone]" /><br />

  <input type="hidden" name="redirect_to" value="http://www.yoursite.com/mobile_optout.html" />
  <input type="submit" value="Opt-Out" />
</form>

You MUST replace the company_key field CO12345 with your Company Key and the "redirect_to" with your own landing page. You can find your company's Key in your company setup page.

Note: We still support the legacy "company" field that uses the ID, but you should upgrade your form code to use company Key instead.

Optional: If you only want to opt-out of particular campaigns, you can add an extra field named "campaign" (or "campaign[]" for multiple campaigns). Only use this option if you have a particular reason to do so and you know what you are doing.

 

Required Terms and Conditions Language

The following language is required with any web opt-in form. The word STOP must be in bold and all caps.

Msg & Data Rates May Apply (link to https://uplandsoftware.com/mobile-messaging/terms-and-conditions/)
Text STOP to opt-out.  Expect 4 msgs/mo. No purchase necessary. 
Terms & Conditions (link to your Terms and Conditions page, if applicable)
Privacy Policy (link to your Privacy Policy, if applicable)

The following language is required for print or television calls to action:

Msg & Data Rates May Apply.  Reply STOP to opt-out. Expect 4 msgs/mo. No purchase necessary.  Terms and Conditions at http://www.yoursite.com/terms_and_conditions.



Resolution Category

Question: Product How-To / Training




Internal Information


Related articles