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.

| Parameter | Description | |-----------|-------------| | oAuthClientId | OAuth 2 Client ID | | oAuthClientSecret | OAuth 2 Client Secret |

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.

| Scope Name | Description | | --- | --- | | SMS | |

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

| Parameter | Tags | Description | |-----------|------|-------------| | payload | Required | A JSON or XML payload containing the recipient's phone number and text message. The recipient number should be in the format '04xxxxxxxx' where x is a digit |

Example Usage

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

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

    
	});

Errors

| Error Code | Error Description | |------------|-------------------| | 400 | Invalid or missing request parameters | | 401 | Invalid or no credentials passed in the request | | 403 | Authorization credentials passed and accepted but account does not have permission | | 404 | The requested URI does not exist | | 405 | The requested resource does not support the supplied verb | | 415 | API does not support the requested content type | | 422 | The request is formed correctly, but due to some condition the request cannot be processed e.g. email is required and it is not provided in the request | | 500 | An internal error occurred when processing the request | | 501 | The HTTP method being used has not yet been implemented for the requested resource | | 503 | The service requested is currently unavailable |

getMessageStatus

Retrieve the status of a single outgoing SMS message.

function getMessageStatus(messageId, callback)

Parameters

| Parameter | Tags | Description | |-----------|------|-------------| | messageId | Required | Unique identifier of a message - it is the value returned from a previous POST call to https://api.telstra.com/v2/messages/sms |

Example Usage

    var messageId = 'messageId';

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

    
	});

Errors

| Error Code | Error Description | |------------|-------------------| | 400 | Invalid or missing request parameters | | 401 | Invalid or no credentials passed in the request | | 403 | Authorization credentials passed and accepted but account does not have permission | | 404 | The requested URI does not exist | | 405 | The requested resource does not support the supplied verb | | 415 | API does not support the requested content type | | 422 | The request is formed correctly, but due to some condition the request cannot be processed e.g. email is required and it is not provided in the request | | 500 | An internal error occurred when processing the request | | 501 | The HTTP method being used has not yet been implemented for the requested resource | | 503 | The service requested is currently unavailable |

retrieveMessages

Retrieve the unread incoming SMS messages

function retrieveMessages(callback)

Example Usage

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

    
	});

Errors

| Error Code | Error Description | |------------|-------------------| | 400 | Invalid or missing request parameters | | 401 | Invalid or no credentials passed in the request | | 403 | Authorization credentials passed and accepted but account does not have permission | | 404 | The requested URI does not exist | | 405 | The requested resource does not support the supplied verb | | 415 | API does not support the requested content type | | 422 | The request is formed correctly, but due to some condition the request cannot be processed e.g. email is required and it is not provided in the request | | 500 | An internal error occurred when processing the request | | 501 | The HTTP method being used has not yet been implemented for the requested resource | | 503 | The service requested is currently unavailable |

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

| Parameter | Tags | Description | |-----------|------|-------------| | authorization | Required | Authorization header in Basic auth format | | scope | Optional | Requested scopes as a space-delimited list. | | fieldParameters | Optional | Additional optional form parameters are supported by this method |

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

| Error Code | Error Description | |------------|-------------------| | 400 | OAuth 2 provider returned an error. | | 401 | OAuth 2 provider says client authentication failed. |

createRequestToken1

Tags: Skips Authentication

Create a new OAuth 2 token.

function createRequestToken1(authorization, scope, formParams, callback)

Parameters

| Parameter | Tags | Description | |-----------|------|-------------| | authorization | Required | Authorization header in Basic auth format | | scope | Optional | Requested scopes as a space-delimited list. | | fieldParameters | Optional | Additional optional form parameters are supported by this method |

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

| Error Code | Error Description | |------------|-------------------| | 400 | OAuth 2 provider returned an error. | | 401 | OAuth 2 provider says client authentication failed. |

Back to List of Controllers