Automate the SMS Server with JavaScript

Auron Software

You need a custom solution but you don’t want to spend the time to re-invent the wheel. That’s exactly why the Auron SMS Server gives you the ability to automate the SMS Server with JavaScript.

It’s more than just a way to send SMS, WhatsApp and other instant messages. Unlock its scripting capabilities, and it becomes your complete solution.

Why script my SMS automation?

There are many situations when you need custom behavior. To name just a few:

  • Immediate acknowledgement: Customers report a more positive support experience if they know right away that their request is well received.
  • Personalized response: You can reply to an existing customer using their full name or you can reference their existing query.
  • FAQ and self-service: Automatically reply with predefined answers, like store hours or product details to reduce your support load.
  • Feedback requests: After a purchase, send a message asking for a review or survey response.

And many more like this. In fact, chances are that, if you’re reading this, you may already have your own use case in mind.

The Auron SMS Server offers multiple ways to customize its behavior. Most notably you can use either a script language, like JavaScript or SQL Server or you can use a compiled language like C# or VB.Net.

A couple of advantages of using JavaScript:

  • JavaScript familiarity: Many developers already have a familiarity with JavaScript.
  • Code in place: Your changes are immediately effective. You can tweak and test immediately on the test server and export/import directly on the production server.
  • Rich Ecosystem: With JavaScript on windows you’ll have access to many built-in windows APIs. Find some of the in our scripting guide.
  • Built-in examples: The Auron SMS Server includes a lot of builtin example triggers. Also, the API reference in the knowledge base has JavaScript examples for most properties and methods.

Triggers and automatic message handling

By using triggers you’ll be able to automatically process incoming messages. But not just incoming messages but failed messages and succeeded messages as well. You can find a full overview of which message states are available for scripting here.

Triggers are especially useful for setting up things such as automatic replies and automatic forwards. The Auron SMS Server has a large number of prebuild scripts as well. All of these are available in JavaScript.

Some key use cases include:

  • Automatic replies: Respond instantly to incoming SMS, such as a receipt confirmation (e.g. “Thank you for your message!”).
  • Automatic forwards: Redirect message to another channel. Like forwarding an SMS to an e-mail or an e-mail to an SMS.
  • Status based actions: Process failed messages by retrying them or retrying them on a different channel.

Creating a simple example trigger

To see how triggers work we can setup a simple example trigger. Let’s use the auto reply example. You can create a trigger by opening the Auron SMS Server manager, going to the ‘Triggers’ node in the left tree-view and selecting ‘New Trigger’.

This will open a dialog with a list of all available trigger templates. Select the ‘Reply Trigger Template.’ The icon indicates that this template is available in JavaScript.

Creating a new 'auto reply' trigger.

In the next couple of steps, you’ll walk through the auto reply wizard, which helps you set up a trigger. First you’ll enter a name for the trigger and select which message channel it should listen to and lastly you’ll setup the reply body.

Finish the auto reply wizard

In the wizard you can use placeholders to shape the reply body. The placeholders that are available depend on the message type. For an SMS or WhatsApp message you’ll have the body and phone number but for an e-mail message you’ll also have the CC and BCC addresses etc.

If this is exactly what you had in mind then you can just click finish, enable the trigger and you’re done. If you need to do some more customizing or if you’re curious to know how the trigger works you can edit it by clicking the pencil on the right side of the trigger.

Inspecting your new trigger

On this first page you’ll find the trigger condition. This is a summary of what causes the trigger to run. Which message type it’s going to trigger for, on which status it’s going to trigger and which condition applies. The condition itself is a SQL expression. In this case it only runs for message that come in on the channel with ID ‘SMPP1’. If you remove that expression the trigger runs for every message. You can also expand the expression to narrow it down further.

Edit trigger condition

The ‘JavaScript’ tab is where the magic happens. That’s where you’ll find the reference to the trigger script. This is also where you can specify some common files to include. By default the Auron SMS Server includes a ‘Common.js’ file which you can expand to add JavaScript function that you’ll need to share between triggers.

Edit trigger script

The JavaScript structure

Click on edit next to the script file to edit or inspect the actual trigger script. The script can look a little intimidating if you’re not familiar with JavaScript, but if you look closely you’ll see that it’s actually very easy to understand.

The ‘ProcessMessageEx’ function at the top of the script is the main entry point for the trigger. From there it calls the ‘Reply’ function. The reply function, in turn, creates a new SMS message object, which uses the incoming message (objMessageIn) to setup the new message (objMessageOut).

You can see that this is where the target channel is set for the reply message. Also, you’ll notice the ReplacePlaceholders function, where the placeholder replacement from the wizard is done.

You’re completely free to change and update this script in any way you see fit. The only thing this script needs is the entry function ‘ProcessMessageEx’. Other than that you can change everything.

STR_DEBUGFILE       = "C:\\ProgramData\\Auron\\SMS Server\\Log\\TRIGGER1.txt"
B_ENABLE_DEBUG        = true

