Setup a Web API

The easiest way to set up 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 shows how to set up a Web API for Auron Omni. With this Web API in place you can use simple HTTP GET or POST requests to send an SMS through Auron Omni.

Web API for Auron Omni

This is useful in the following situations:

• To send SMS messages 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://:8080/sendsms.asp?to=+31622334455&body=Hello World

Where is the name of your web server. +31622334455 is the recipient phone number and Hello World is the SMS body.

This how to uses ASP Classic in combination with IIS to set up a Web API for Auron Omni. This is one of the easiest ways to quickly set up a working solution because both IIS and ASP are included with Windows.

If you need a Web API with more features or you want to integrate into an existing system, the Auron Omni API works well in PHP, ASP.NET and many other programming languages.

The Auron Omni setup includes working examples for creating your own web interface and Web APIs. You can find these in C:\ProgramData\Auron\Samples\API after installing Auron Omni.

These instructions assume you use a recent Microsoft Server operating system such as Windows Server 2012 or newer. On Windows 10 the IIS steps look slightly different.

We go through the following steps:

1. Set up Auron Omni
2. Enable IIS
3. Set up a new website
4. Create Web API
5. Test the Web API
6. (Optional) Expand and improve

Set up Auron Omni

Follow these steps to set up Auron Omni. Please choose the following configuration options:

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

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

Auron Omni with an SMS channel configured

Enable IIS

The next step is to enable IIS. Click Add roles and features in the Microsoft Windows Server Manager.

Add roles and features

Follow the wizard with default settings until you reach the Server Roles page. Check Web Server (IIS). A window appears asking to add the IIS Management Console. Select Add Features and continue.

Add web server role

On the Role Services page, under Application Development, check ASP. A prompt appears to add ISAPI Extensions. Select Add Features and continue.

Enable ASP (Active Server Pages)

Set up a new website

Start Internet Information Services (IIS) Manager.

In the left tree view, right click Sites and select Add Website.

IIS Manager – Add website

Use these settings:

• Name: rest_api
• Physical path: c:\inetpub\rest_api
• Port: 8080

Click OK.

IIS – Add website

Create the Web API for Auron Omni

We expose three parameters:

• To The recipient of the SMS message
• Body The SMS body
• Channel ID Optional channel ID to use

We use simple form encoding.

To create the API:

1. Create a file called sendsms.asp in c:\inetpub\rest_api
2. Open it in Notepad and paste the script below
3. Save the file

<%
sToAddress = Request("To")
sBody = Request("Body")
sChannel = Request("Channel")

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

Set objMessageDb = CreateObject("AxMmServer.MessageDB")
Set objMessage = objMessageDb.Create("SMS")

objMessage.ToAddress = sToAddress
objMessage.Body = sBody
objMessage.ChannelID = sChannel

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

objMessageDb.NotifyStatusUpdate
Response.Write "Success: " & objMessage.ID
%>

This script uses the MessageDB object to create and store a new SMS. After saving the message, NotifyStatusUpdate triggers Auron Omni to send it immediately.

Test the Web API

You can test the Web API directly in a browser.

Use this URL:

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

If you call it from an application, make sure to URL encode parameters. In JavaScript you can use encodeURI.

Web API test success

Now you know how to set up a Web API for Auron Omni.

Expand and improve

This setup works for most cases, but you can improve it further.

More parameters

You can easily add more fields such as From address, DCS value, batch ID or conversation ID.

Add new request parameters in the TODO sections and map them to the message object.

See the SMS object properties for available fields.

Enable debugging

To show detailed ASP errors:

1. Open IIS Manager
2. Select your website
3. Open ASP
4. Enable Send Errors to Browser

Also enable detailed errors:

1. Open Error Pages
2. Select Edit Feature Settings
3. Set to Show detailed errors

Use HTTPS

Create a certificate:

1. Open IIS Manager
2. Select the server
3. Open Server Certificates
4. Select Create Self Signed Certificate
5. Enter a name and select Web Hosting

Enable HTTPS:

1. Open IIS Manager
2. Select your website
3. Open Bindings
4. Add an HTTPS binding
5. Select the certificate

If you use a self signed certificate you may see browser warnings.

Enable authentication

Use Basic Authentication with HTTPS.

Install it:

1. Open Server Manager
2. Add Roles and Features
3. Go to Web Server Security
4. Enable Basic Authentication
5. Install and restart if needed

Enable it in IIS:

1. Open IIS Manager
2. Select your website
3. Open Authentication
4. Enable Basic Authentication
5. Disable Anonymous Authentication

You now require a server account to access the Web API.