telstramessagingapitestlib

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.

How to Build

The generated SDK relies on Node Package Manager (NPM) being available to resolve dependencies. If you don't already have NPM installed, please go ahead and follow instructions to install NPM from here. The SDK also requires Node to be installed. If Node isn't already installed, please install it from here

NPM is installed by default when Node is installed

To check if node and npm have been successfully installed, write the following commands in command prompt:

• node --version
• npm -version

Now use npm to resolve all dependencies by running the following command in the root directory (of the SDK folder):

npm install

This will install all dependencies in the node_modules folder.

Once dependencies are resolved, you will need to move the folder TelstraMessagingAPITestLib in to your node_modules folder.

How to Use

The following section explains how to use the library in a new project.

1. Open Project Folder

Open an IDE/Text Editor for JavaScript like Sublime Text. The basic workflow presented here is also applicable if you prefer using a different editor or IDE.

Click on File and select Open Folder.

Select the folder of your SDK and click on Select Folder to open it up in Sublime Text. The folder will become visible in the bar on the left.

2. Creating a Test File

Now right click on the folder name and select the New File option to create a new test file. Save it as index.js Now import the generated NodeJS library using the following lines of code:

var lib = require('lib');

Save changes.

3. Running The Test File

To run the index.js file, open up the command prompt and navigate to the Path where the SDK folder resides. Type the following command to run the file:

node index.js

How to Test

These tests use Mocha framework for testing, coupled with Chai for assertions. These dependencies need to be installed for tests to run. Tests can be run in a number of ways:

Method 1 (Run all tests)

1. Navigate to the root directory of the SDK folder from command prompt.
2. Type mocha --recursive to run all the tests.

Method 2 (Run all tests)

1. Navigate to the ../test/Controllers/ directory from command prompt.
2. Type mocha * to run all the tests.

