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.
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.
Install with NPM
npm install telstra-sms-messaging --save
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('telstra-sms-messaging/lib');
// Configuration parameters and credentials
lib.Configuration.oAuthClientId = "oAuthClientId"; // OAuth 2 Client ID
lib.Configuration.oAuthClientSecret = "oAuthClientSecret"; // OAuth 2 Client SecretYou must now authorize the 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 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 |
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.
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
});
});
}
});
The singleton instance of the MessagingController class can be accessed from the API Client.
var controller = lib.MessagingController;
Get Message Status
function getSMSStatus(messageId, callback)| Parameter | Tags | Description |
|---|---|---|
| messageId | Required |
Unique identifier of a message - it is the value returned from |
| a previous POST call to https://tapi.telstra.com/v2/messages/sms |
var messageId = 'messageId';
controller.getSMSStatus(messageId, function(error, response, context) {
});| 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 | |
| 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 |
Retrieve Messages
function retrieveSMSResponses(callback) controller.retrieveSMSResponses(function(error, response, context) {
});| 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 | |
| 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 |
Send Message
function createSendSMS(payload, callback)| 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 |
var payload = new SendSMSRequest({"key":"value"});
controller.createSendSMS(payload, function(error, response, context) {
});| 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 | |
| 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 |
Get MMS Status
function getMMSStatus(messageid, callback)| Parameter | Tags | Description |
|---|---|---|
| messageid | Required |
Unique identifier of a message - it is the value returned from a previous POST call to https://tapi.telstra.com/v2/messages/mms |
var messageid = 'messageid';
controller.getMMSStatus(messageid, function(error, response, context) {
});| 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 |
| 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 |
Send MMS
function createSendMMS(body, callback)| 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 |
var body = new SendMMSRequest({"key":"value"});
controller.createSendMMS(body, function(error, response, context) {
});| 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 |
| 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 |
The singleton instance of the OAuthAuthorizationController class can be accessed from the API Client.
var controller = lib.OAuthAuthorizationController;Tags:
Skips Authentication
Create a new OAuth 2 token.
function createRequestToken(authorization, scope, formParams, callback)| 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 |
var authorization = 'Authorization';
var scope = 'scope';
// key-value map for optional form parameters
var formParams = [];
controller.createRequestToken(authorization, scope, formParams, function(error, response, context) {
});| Error Code | Error Description |
|---|---|
| 400 | OAuth 2 provider returned an error. |
| 401 | OAuth 2 provider says client authentication failed. |
Tags:
Skips Authentication
Create a new OAuth 2 token.
function createRequestToken1(authorization, scope, formParams, callback)| 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 |
var authorization = 'Authorization';
var scope = 'scope';
// key-value map for optional form parameters
var formParams = [];
controller.createRequestToken1(authorization, scope, formParams, function(error, response, context) {
});| Error Code | Error Description |
|---|---|
| 400 | OAuth 2 provider returned an error. |
| 401 | OAuth 2 provider says client authentication failed. |