telstra-sms-messaging v1.1.5

Deprecation warning

This version of the Messaging SDK is now deprecated and will no longer be supported. The newest offical version of the Telstra Messaging API Nodejs SDK can be found here.

Getting started

The Telstra Messaging API allows your applications to send SMS and MMS 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 messages.

Installation

Install with NPM

npm install telstra-sms-messaging --save

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('telstra-sms-messaging/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.

Authorization 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.

app.js

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

const PORT = 1800;

const lib = require('telstra-sms-messaging/lib');
const oAuthManager = lib.OAuthManager;

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

lib.Configuration.oAuthTokenUpdateCallback = function(token) {
    // 'token' holds the new access token
    console.log(token);
};

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

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

Class Reference

List of Controllers

• MessagingController
• OAuthAuthorizationController

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

Example Usage

    var messageId = 'messageId';

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

    
    });

Errors

the request cannot be processed e.g. email is required and it is not provided in the request | | 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

the request cannot be processed e.g. email is required and it is not provided in the request | | 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

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

the request cannot be processed e.g. email is required and it is not provided in the request | | 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

Example Usage

    var messageid = 'messageid';

    controller.getMMSStatus(messageid, function(error, response, context) {

    
    });

Errors

createSendMMS

Send MMS

function createSendMMS(body, callback)

Parameters

Example Usage

    var body = new SendMMSRequest({"key":"value"});

    controller.createSendMMS(body, 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