How can we help?

Setup a Web API

The easiest way to setup a Web API is to use the REST API channel.

This article describes an alternative way to build your own customized Web API.

 

This how-to will show you how to setup a Web API for the SMS Server. With this Web API in place you can use a simple HTTP GET or POST requests to send an SMS through the SMS Server.

Web API for the SMS Server

Web API for the SMS Server

This is useful in the following situations:

  • For sending SMS message from your website or web applications
  • When your application runs on a different server
  • When you want to send SMS from a Linux system
  • If you want to expose an HTTP interface to your customers
  • Etc…

Overview

By the end of this how-to you will be able to send an SMS by going to this URL:

http://<yourservername>:8080/sendsms.asp?to=+31622334455&body=Hello World

Where ‘<yourservername>‘ should be the name of your webserver. ‘+31622334455‘ should be replaced by the recipient phone nr. and ‘Hello World‘ should be replaced by the SMS body.

This how-to uses ASP classic in combination with IIS to setup a Web API for the SMS Server. This is by far the easiest way to quickly setup a fully working solution without installing any extra software since both IIS and ASP are a default part of Windows.

If you need a Web API which has a lot more features or you need to integrate into something existing please note that the SMS Server API will work great in PHP, ASP.Net as well as many other programming languages.

The SMS Server setup includes a lot of working examples for creating your own web interface as well as web API’s. To find these please navigate to C:\ProgramData\Auron\Samples\API after installing the SMS Server.

These instructions assume that you are using a fairly recent Microsoft Server operating system. Windows Server 2012 or newer. On Windows 10, for instance, enabling IIS will look slightly different.

We’ll go through the following steps:

  1. Setup the SMS Server
  2. Enable IIS
  3. Setup a new website
  4. Create Web API
  5. Testing the Web API
  6. (Optional) Expanding and improving

Setup the SMS Server

Follow these steps to setup the SMS Server. Please choose the following configuration options:

  • The configuration should be either standalone or server
  • The database should be SQL Server or Microsoft Azure

Next create an SMS channel. This can be an SMPP channel that connects to our test and demonstration gateway.

SMS Server with an SMS channel configured

SMS Server with an SMS channel configured

Enable IIS

The next step is to enable the IIS server. For this please click on the ‘Add roles and features‘ link in the Microsoft Windows Server Manager.

Add roles and features

Add roles and features

Depending on your server configuration you can accept all default setting until you come to the ‘Server Roles‘ page of the wizard. In the server roles page make sure to check ‘Web Server (IIS)‘. With checking this box a window will pop up which asks if you want to enable the ‘IIS Management Console’ as well. Confirm this by clicking ‘Add Features‘ and ‘Next‘.

Add web server role

Add web server role

The wizard will now include an extra page and sub-page: ‘Web Server role (IIS)‘ with ‘Role Services‘. In this page make sure that in the branch ‘Application Development‘ the box for ‘ASP‘ is checked. With checking this box another window will pop up which asks if you want to enable the ‘ISAPI Extensions‘ as well. Confirm this by clicking ‘Add Features‘ and ‘Next‘.

Enable Active Server Pages

Enable ASP (Active Server Pages)

Setup a new website

Now that IIS is configured please start the ‘Internet Information Services (IIS) Manager‘.

In the tree on the left of the manager click open the name of your server and right-click on the ‘Sites‘ folder. Select ‘Add Website…‘ to start setting up the Web API website.

IIS Manager - Add website

IIS Manager – Add website

In the add website dialog you can configure some basic settings. Please make sure of:

  • The name of the website. In this case: ‘rest_api‘.
  • The physical path of the website. In this case: ‘c:\inetpub\rest_api‘
  • The port number in the binding section of the dialog. In this case: 8080

Click on ‘OK‘ to create the website.

IIS - Add website

IIS – Add website

Create the Web API for the SMS Server

To create the web API we need to think of which functionality we want to expose and which format we want to use.

In this case we’re going to expose only three parameters:

  • To – The recipient of the SMS message
  • Body – The SMS body
  • Channel ID – (Optional) Channel ID to use

As a format we’re just going to use the very straight forward ‘form encoding‘. This is the easiest type of encoding to implement and will suite our purpose perfectly.

To create this API simply:

  1. Create a new file called ‘sendsms.asp‘ in the directory: ‘c:\inetpub\rest-api‘
  2. Open the file in notepad and copy/paste the script below into the file.
  3. Click on ‘File->Save’
<%
' gather request parameters
sToAddress = Request("To")
sBody = Request("Body")
sChannel = Request("Channel")
' TODO: Add more fields if required

' basic input checks
If sToAddress = "" OR sBody = "" Then
  Response.Write "Error: Require both 'To' and 'Body' request parameters"
  Response.End
End If

' create new message object and save to database
Set objMessageDb = CreateObject("AxMmServer.MessageDB")
Set objMessage = objMessageDb.Create("SMS")

