telstrasmsmessagingapilib v2.2.1

Deprecation Warning

This package is now deprecated and has been renamed to telstra-sms-messaging located here. Please update your project to telstra-sms-messaging.

Getting started

The Telstra SMS Messaging API allows your applications to send and receive SMS text messages from Australia's leading network operator. It also allows your application to track the delivery status of both sent and received SMS messages.

Initialization

Authentication

In order to setup authentication in the API client, you need the following information.

API client can be initialized as following:

const lib = require('telstrasmsmessagingapilib/lib');

// Configuration parameters and credentials
lib.Configuration.oAuthClientId = "oAuthClientId"; // OAuth 2 Client ID
lib.Configuration.oAuthClientSecret = "oAuthClientSecret"; // OAuth 2 Client Secret

You must now authorize the client.

Authorizing your client

This SDK uses OAuth 2.0 authorization to authorize the client.

The authorize() method will exchange the OAuth client credentials for an access token. The access token is an object containing information for authorizing client requests.

You must pass the scopes for which you need permission to access.

const tokenPromise = oAuthManager.authorize([lib.OAuthScopeEnum.SMS]);

The Node.js SDK supports both callbacks and promises. So, the authorize call returns a promise and also returns response back in the callback (if one is provided)

The client can now make authorized endpoint calls.

Scopes

Scopes enable your application to only request access to the resources it needs while enabling users to control the amount of access they grant to your application. Available scopes are defined in the lib/Models/OAuthScopeEnum enumeration.

Storing an access token for reuse

It is recommended that you store the access token for reuse.

This code snippet stores the access token in a data store. For this example, node-localstorage is being used as the data store.

const lib = require('lib');
const LocalStorage = require('node-localstorage').LocalStorage;
const localStorage = new LocalStorage('./scratch');

localStorage.setItem('token', lib.Configuration.oAuthToken);

Creating a client from a stored token

To authorize a client from a stored access token, just set the access token in Configuration along with the other configuration parameters before making endpoint calls:

// load token later...
const lib = require('lib');
const LocalStorage = require('node-localstorage').LocalStorage;
const localStorage = new LocalStorage('./scratch');

lib.Configuration.oAuthToken = localStorage.getItem('token');

Complete example

In this example, app.js will check if the access token has been set in the SDK. If it has been, API calls can be made. Otherwise, client has to be authorized first before making API calls.
This example makes use of node-localstorage for handling data persistence.

app.js

const express = require('express');
const app = express();

const PORT = 1800;

const lib = require('telstrasmsmessagingapilib/lib');
const oAuthManager = lib.OAuthManager;
const LocalStorage = require('node-localstorage').LocalStorage;
const localStorage = new LocalStorage('./scratch');

lib.Configuration.oAuthClientId = 'oAuthClientId'; // OAuth 2 Client ID
lib.Configuration.oAuthClientSecret = 'oAuthClientSecret'; // OAuth 2 Client Secret

const storedToken = localStorage.getItem('token');
if (storedToken !== null && storedToken !== undefined) {
    lib.Configuration.oAuthToken = storedToken;
}
lib.Configuration.oAuthTokenUpdateCallback = function(token) {
    // token is the updated access_token
    localStorage.setItem('token', token);
};

app.listen(PORT, () => {
    console.log('Listening on port ' + PORT);
});

app.get('/', (req, res) => {
    if (oAuthManager.isTokenSet()) {
        // token is already stored in the client
        // make API calls as required
    } else {
        const scopes = [lib.OAuthScopeEnum.SMS];
        const promise = oAuthManager.authorize(scopes);
        promise.then((success) => {
            // client authorized. API calls can be made
        }, (exception) => {
            // error occurred, exception will be of type lib/Exceptions/OAuthProviderException
        });
    }
});

Class Reference

List of Controllers

• SMSController
• OAuthAuthorizationController

SMSController

Get singleton instance

The singleton instance of the SMSController class can be accessed from the API Client.

var controller = lib.SMSController;

createSendMessage

Send an SMS to a Australian or International mobile phone.

function createSendMessage(payload, callback)

Parameters

Example Usage

    var payload = new SendSMSRequest({"key":"value"});

    controller.createSendMessage(payload, function(error, response, context) {

    
	});

Errors

getMessageStatus

Retrieve the status of a single outgoing SMS message.

function getMessageStatus(messageId, callback)

Parameters

Example Usage

    var messageId = 'messageId';

    controller.getMessageStatus(messageId, function(error, response, context) {

    
	});

Errors

retrieveMessages

Retrieve the unread incoming SMS messages

function retrieveMessages(callback)

Example Usage

    controller.retrieveMessages(function(error, response, context) {

    
	});

Errors

Back to List of Controllers

OAuthAuthorizationController

Get singleton instance

The singleton instance of the OAuthAuthorizationController class can be accessed from the API Client.

var controller = lib.OAuthAuthorizationController;

createRequestToken

Tags: Skips Authentication

Create a new OAuth 2 token.

function createRequestToken(authorization, scope, formParams, callback)

Parameters

Example Usage

    var authorization = 'Authorization';
    var scope = 'scope';
    // key-value map for optional form parameters
    var formParams = [];

    controller.createRequestToken(authorization, scope, formParams, function(error, response, context) {

    
	});

Errors

createRequestToken1

Tags: Skips Authentication

Create a new OAuth 2 token.

function createRequestToken1(authorization, scope, formParams, callback)

Parameters

Example Usage

    var authorization = 'Authorization';
    var scope = 'scope';
    // key-value map for optional form parameters
    var formParams = [];

    controller.createRequestToken1(authorization, scope, formParams, function(error, response, context) {

    
	});

Errors

Back to List of Controllers