API Documentation

From Developer Wiki

This is the page for documentation surrounding the Mozes API

Contents

Overview

The Developer API provides a way to use Mozes keywords to interface with systems outside of the Mozes system. A keyword on Mozes can be configured to execute a web script on a different system and then receive and display dynamic content via SMS or the web within the Mozes system. The API consists of two main parts: the Dynamic Content URL which specifies what the Mozes system sends out, and the Dynamic Content Tags which specify how the Mozes system can properly receive and display dynamic data returned to it.

Dynamic Content URL

The Dynamic Content URL is where an external Web CGI script can be set to be called when a keyword is texted. The Dynamic Content URL location is under the API section during the keyword editing process. Enter the entire web address for the script including the "http://" in the field. The Web CGI script can perform any desired action but must return an XML document to the Mozes system. This XML document must consist of a MozesDynamicContent tag, surrounding one or more user-defined tags. For example, if you wish to have your script give Mozes two variables, named Result1 and Result2, to display back to the person who texted the keyword, then your script should return something like this: 

<?xml version="1.0" encoding="ISO-8859-1"?>
<MozesDynamicContent>
 <Result1><![CDATA[insert result1data here]]></Result1>
 <Result2><![CDATA[insert result2data here]]></Result2>
</MozesDynamicContent>

If the script is not intended to provide data back to Mozes, then send the above XML code with just the MozesDynamicContent tags. Please test these URLs and their scripts outside the Mozes system first. If the Mozes system receives an error trying to call the script at the URL provided, Mozes will ignore the error and process the rest of the keyword as if there was no Dynamic Content URL.

Dynamic Content Tags

The Dynamic Content Tags are HTML-style tags which will insert data into the content displayed by the keyword. Most tags will result from the Dynamic Content URL script, although there are some system tags than can be used. These tags can be inserted into the keyword's SMS message and stash only. For user-defined tags, they should be labeled as "Dynamic" followed by the name of the variable.

Example: if the script put data into two variables, Result1 and Result2, then you would insert <DynamicResult1> and <DynamicResult2> into the appropriate sections of the keyword's definition. When editing the keyword, under the Details tab in the Description box you could enter the text: 

Hello! Today is <DynamicResult1> and thanks for texting my keyword.

And under the Mobile tab you could enter: 

<DynamicResult2>

You can also use these tags to specify whether the text message for a keyword should be sent. If your keyword's Text Message just "<DynamicResult1>", and your script returns this XML... 

<?xml version="1.0" encoding="ISO-8859-1"?>
<MozesDynamicContent>
 <Result1><![CDATA[ ]]></Result1>
</MozesDynamicContent>

...then there will be no message sent back to the texter for that particular texting of your keyword.

System Tags

There are also some system-provided tags and are primarily intended to be used as part of the API. You can also use these tags anywhere you could use <DynamicResult1> style tags, although there are few uses for them anywhere but in the API. The Mozes-provided tags are:

  • <userid> - the Mozes user ID of the person receiving the keyword. This is the only way of identifying the users for determining unique responses. For example, a Dynamic Content URL of 
http://my.server.com/cgi-bin/mozesscript.cgi?user=<userid>

would allow your script to return different messages based on who's receiving the keyword. For privacy reasons, we do not allow the API to display the phone numbers or names of Mozes users.

  • <sendid> - the Mozes user ID of the person sending the keyword. This will be the same as <userid> unless this keyword is being sent to someone else using @NUMBER or @GROUP.
  • <sendersubscribed> - 1 if the person sending the keyword (see <sendid>) is part of your keyword's mob, otherwise 0. Useful if you want to encourage people to join your keyword's mob; in addition, if your keyword asks people to reply Y to join, you'll know if the footer that requests this is going to be appended (thus reducing the number of characters your response has available).
  • <parameter> - if the keyword was texted using "keyword abc", then "<parameter>" will be replaced with "abc". This allows users to send arbitrary commands, votes, or whatever else you want to configure your script to recognize. Anything to the right of the keyword will be sent as one parameter even if it contains spaces or symbols. Be careful to check this for errant symbols and clean them out, if you ask the user to input filenames or the like - this is essentially user-input data, so a skilled systems cracker can try to input malicious data (for example, if you ask for a filename and a user sends "; cd /; rm -rf *") or can send bad data by accident (for example, if you ask for "steve" or "mary" and take the answer as the filename to open, as in "steve.conf" or "mary.conf", but someone answers "steve!!!" and you have no "steve!!!.conf"), although making sure your script only accepts valid characters can completely defend against this.
  • <keyword> - the actual keyword string that was texted in (URL escaped, as in replacing whitespace with +, if in the dynamic content URL). Useful if you have two or more keywords pointing to the same script. Essentially identical to <parameter>, but with the keyword in front, so the same warning about cleaning your data applies.
  • <keywordonly> - just the keyword. As above, useful if you have two or more keywords pointing to the same script.

