ShoutOUT Engage SDK

Requirements

The SDK requires Node.js 4.x or later and npm to resolve its dependencies.

Installation

Install @shoutoutlabs/engage-sdk from npm:

npm install @shoutoutlabs/engage-sdk --save

Configure the SDK

var ShoutoutClient = require('@shoutoutlabs/engage-sdk');

var apiKey = 'XXXXXXXXX.XXXXXXXXX.XXXXXXXXX';
var debug = true, verifySSL = false;

var client = new ShoutoutClient(apiKey, debug, verifySSL);

Send a message

sendMessage sends through the Direct Message API at POST /v1/messages.

var message = {
    source: 'ShoutDEMO',
    destinations: ['94777123456'],
    content: {
        sms: 'Sent via SMS Gateway'
    },
    transports: ['sms']
};

client.sendMessage(message, (error, result) => {
    if (error) {
        console.error('error ', error);
    } else {
        console.log('result ', result);
        // result.cost is a decimal string, for example "2.00"
        // result.responses[0].reference_id can be used to look up delivery status
    }
});

Send a message using a template

Use a saved template by passing templateId and customAttributes. Template placeholders such as {{name}} and {{code}} are replaced with matching custom attributes. content and templateId are mutually exclusive.

var message = {
    source: 'ShoutDEMO',
    destinations: ['94777123456'],
    templateId: '***',
    customAttributes: {
        name: 'Kasun',
        order_id: 'ORD-4821'
    },
    transports: ['sms']
};

client.sendMessage(message, (error, result) => {
    if (error) {
        console.error('error ', error);
    } else {
        console.log('result ', result);
    }
});

Send a priority message

sendPriorityMessage uses the same POST /v1/messages endpoint and setspriority: 1 when no priority is provided. Priority messages are queued ahead of normal transactional traffic for a small additional credit surcharge per destination, reflected in the returned cost. Set priority: 0 to opt out.

var message = {
    source: 'ShoutDEMO',
    destinations: ['94777123456'],
    content: {
        sms: 'Your time-sensitive alert'
    },
    transports: ['sms'],
    priority: 1
};

client.sendPriorityMessage(message, (error, result) => {
    if (error) {
        console.error('error ', error);
    } else {
        console.log('result ', result);
    }
});

Send an OTP

sendOtp sends a one-time password to one recipient through POST /send. The content.sms value must contain the {{code}} placeholder. Save the returned referenceId; it is required to verify the code.

var otpRequest = {
    source: 'ShoutDEMO',
    destination: '94777123456',
    content: {
        sms: 'Your verification code is {{code}}'
    },
    transport: 'sms'
};

client.sendOtp(otpRequest, (error, result) => {
    if (error) {
        console.error('error ', error);
    } else {
        console.log('result ', result);
        // result.referenceId is required to verify the OTP later
    }
});

Verify an OTP

verifyOtp checks the user-entered code against the referenceId throughPOST /verify. An invalid code returns a successful HTTP response withvalid: false; it is not returned as an error.

var verifyRequest = {
    code: '12345',
    referenceId: '***'
};

client.verifyOtp(verifyRequest, (error, result) => {
    if (error) {
        console.error('error ', error);
    } else {
        console.log('result ', result);
        // result.valid indicates whether the code was correct
    }
});

Migrating from shoutout-sdk

The package was renamed from shoutout-sdk to @shoutoutlabs/engage-sdk in v1.0.0. The old package is no longer updated. Update both your dependency and import when upgrading.

• sendMessage now targets POST /v1/messages.
• cost is now returned as a decimal string at the top level and in each response item.
• Each response item includes a reference_id UUID for delivery-status lookups.
• Direct Message API calls use the Authorization: Apikey <key> header format.