Introduction

Onuprova SMS server is highly programmable SMS gateway server. Everything it requires is a PC to run on and a GSM modem with a valid SIM card. It exposes easy to use API over TCP. The basic functionalities of the SMS server are

  • Send single or bulk SMS from the provided SMS Server Manager or API.
  • Receive SMS and apply any combination of SIX SMS processing logics.

In built SMS processing logics are known as actions. The six actions are

  1. Static response
  2. Forward via SMS or E-Mail
  3. Forward using TCP protocol
  4. Forward using HTTP protocol
  5. Search a Database
  6. Insert In a Database

Static Response

This is helpful when you want to provide any static information. For example if someone send a text writing INFO then you want the server send a text with your company information.

Forward via SMS or E-Mail

Sometimes you may want to receive the SMS directly in your phone or e-mail inbox. Use this action to do so.

Forward using TCP

If you want SMS server to notify your software about any SMS with particular SMS tag, please use this action.

Forward using HTTP

This action can notify any web page about the incoming SMS with specific tag.

Search Database

This function is able to search a database and send response with the search result. It will send up to five results for a search query.

Please note that this function can search or send response from only columns with string value type.

Insert Into Database

This function is able to Insert records in a database and send response by parsing data from some columns.

Please note that this function can Insert or send response from only columns with string value type.


Installing SMS Server

SMS server comes with an executable ‘SMS Server Setup.exe’. Please run the file and follow the wizard. Once the software is installed, you will see an Icon on the desktop. Alternatively you can find the shortcut from

Start Menu>>All Programs>>Onuprova>>SMS Server>>SMS Server Manager

If you see the Server Status Indicator is gray, then turn the server on by clicking

File>>Start Server

Wait until you see the Server Status Indicator goes green and the Activity indicator says Ready. (It may take some time for the server to be ready). Now plug in the modem and setup the drivers (If you have not done this already). Now select the modem setup tab

Modem setup

Once you select the Modem setup tab Click on the change button and you will see the list of available modems. Select one that you want to use. Now you have changed the modem but you need to apply the changes to make the server use your selected modem. Please select File>>Apply Changes and Choose Re-start and apply now. You will see the activity indicator to change to ‘Server is unreachable…’ wait for it to change to ‘Ready’. Now your server is ready to send and receive SMS.

***Please note that, SMS server exposes API over TCP port 2000. If you have a firewall blocking connection to and from port 2000 please add an exception.


Programming the SMS server

The main feature of the SMS server is its programmability. In SMS server, reception logics are made up of functions and each function is made of several actions. The default function of the SMS server is Unknown. You cannot delete or create the Unknown function. Let’s add come function by clicking the add button under the function list, name it INFO. In the parameter field type

[FirstName] [LastName]

This is how you define the parameters for the INFO function. Now click save. You can name the parameters anything you like however, [PhoneNumber] and [Date] is two reserved parameter that you cannot define. Each parameter name must be enclosed with in square bracket and parameters are separated by a space. You can call this function by sending a text with the following sample content

Info Mark Robertson

You have to apply the change before you can call this function.

So we can see the first word of the SMS represents the function name and the rest represents the parameters. So what happens when the function name is not found? SMS server will execute the Unknown function if the function name indicated on the SMS is not found.

Adding Actions

These functions alone are not any good unless you have some action assigned to them. To add actions to a function, click on the function and now click on the add button underneath the Actions List box.

You should see a dialogue box with six options. Let’s select the Static response. You will see another dialogue box.  First two field of this dialogue box will indicate the name of the function and parameter format of the function. As you are sending static response you now need to specify the response text now, you can use the parameters to customize the response. In our case, INFO function has two parameters [FirstName] [LastName] so we can add a response text like the following

Your first name is [FirstName] and your last name is [LastName].

Now when someone write a SMS to your server with content

Info Mark Robertson

Will receive the following response

Your first name is Mark and your last name is Robertson.

I hope the uses of parameters are pretty clear now. However there are many other uses. If you add a TCP or HTTP forward action to the INFO function, your application will receive a line of text like the following (Let’s assume Mark’s phone number is +44123456789)

PhoneNumber=+44123456789&FirstName=Mark&LastName=Robertson

If you check the ‘has response’ check box then the SMS server will forward the response received from the TCP or HTTP server to the sender.

Special Actions Search and Insert

The search action can search database records and the insert action can insert record to the database. After filling in the connection string and the table name, you have to specify the search columns like the following

FName=[FirstName],Lname=[LastName]

Here FName and LName are two columns of the specified table of the database. After specifying the search columns you require to specify the response columns like the following

FName,LName,Address

This means we are instructing to read from the FName LName and Address columns. In the response format, you can write like the following

Dear [FName] [LName], Your address is [Address]

Please note that in response format, function parameters will not work. You have to use the Response column names and put them inside the square bracket to format the response text. Same applies to the Insert action.

API

The SMS server has the following APIs. You have to apply this APIs by connecting to TCP port 2000 of the computer running SMS server.

To call the API simply write the command using the WriteLine function of any programming language. Now flush the bytes to the server and the read a line. This line is the response from the server. The commands are as follows

Command

Appliance

Result

SQ

WriteLine(“SQ”)

ReadLine()

A number between 0-100 indicating the signal quality

NSQ

WriteLine(“NSQ”)

ReadLine()

Returns the number of SMS in the sending list.

NPQ

WriteLine(“NPQ”)

ReadLine()

Returns the number of SMS in the processing list.

CD

WriteLine(“CD”)

ReadLine()

Return the current device details

DL

WriteLine(“DL”)

ReadLine()

Returns a list of available devices

SMS

WriteLine(“SMS”)

WriteLine(phone numbers)

WriteLine(Message)

ReadLine()

Returns the status of acceptance and any reasons if acceptance fails.

Conclusion

Hopefully this comprehensive tutorial will help you to start using the SMS server. If you require further help or if you have any suggestion, please contact the developer directly at

E-mail: Shuhan@onuprova.com

 

 

 

Last edited Oct 22, 2011 at 3:02 AM by Shuhan, version 2

Comments

No comments yet.