PHP Automated SMS Gateway for Request and Response Service - Part 1 - The Basics - PHP dotGo Engine package blog

Introduction

Who can use this service?

How does it work?

Your first look at the CMRL

Setting up the PHP dotGo Engine package

Conclusion

Introduction

An automated SMS request and response service is a system that allows users to send text message requests to your domain, which in turn sends back a text message response.

The response can be a simple message or it can be a request for additional information from the user which starts the interaction.

We will be using the DOTGO web service to manage these interactions between a user, who sends the request, and a publisher, your service which returns the response.

Who can use this service?

DOTGO uses short code phone numbers to identify the top level domain of the web site where a request is sent. This means there are some limitations to who can be a publisher and who your users will be.

To understand this limitation, we need to understand how the service works. A user will send their request to a short code phone number, which is a special 6 digit number that routes to the DOTGO service.

These short code phone numbers only work in the United States, Canada and United Kingdom, which means your users can only send SMS messages from these countries.

The PHP dotGo Engine package does come with a solution to emulate SMS messaging through the DOTGO web service which will allow users from anywhere to access your content. In these cases, it is not true SMS messaging, instead the requests are sent over the internet.

The short code phone numbers are a numeric representation of the top level domain (TLD) for the web site. Using yourdomain.com as an example, the TLD is the extension dot com. Using the number pad on a phone, you would spell out DOTCOM by pressing 368266, so the short code for any domain ending with dot com is 368266.

The supported short code phone numbers are DOTCOM (368266), DOTNET (368638), DOTORG (368674), DOTEDU (368338) and DOTGOV (368468). This means that publishers must have a domain that belongs to one of these TLD's.

How does it work?

The user sends a request which consists of a designator followed by optional keywords to a specific channel. Now lets make some sense of that.

The designator is the second level domain (SLD) in a domain name. With yourdomain.com, yourdomain is the SLD which DOTGO refers to as the designator.

The channel is the short code phone number for the TLD of the domain name. Once again using yourdomain.com, the channel is DOTCOM (368266).

The simplest request a user could send would be 'yourdomain' sent to DOTCOM (368266). The text message is routed to DOTGO who queries the domain yourdomain.com, looking for a file named index.cmrl.

This file contains the instructions and responses that DOTGO needs to process the request and is written in a variation of the extensible markup language (XML) called the Concise Message Routing Language (CMRL).

Once DOTGO has determined the appropriate response, it returns it as a text message to the user.

Your first look at the CMRL

In our first example, we will look a the proper format of a simple index.cmrl file.

<cmrl xmlns:dotgo="http://dotgo.com/cmrl/1.0">
  <match pattern="">
    <message>
      <content>Welcome to the site</content>
    </message>
  </match>
  <match pattern="*">
    <engine href="http://yourdomain.com/dotgo.engine.php"/>
  </match>
</cmrl>

Inside each match element we have a message element which contains a content element. Each match element has a pattern parameter which will contain the keyword to compare against a request for a match. Each match element must contain at least one terminating node, which in simple terms is the response or action for DOTGO to take.

The first match pattern contains no keywords which is called a null match. If no keywords are provided, this pattern is matched and the message 'Welcome to the site' is returned to the user. In this case, the message element is the terminating node.

The second match pattern contains the default wild-card match. If no other matches are found then this pattern is matched. In this case an engine element is the terminating node.

An engine element tells DOTGO to send the request to the specified script which will return the response. The package PHP dotGo Engine is the script we will use to dynamically build our responses, including a default response for a null match, so our index.cmrl will look like this...

<?xml version="1.0" encoding="UTF-8"?>
<cmrl xmlns:dotgo="http://dotgo.com/cmrl/1.0">
  <match pattern="*">
    <engine href="http://yourdomain.com/dotgo.engine.php"/>
  </match>
</cmrl>

You will need to replace the href property with the actual URL to the engine file in your site.

Setting up the PHP dotGo Engine package

As was just mentioned, we need to send DOTGO to the correct location of the engine by changing the href property in the index.cmrl file. It is important that there are no redirects. For example if you redirect all traffic sent to yourdomain.com to the sub-domain www.yourdomain.com, then you must use the sub-domain.

You should change the name of the admin.php file to something only you know or can guess. This adds an additional layer of security to keep your system safe. In this article, I will continue to refer to it as the admin.php file so you will need to remember to substitute that with the new name.

In the dotgo.class.php file...

Provide the proper credentials to access your mySQL database

Provide the correct designator for your domain, the SLD.

Provide the correct DOTGO channel to use based on your TLD.

This is also where you can change the default response for a null match and the failed response when no response can be determined.

In the dotgo.admin.php file...

Set your own secret access key. Make it a difficult one, since the administration script uses only this key for authentication. If you ever need to, the key can be changed at any time.

Using the PHP dotGo Engine Package

Point your browser to admin.php?key=yoursecretkey substituting yoursecretkey with your real secret key. This will give you access to the administration interface.

Keywords can be chained together in a path with a parent child relationship. So in the keyword path hello -> world -> again, hello is a root keyword with no parent, world is a child to hello and again is a child to world.

If this is a new installation, you will not have any root keywords yet, so enter the text 'hello' into the Add new keyword field and submit it. You should now be able to see your keyword in the list of children.

Select the keyword 'hello' and you will see more options.

At the top of the page is a breadcrumb navigation section which will allow you to select any keyword within the current path, which ends with the current keyword selected.

You can add a new keyword as a child to this keyword.

You can add/change the response to this keyword. For now, we will be dealing with message responses.

If there are no children, you can remove this keyword.

After this form is a section that will display any notices, the request a user would send and the response returned by the engine.

We should be looking at the admin page for the root keyword 'hello'. We want to add a response, so add the following to the message content section...

Say hello to<br/>
<a query="yourdomain hello world"/> for the World<br/>
<a query="yourdomain hello universe"/> for the Universe

We have introduced some new elements here, the <a/> and <br/> elements. The <a/> element contains a query property, you need to replace yourdomain with your actual domain designator, the SLD.

DOTGO requires strict compliance with closing named elements, as we can see in this case, after the query property we use the slash to close since <a/> elements do not have a named closing element. This is also true with the <br/> element, which is a line break.

DOTGO replaces the <a/> element with a digit that can be returned on its own to represent a users choice. What the user will see in the text message returned to them will be...

Say hello to
(1) for the World
(2) for the Universe

If the user responds with a 1, DOTGO queries yourdomain as if they sent hello world. Likewise, if they respond with a 2, it is as if they sent yourdomain hello universe.

This is our first interaction, however we now need to set up the children, world and universe. Add a new keyword world and submit it, then add a new keyword universe and submit it. Our keyword list should now contain those keywords.

Select the child keyword world and add the message response 'Hello World'. Select the parent 'hello from the breadcrumb', select the child universe and add the message response 'Hello Universe'.

Congratulations, you have set up your first interaction. When a user send the request hello to your web site they are given the option to say hello to the world or the universe. Based on their selection, they will receive the appropriate response.

Conclusion

In this article we have covered the concept behind an automated SMS request and response service and how to use the DOTGO web service to achieve this. We have also looked at using the PHP dotGo engine to simplify user interaction and generating responses.

In future articles we will go more in depth to unleash some truly powerful features of the dotGo Engine.