// ========================================================================
// Function: ProcessMessageEx
// ------------------------------------------------------------------------
// ProcessMessageEx trigger function to process incoming messages
// ========================================================================
function ProcessMessageEx(objMessageIn, objMessageDB, dctContext)
{
    Log(">> ProcessMessageEx")
        
    Reply(objMessageIn, objMessageDB)
    
    Log("<< ProcessMessageEx")
}


// ========================================================================
// Reply
// ------------------------------------------------------------------------
// Automatically reply this message
// ========================================================================
function Reply(objMessageIn, objMessageDB)
{
    Log(">> Reply")

    // reply to SMS message
    objMessageOut = objMessageDB.Create("SMS")
    objMessageOut.AddTrace("Reply to message from channel: [" + objMessageIn.ChannelID + "]")

    objMessageOut.ChannelID              = "SMPP1"
    objMessageOut.ToAddress              = objMessageIn.FromAddress
    objMessageOut.ToAddressTon           = objMessageIn.FromAddressTon          
    objMessageOut.ToAddressNpi           = objMessageIn.FromAddressNpi          
    objMessageOut.DataCoding             = objMessageIn.DataCoding        // in case of Unicode messages

    objMessageOut.Body                   = ReplacePlaceholders("Automatically generated reply.\r\n%BODY%", 
       objMessageIn.FromAddress, objMessageIn.ToAddress, objMessageIn.Body)    

    // save the message into the database
    objMessageDB.Save(objMessageOut)
    if (objMessageDB.LastError != 0)
    {
        sErrorDescription = objMessageDB.GetErrorDescription(objMessageDB.LastError)
        objMessageOut.AddTrace("Error replying to this message: [" + sErrorDescription + "]")
        objMessageOut.StatusID = "FAILED"
        Log("Error: Could not reply to this message: [" + sErrorDescription + "]")
    }

    Log("<< Reply")
}

// ========================================================================
// ReplacePlaceholders
// ------------------------------------------------------------------------
// Replace placeholder values
// ========================================================================
function ReplacePlaceholders(sFormat, sFromAddress, sToAddress, sBody)
{
    Log(">> ReplacePlaceholders")

    sResult = sFormat
    sResult = sResult.replace("%FROMADDRESS%", sFromAddress)
    sResult = sResult.replace("%TOADDRESS%", sToAddress)
    sResult = sResult.replace("%BODY%", sBody)
      
    Log("<< ReplacePlaceholders")
    
    return sResult
}

JavaScript around the Auron SMS Server

So far, we've setup a new trigger and looked at the script that it produces. But that's not all that we can do to automate the SMS Server with JavaScript.

The same API that's used inside triggers can also be used outside of the Auron SMS Server, for example, to script behavior from the Windows Task scheduler.

For example, let's setup a simple JavaScript that will send an e-mail message every day containing a report of the number of failed message in the last 24 hours. This is the script:

// File: FailedMessageReport.js
// Purpose: Check SMS Server MSSQL database for failed messages using AxMmServer.MessageDB Count() and save a summary message for an admin

// Create SMS Server MessageDB object
var objMessageDB = WScript.CreateObject("AxMmServer.MessageDB");

// Count failed messages from the last 24 hours using MSSQL syntax
var sFilter = "StatusID = 'FAILED' AND LastUpdate >= DATEADD(HOUR, -24, GETDATE())";
var nFailedCount = objMessageDB.Count(sFilter);
if (objMessageDB.LastError != 0) 
{
    WScript.Echo("Count failed: " + objMessageDB.GetErrorDescription(objMessageDB.LastError));
    WScript.Quit(1);
}

// Create and save a summary message to admin
var objNewMessage = objMessageDB.CreateMessage("SMS"); // Create an SMS message
objNewMessage.ToAddress = "+1234567890"; // Admin phone number
objNewMessage.Body = "Daily Report: " + nFailedCount + " messages failed in the last 24 hours.";
objMessageDB.Save(objNewMessage);

if (objMessageDB.LastError == 0) 
    WScript.Echo("Summary SMS saved successfully.");
else
    WScript.Echo("Failed to save summary: " + objMessageDB.GetErrorDescription(objMessageDB.LastError));

To run this script every day we'll setup the script in the Windows Task Scheduler by following these steps:

  1. Save the script: For example, use FailedMessageReport.js in C:\Scripts
  2. Open the Windows Task Scheduler
  3. Create task: Set the name to 'SMS Failed Report'
  4. Create trigger: In the Triggers tab click -New -> Action: "Start a program"
  5. Setup program: Name: "cscript.exe" Arguments: "C:\Scripts\FailedMessageReport.js"
  6. Condition: Check 'Run whether the user is logged on or not' and store the credentials

That's it. You can run the task manually to verify that it works. You now know exactly how to automate the SMS Server with JavaScript.

Try it for yourself

You can get started with the Auron SMS Server right away by downloading the trial here. The trial is fully functional for 30days.

If you need any help setting things up or if you have any other questions you can always contact us.