ShoutOUT SDK for Nodejs

version: 1.1.0

ShoutOUT Engage is a customer engagement platform that lets businesses send SMS, OTP, and other messaging campaigns to their customers. This SDK provides a Node.js client for the ShoutOUT Engage messaging APIs.

v1.1.0 — OTP API support

Adds client.sendOtp(...) and client.verifyOtp(...) for sending and verifying One Time Passwords via SMS (POST /send and POST /verify), authenticated the same way as sendMessage (configureMessagesApiKey). See "Send OTP" / "Verify OTP" below.

v1.0.0 — Renamed to @shoutoutlabs/engage-sdk, Direct Message API changes

Starting with this version, the package is published as @shoutoutlabs/engage-sdk (previously shoutout-sdk). The old shoutout-sdk package on npm is not updated further — update your package.json dependency and require('@shoutoutlabs/engage-sdk') import when upgrading.

sendMessage now targets the current Direct Message API (POST /v1/messages) instead of the legacy /coreservice/messages route. This is a breaking change if you parse the response:

• cost is now a decimal string (e.g. "2.00") instead of a number, both at the top level and per item in responses.
• Each item in responses now includes a reference_id (UUID) you can use to look up delivery status.
• The client now authenticates Direct Message API calls with the Authorization: Apikey <key> header format required by the new backend (previously sent as Bearer <key>, which the new auth middleware rejects).

New capabilities:

• Send using a saved message template via templateId + customAttributes (see below).
• Send with paid priority delivery via client.sendPriorityMessage(...), which defaults priority to 1 on the versioned POST /v1/messages endpoint.

Requirements

This SDK requires a Node.js (at least version 4.x). It also requires the Node Package Manager aka npm to resolve the dependencies.

Installation

You can install @shoutoutlabs/engage-sdk via npm

Via NPM

@shoutoutlabs/engage-sdk is available on NPM as the @shoutoutlabs/engage-sdk package

Installation

npm install @shoutoutlabs/engage-sdk --save

Configure 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 Message

####Example

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, e.g. "2.00"
        // result.responses[0].reference_id can be used to look up delivery status
    }
});

###Send Message via Template

Use a saved message template to avoid repeating content in every request. Placeholders in the template ({{name}}, {{code}}, etc.) are substituted from customAttributes. content and templateId are mutually exclusive.

####Example

var message = {
    source: 'ShoutDEMO',
    destinations: ['94777123456'],
    templateId: '8a3c1f2b-4d9e-4c3a-b1f2-9e8d7c6b5a4e',
    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 Priority Message

Sends via the same POST /v1/messages endpoint as sendMessage, but automatically sets priority: 1 on the message if you don't already specify one. priority: 1 queues the message ahead of normal transactional traffic for a small additional credit surcharge per destination (reflected in the returned cost). Pass priority: 0 explicitly in the message to opt out of priority delivery while still using sendPriorityMessage.

####Example

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

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

###Send OTP

Sends a One Time Password (OTP) to a single recipient via SMS by POSTing to POST /send. content.sms must include the {{code}} placeholder, which is substituted with the generated code. The response includes a referenceId (UUID) which you must keep to verify the code later.

####Example

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 OTP

Verifies a code entered by the user against the referenceId returned by sendOtp, by POSTing to POST /verify. An invalid code is still a 200 response with valid: false, not an error.

####Example

var verifyRequest = {
    code: '12345',
    referenceId: 'a3f1c2b4-9e87-4c3a-b1f2-9e8d7c6b5a4e'
};

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