Method 3 (Run specific controller's tests)

1. Navigate to the ../test/Controllers/ directory from command prompt.
2. Type mocha Telstra Messaging API testController to run all the tests in that controller file.

To increase mocha's default timeout, you can change the TEST_TIMEOUT parameter's value in TestBootstrap.js.

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('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.NSMS]);

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
NSMS	NSMS

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 lib = require('lib');
const oAuthManager = lib.OAuthManager;
 
lib.Configuration.oAuthClientId = 'oAuthClientId'; // OAuth 2 Client ID
lib.Configuration.oAuthClientSecret = 'oAuthClientSecret'; // OAuth 2 Client Secret
 
// this method will be called whenever the token updates
// you can update the storage you're using with the updated token
lib.Configuration.oAuthTokenUpdateCallback = (token) => {
    // token is the updated access_token
};
 
if (oAuthManager.isTokenSet()) {
    // token is already stored in the client
    // make API calls as required
} else {
    const scopes = [lib.OAuthScopeEnum.NSMS];
    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

• AuthenticationController
• MessagingController
• ProvisioningController

AuthenticationController

Get singleton instance

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

var controller = lib.AuthenticationController;

createAuthToken

Tags: Skips Authentication

Generate authentication token

function createAuthToken(clientId, clientSecret, grantType, callback)

Parameters

Parameter	Tags	Description
clientId	Required	TODO: Add a parameter description
clientSecret	Required	TODO: Add a parameter description
grantType	Required DefaultValue	TODO: Add a parameter description

Example Usage

 
    var clientId = client_id;
    var clientSecret = client_secret;
    var grantType = grant_type;
 
    controller.createAuthToken(clientId, clientSecret, grantType, function(error, response, context) {
 
    
    });

Errors

Error Code	Error Description
400	unsupported_grant_type
401	invalid_client
404	The requested URI does not exist
503	The service requested is currently unavailable
0	An internal error occurred when processing the request

Back to List of Controllers

MessagingController

Get singleton instance

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

var controller = lib.MessagingController;

getSMSStatus

Get Message Status

function getSMSStatus(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.getSMSStatus(messageId, function(error, response, context) {
 
    
    });

Errors

Error Code	Error Description
400	Invalid or missing request parameters NOT-PROVISIONED Request flagged as containing suspicious content
401	Invalid access token. Please try with a valid token
403	Authorization credentials passed and accepted but account does not have permission SpikeArrest-The API call rate limit has been exceeded
404	The requested URI does not exist OLD-NONEXISTANT-MESSAGE-ID RESOURCE-NOT-FOUND
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	Technical error : Unable to route the message to a Target Endpoint : An error has occurred while processing your request, please refer to API Docs for summary on the issue
501	The HTTP method being used has not yet been implemented for the requested resource
503	The service requested is currently unavailable
0	An internal error occurred when processing the request

retrieveSMSResponses

Retrieve Messages

function retrieveSMSResponses(callback)

Example Usage

 
 
    controller.retrieveSMSResponses(function(error, response, context) {
 
    
    });

Errors

Error Code	Error Description
400	Invalid or missing request parameters NOT-PROVISIONED Request flagged as containing suspicious content
401	Invalid access token. Please try with a valid token
403	Authorization credentials passed and accepted but account does not have permission SpikeArrest-The API call rate limit has been exceeded
404	The requested URI does not exist RESOURCE-NOT-FOUND
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	Technical error : Unable to route the message to a Target Endpoint : An error has occurred while processing your request, please refer to API Docs for summary on the issue
501	The HTTP method being used has not yet been implemented for the requested resource
503	The service requested is currently unavailable
0	An internal error occurred when processing the request

createSendSMS

Send Message

function createSendSMS(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.createSendSMS(payload, function(error, response, context) {
 
    
    });

Errors

Error Code	Error Description
400	Invalid or missing request parameters TO-MSISDN-NOT-VALID SENDER-MISSING DELIVERY-IMPOSSIBLE FROM-MSISDN-TOO-LONG BODY-TOO-LONG BODY-MISSING TO-MSISDN-TOO-LONG TECH-ERR BODY-NOT-VALID NOT-PROVISIONED Request flagged as containing suspicious content
401	Invalid access token. Please try with a valid token
403	Authorization credentials passed and accepted but account does not have permission SpikeArrest-The API call rate limit has been exceeded
404	The requested URI does not exist RESOURCE-NOT-FOUND
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	Technical error : Unable to route the message to a Target Endpoint : An error has occurred while processing your request, please refer to API Docs for summary on the issue
501	The HTTP method being used has not yet been implemented for the requested resource
503	The service requested is currently unavailable
0	An internal error occurred when processing the request

getMMSStatus

Get MMS Status

function getMMSStatus(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/mms

Example Usage

 
    var messageid = 'messageid';
 
    controller.getMMSStatus(messageid, function(error, response, context) {
 
    
    });

Errors

Error Code	Error Description
400	Invalid or missing request parameters NOT-PROVISIONED Request flagged as containing suspicious content
401	Invalid access token. Please try with a valid token
403	Authorization credentials passed and accepted but account does not have permission SpikeArrest-The API call rate limit has been exceeded
404	The requested URI does not exist OLD-NONEXISTANT-MESSAGE-ID RESOURCE-NOT-FOUND
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	Technical error : Unable to route the message to a Target Endpoint : An error has occurred while processing your request, please refer to API Docs for summary on the issue
501	The HTTP method being used has not yet been implemented for the requested resource
503	The service requested is currently unavailable
0	An internal error occurred when processing the request

createSendMMS

Send MMS

function createSendMMS(body, callback)

Parameters

Parameter	Tags	Description
body	Required	A JSON or XML payload containing the recipient's phone number

and MMS message.The recipient number should be in the format '04xxxxxxxx' where x is a digit |

Example Usage

 
    var body = new SendMMSRequest({"key":"value"});
 
    controller.createSendMMS(body, function(error, response, context) {
 
    
    });

Errors

Error Code	Error Description
400	Invalid or missing request parameters MMS-TYPE-MISSING MMS-PAYLOAD-MISSING MMS-FILENAME-MISSING DELIVERY-IMPOSSIBLE TO-MSISDN-NOT-VALID SENDER-MISSING DELIVERY-IMPOSSIBLE SUBJECT-TOO-LONG FROM-MSISDN-TOO-LONG TO-MSISDN-TOO-LONG NOT-PROVISIONED Request flagged as containing suspicious content
401	Invalid access token. Please try with a valid token
403	Authorization credentials passed and accepted but account does not have permission SpikeArrest-The API call rate limit has been exceeded
404	The requested URI does not exist RESOURCE-NOT-FOUND
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	Technical error : Unable to route the message to a Target Endpoint : An error has occurred while processing your request, please refer to API Docs for summary on the issue
501	The HTTP method being used has not yet been implemented for the requested resource
503	The service requested is currently unavailable
0	An internal error occurred when processing the request

Back to List of Controllers

ProvisioningController

Get singleton instance

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

var controller = lib.ProvisioningController;

getSubscription

Get mobile number subscription for an account

function getSubscription(callback)

Example Usage

 
 
    controller.getSubscription(function(error, response, context) {
 
    
    });

Errors

Error Code	Error Description
400	Invalid or missing request parameters
401	Invalid access token. Please try with a valid token
403	Authorization credentials passed and accepted but account does not have permission SpikeArrest-The API call rate limit has been exceeded
404	The requested URI does not exist RESOURCE-NOT-FOUND
500	Technical error : Unable to route the message to a Target Endpoint : An error has occurred while processing your request, please refer to API Docs for summary on the issue
0	An internal error occurred when processing the request

createSubscription

Provision a mobile number

function createSubscription(body, callback)

Parameters

Parameter	Tags	Description
body	Required	A JSON payload containing the required attributes

Example Usage

 
    var body = new ProvisionNumberRequest({"key":"value"});
 
    controller.createSubscription(body, function(error, response, context) {
 
    
    });

Errors

Error Code	Error Description
400	Invalid or missing request parameters
401	Invalid access token. Please try with a valid token
403	Authorization credentials passed and accepted but account does not have permission SpikeArrest-The API call rate limit has been exceeded
404	The requested URI does not exist RESOURCE-NOT-FOUND
500	Technical error : Unable to route the message to a Target Endpoint : An error has occurred while processing your request, please refer to API Docs for summary on the issue
0	An internal error occurred when processing the request

deleteSubscription

Delete a mobile number subscription from an account

function deleteSubscription(body, callback)

Parameters

Parameter	Tags	Description
body	Required	EmptyArr

Example Usage

 
    var body = new DeleteNumberRequest({"key":"value"});
 
    controller.deleteSubscription(body, function(error, response, context) {
 
    
    });

Errors

Error Code	Error Description
400	Invalid or missing request parameters
401	Invalid access token. Please try with a valid token
403	Authorization credentials passed and accepted but account does not have permission SpikeArrest-The API call rate limit has been exceeded
404	The requested URI does not exist RESOURCE-NOT-FOUND
500	Technical error : Unable to route the message to a Target Endpoint : An error has occurred while processing your request, please refer to API Docs for summary on the issue
0	An internal error occurred when processing the request

Back to List of Controllers