objMessage.ToAddress = sToAddress
objMessage.Body = sBody
objMessage.ChannelID = sChannel
' TODO: Add more fields if required

objMessageDb.Save objMessage
If objMessageDb.LastError <> 0 Then
  Response.Write "Error: " & _
    objMessageDB.GetErrorDescription(objMessageDB.LastError)
  Response.End
End If

' trigger SMS Server to send new message
objMessageDb.NotifyStatusUpdate
Response.Write "Success: " & objMessage.ID
%>

In this script we use the MessageDB object to create a new SMS. After setting the request properties in the SMS the message is saved. The NotifyStatusUpdate notifies the SMS Server to send the new message right away.

Please read this FAQ item if you are having trouble sending Unicode SMS message using this script.

Testing the Web API

While the Web API is intended to be used from an application directly you can easily test it from a web browser.

In this case the URL to send a new SMS message should be:

http://<yourservername>:8080/sendsms.asp?to=+31622334455&body=Hello World

Where ‘<yourservername>‘ should be the name of your webserver. ‘+31622334455‘ should be replaced by the recipient phone nr. and ‘Hello World‘ should be replaced by the SMS body.

If you are sending messages from an application please make sure to ‘Url Encode‘ the phone number and SMS body. In Javascript you can use ‘encodeURI‘.

Web API test success

Web API test success

Now you know how to setup a web API for the SMS Server. The following section will show some ways in which to improve your new Web API.

Expanding and improving

While this setup will work for most purposes there are also a couple of improvements that can easily be made. For instance adding support for HTTPS or authorization.

The following sections will briefly discuss how to add these improvements.

More parameters

If you want to set the From as well as the To address, or if you want to include a DCS value or specify a batch or conversation ID. All of these these fields and more can easily be added.

The way to add extra fields is to expand both the ‘TODO: Add more fields if required‘ sections of the code. For every parameter add a request parameter and set it to the message object.

Find an overview of all SMS object properties here. Of course it’s easy to change this

Enable debugging

With our current setup it’s difficult to try different things because an error in the script will just result in an HTTP status 500. To change this so that the browser will show full ASP error messages please follow these instructions:

  1. Open the Internet Information Services (IIS) Manager
  2. Open your website in the right tree view
  3. Click on the ‘ASP‘ icon
  4. Click open the ‘Debugging Properties‘ item
  5. Double click the ‘Send Errors To Browser’ sub-item

This will cause the error to be sent to the browser only when testing on the server. To be able to test from a different PC please also:

  1. Click on the ‘Error Pages‘ icon in your website
  2. Click on ‘Edit Feature Settings…‘ on the right hand side
  3. In Error Responses change the setting to ‘Show detailed errors‘

Use the secure HTTPS protocol

To be able to use HTTPS you will need to have a certificate. For this you can either buy a certificate that is signed by a third party or you can create a self signed certificate.

To quickly create a self signed certificate for use with HTTPS please follow these steps:

  1. Open the Internet Information Services (IIS) Manager
  2. Click on your server name in the left tree view
  3. Click on the ‘Server Certificates‘ icon
  4. On the right hand side click on ‘Create Self-Signed Certificate…‘
  5. Enter a name for the certificate and select the ‘Web Hosting‘ certificate store
  6. Click on ‘OK’

You can secure you website using the HTTP protocol by following these steps:

  1. Open the Internet Information Services (IIS) Manager
  2. Open your website in the right tree view
  3. Click on the ‘Bindings…‘ icon on the right hand side
  4. Click op ‘Add…‘ to add another binding
  5. Select ‘HTTPS‘ instead of HTTP as the binding type
  6. On the bottom select your certificate under ‘SSL certificate‘
  7. Click on ‘OK’ and ‘Close’ to close all dialog boxes

If you are using a self-signed certificate you may get certificate errors when opening your website using HTTPS in a browser. These can be ignored.

Enable authentication

The easiest way to add authentication is to use basic-authentication. This must first be added as a feature to your website.

Note: Only use basic-authentication together with HTTPS from the previous section.

To add the basic-authentication features:

  1. Open the Windows ‘Server Manager‘ application
  2. Click on ‘Add roles and Features‘
  3. Click ‘Next‘ until you are at the ‘Server Roles‘ page
  4. Open items and sub-items: ‘Web Server (IIS)‘, ‘Web Server‘, ‘Security‘
  5. Check the box for ‘Basic Authentication‘
  6. Click next until you can finally click ‘Install‘.
  7. Reboot your server to make sure basic-authentication is available in IIS

To enable basic authentication in IIS:

  1. Open the Internet Information Services (IIS) Manager
  2. Open your website in the right tree view
  3. Click on the ‘Authentication‘ icon
  4. Select ‘Basic Authentication‘ and click on ‘Enable‘ on the right hand side
  5. Select ‘Anonymous Authentication‘  and click on ‘Disable‘ on the right hand side

You will now need to have an account on this server to be able to visit the Web API.