Send an SMS via Automation

Automations allow you to use events as a trigger to fire actions. For example, you can send an SMS when a user enters a geofence or if a user does not complete a journey such as checkout.

In this recipe, we'll show you how you can create an Automation to send an SMS when a custom Analytics event is tracked, using the example of a confirmation text message when an order is completed. We'll assume that the user's mobile number and name have been stored as attributes.

This example will use Twilio, but can be easily adapted for Nexmo or Sendinblue.

Ingredients

This recipe assumes that you have KScripts enabled for your app, you have a Twilio account and that users' mobile numbers and names are being stored as attributes.

Recipe

This recipe consists of two parts. Firstly, creating the Kscript methods to call the Twilio API and secondly adding an automation to fire these methods when a custom Analytics event is tracked.

KScript

Expand "Backend" in the left hand menu, select "API" and then click the "KScript" button. Create a new method called something like _sms_ and include the following JavaScript function:

function sendSMS(from, to, body) {
    var client = K.http.createClient('https://api.twilio.com');
    var ACCOUNT_SID = 'YOUR_TWILIO_ACCOUNT_SID';
    var AUTH_TOKEN = 'YOUR_TWILIO_AUTH_TOKEN';

    var headers = {
        'Authorization' : 'Basic ' + base64_encode(ACCOUNT_SID + ":" + AUTH_TOKEN)
    };

    var data =  {
        "From" : from,
        "To" : to,
        "Body" : body
    };

    var result = client.post('/2010-04-01/Accounts/' + ACCOUNT_SID + '/Messages', data, headers);

    if (failed(result)) {
        K.log(result.error);
    }
    else if (result.isError()) {
        K.log(result.getBody());
    }

    return result;
}

If you wish to use a different SMS service, see the Nexmo integration guide

Now, create another Kscript method called sendConfirmationSMS and paste in the following:

//
// Include SMS helper function
//
include("_sms_");
var FROM_NUMBER = "YOUR_TWILIO_FROM_NUMBER";

//
// Check we have all of the required parameters and
// we are only being called from an automation
//
// {
//     params : {
//         "installId" : "uuid",
//         "userId" : "identifier",
//         "triggerEvent" : {
//             "uuid" : "uuid",
//             "eventType" : "k.engage.geofenceEntered",
//             "happenedAt" : "DateTime::RFC3339_EXTENDED",
//             "data" : {
//                 "geofenceId" : 123
//             }
//         }
// }
if (!K.params.has("userId")) {
    throw ("Missing user id");
}

if (!K.params.has("triggerEvent")) {
     throw ("This script is intended for use with automations only");
}

//
// Check we have a mobile number for the user
//
var attributes = K.users.getAttributes(K.params.userId);
if (!attributes.has("sms")) {
    throw ("User does not have a mobile number.");
}

var greeting = "Hi";
if (attributes.has("name")) {
    greeting = attributes.get("name")
}

//
// Send an SMS
//
sendSMS(
    FROM_NUMBER,
    attributes.get("sms"),
    greeting + ", sit tight - your order is being processed."
);

Finally, click the "Deploy" button to deploy your KScript methods to our API Servers.

Automation

Now we can add our automation. Automations are comprised of an availability period (e.g. for time-limited promotions) and one or more rules. Each rule is in turn comprised of a trigger (audience and event) and one or more actions (e.g. running a KScript).

To add an automation, expand "Messaging" in the left menu, select "Automation" and then click the primary action button. Give the automation a meaningful name and click "Save" so we can add a rule.

To add a rule to the automation, click the primary action button. The trigger is comprised of audience and an event. We're not going to limit the audience of this trigger any further, so just click "Next".

Now, from the trigger event drop-down, select the custom analytics event that is to be used to trigger this rule and click 'Next' when ready to add actions to the rule.

Select the sendConfirmationSMS method from the KScript dropdown and click "Done" to add the automation rule.

That's It! Now, when a user completes their order, sending the custom analytics event to Kumulos, the KScript method will send a confirmation text message to the address stored in the user's attributes.

If your Twilio (or Nexmo) account is in trial mode, then you can only send messages to verified phone numbers such as the number you provided during the signup process. Also, the FROM_NUMBER must be a number or short code purchased via Twilio (or Nexmo).

Further reading

Please see KScript docs for a full function reference and Automation docs for more details on triggers and actions.