Example: If you created a keyword called "homelight" and then wanted users to pass along the command to turn it "on" or "off", you could tell users to text "homelight on" or "homelight off", and you could define the following in the Dynamic Content URL under the Developer API section from "Edit my Mobile Card" tab for the "homelight" keyword: 

http://my.server.com/cgi-bin/myprogram.cgi?command=<parameter>

This means the script myprogram.cgi will have the variable "command" set to the value ("on" or "off") that was texted by the user.

Tips & Tricks

  • Remember, texting "keyword@number" allows a user to send a keyword to other users. Some of our API keywords make use of this functionality. If you want to disallow this use, make sure to get both the userid and sendid and make sure they match, or return an error message if they do not.
  • If your script sends a blank response (for instance, "<Result> </Result>" - note the whitespace between the tags), and you set the keyword's SMS reply to be nothing but this response (in this case, just "<DynamicResult>"), then no reply will be sent back to your users when they text in. Use this if you don't have anything to send back and your users are sensitive about text messaging charges (although most cell phone plans these days come with allowance for some amount of free texting, even if their users are not always aware of it).

Example Script: Simple Voting Module

This example allows users to vote on a yes/no question by texting "samplevote y" or "samplevote n". The keyword owner can announce to a group the question and the instructions for responding. The users receive a running vote count on their phone and Mozes account.

Editing the "samplevote" keyword from "Edit my Mobile Card" tab. Under the Developer API section, enter in Dynamic Content URL: 

http://my.server.com/cgi-bin/votescript.cgi?vote=<parameter>

Here is the content of votescript.cgi: 

#!/usr/bin/perl
use CGI;
my $query = new CGI;
my $result = "Please vote \"samplevote yes\"" .
 ", \"samplevote no\", or " .
 "\"testvote tally\" to just see the results.";
my $vote = lc($query->param("vote"));
if ($vote eq "y") {
 $vote = "yes";
} elsif ($vote eq "n") {
 $vote = "no";
} elsif ($vote eq "t") {
 $vote = "tally";
}
if (($vote eq "yes") || ($vote eq "no") ||
  ($vote eq "tally")) {
 my $yes = 0;
 my $no = 0;
 my $filename = "/var/www/data/vote.txt";
 if (-e $filename) {
  open(RD,$filename);
  my $line = <RD>;
  $line =~ s/\D//gs;
  $yes = $line;
  $line = <RD>;
  $line =~ s/\D//gs;
  $no = $line;
  close(RD);
}
if (($vote eq "yes") || ($vote eq "no")) {
 if ($vote eq "yes") {
  $yes++;
 } else {
  $no++;
 }
 open(WR,">" . $filename);
 print WR $yes . "\n" . $no . "\n";
 close(WR);
}
$result = "Received a " . $vote .
 ". As of your texting, the total is " .
 $yes . " yes and " . $no . " no.";
}
print "Content-Type: text/xml\r\n\r\n" .
 "<?xml version=\"1.0\" " .
 "encoding=\"ISO-8859-1\" ?>\n" .
 "<MozesDynamicContent>\n" .
 "<Result>" . $result . "</Result>\n" .
 "</MozesDynamicContent>\n";

And while editing the keyword "samplevote", enter: 

<DynamicResult>

for the Text Messages field.

Alternately, you could have two keywords - "samplevotey" and "samplevoten" (or "ilikethat" and "ihatethat", or other keywords more relevant to the question in question) - and set their Dynamic Content URLs as follows: 

http://my.server.com/cgi-bin/votescript.cgi?vote=y (for "samplevotey")
http://my.server.com/cgi-bin/votescript.cgi?vote=n (for "samplevoten")

For both keywords, you would again enter: 

<DynamicResult>

for the Text Messages field.

Disclaimer

If you use the API, you are responsible for testing your keyword to make sure that what shows up in the Mozes system when someone texts your keyword is what you desire to have show up. Mozes assumes no responsibility or liability for anything that may happen to your servers as a result of any script invoked by your keyword, nor for any consequence that should arise if you point your keyword to a script whose owners object to this use.

Retrieved from "http://wiki.mozes.com/developer/index.php/API_Documentation"