The Concept
To create an interactive game using Text Messaging and to show how easy it is to create interactive experiences using your Text Marketer Account. The example uses both our short code API (to receive the customer responses) and then our gateway API to send out the ‘answer’.
The Game
Guess the number of sweets in a jar. A simple game where the participant texts in the number of sweets they think are in the jar and then receives a message indicating if they are high, low , close or have correctly guessed to the number of sweets.
Mechanics
Fig 1 shows the how the basic flow of the systems works. The game is initiated by an incoming text message (as shown in orange) to our 88802 shortcode. The text message contains a keyword in this case sweets and the data you which you need to parse.
Once the text message has been received in your account you can enable a trigger to be sent to your own script residing on your own server. The trigger is a GET request with the parameters added to it as per our short code documentation.
Your application/script can then use the data to generate a response. In our case, we find out whether the participant has guessed the correct number and we send back an appropriate response using the Text Marketer API Gateway see the documentation for details.
Creating the game and code examples
The Guess number of sweets in a jar game and all the code you need is below. It’s written in PHP 5.
Once you have created yourself a free account you need to request a free shortcode keyword from Text Marketer.
Next login to your account and set the url your wish to use for accessing your script. To access the setup screen, select from the menu “Incoming SMS” => “Change Reply Settings” then click “Configure” next to the keyword. You’ll then be able to paste the URL into the API URL window. Then press submit.
The game is broken the code down into 4 classes.
| Class Name | Purpose |
| SweetsInAJar | The entry point class |
| ExtractData | Parse the incoming data & extract the result |
| MessageLogic | Game logic and associated response |
| SendSMSXML | The SMS send class |
class SweetsInAJar
{
function __construct()
{
$sms = new SendSMSXML("myUsername","myPassword");
$theData = new ExtractData("sweets",$_GET['message'],$_GET['number']);
$logic = new MessageLogic();
$logic->setClosenessRangeInPercent(15);
if($theData->isValid()){
$sms->send($theData->getNumber(),$logic->getMessage($theData->getData()),"GuessGame");
}
else
{
$sms->send($theData->getNumber(),$logic->getFailedMessage(),"GuessGame");
}
}
}
Explanation
This is our main class that calls all the relevant objects and class together. Simply the logic works like this:
- Set up all the objects you need.
- Set the closeness to the number of sweets you will need to get before the “you are close” message will get sent .
- If there is data we can use from the incoming message, select the correct response and send it.
- Otherwise select the “invalid format message” and send that.
class ExtractData
{
private $theData;
private $theMobileNumber;
private $keyword;
private $valid=false;
function __construct($keyword,$message,$number)
{
$this->keyword = $keyword;
$this->valid = $this->getMessageInfo($message);
$this->theMobileNumber = $number;
}
public function isValid()
{
return $this->valid;
}
public function getData()
{
return $this->theData;
}
public function getNumber()
{
return $this->theMobileNumber;
}
private function getMessageInfo($m)
{
//remove the keyword and set the result
//remove extra spaces
$m=trim($m);
$m=str_ireplace($this->keyword,"",$m); /// remove keyword $m=ltrim($m); // remove any spaces
if(is_numeric($m)) {
$this->theData = $m;
return true; // is it data?
}
else return false;
}
}
Explanation
This simple class allows us to extract the data we need from the short code response. The response contains the entire message so we need to remove the keyword and any spaces then check to see if the result is a number. If it is then the object is “valid” else it’s not valid and we can use this state to send the “invalid format message” as described above.
class MessageLogic
{
private static $lowGuess ="Bad Luck! There are more sweets in the jar than you think, try again.";
private static $highGuess="Bad Luck! There are less sweets in the jar than you think, try again.";
private static $correctGuess="Well done! You have guessed the correct amount.";
private static $closeGuess="Close Guess! you are within {value}% of the correct answer.";
private static $badData="We couldn't understand your answer please text in the word SWEETS and your answer, for example SWEETS 300";
private $numSweets=5678; //default
private $closenessRange=5; //5 percent as default
public function setNumberOfSweets($value)
{
$this->numSweets=$value;
}
public function setClosenessRangeInPercent($value) //in percent
{
$this->closenessRange=$value;
}
public function getFailedMessage()
{
return self::$badData;
}
public function getMessage($value)
{
/// some very simple rules
if($value==$this->numSweets) return self::$correctGuess;
$isClose = round(((abs($this->numSweets - $value)) / $this->numSweets) * 100); // calculate how close the number is
if($isClose < $this->closenessRange) return str_replace("{value}",$this->closenessRange,self::$closeGuess); // if with in the closeness range return close messsage
else{
if($value > $this->numSweets) return self::$highGuess;
else return self::$lowGuess;
}
}
}
Explanation
This is the game logic class, the getMessage function requires the integer that we extracted using the ExtractData class. There are then some simple rules that select the appropriate message as the returned value.