WARNING: This is NOT the official Unifonic SDK, at the time of this writing, Unifonic's suggested method is that a user should download the SDK from their website and extract it in their repository which makes it difficult for people to find whether there is a new version of this package that can potentially includea security fix.

I'll publish this as a package, I'll try to keep the dependencies up-to-date until Unifonic publish their own official package.

Getting started

Introduction

Send SMS messages using Unifonic Messaging API. Get your dedicated Universal number, and start sending messages today.

Unifonic NextGen Restful and HTTP API's uses The basic Authentication protocol. All request and response bodies are formatted in JSON.

Get an account

To start using the API you need to send an email to Unifonic to create Appsid for you.

Base URL

All URLs referenced in the documentation have the following base:

basic.unifonic.com

Security

To ensure privacy we recommend you to use HTTPS for all Unifonic API requests. you can download our HTTPS certificate.

[Download] (https://api.unifonic.com/udm/https.zip)

Formats

Unifonic API only supports JSON format. All request must use the Content-type header set to application/json.

Support

We’re here to help! Get in touch with support at [email protected] and we’ll get back to you as soon as we can or you can contact us throw live chat on our [website] (www.unifonic.com).

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 UnifonicNextGenLib 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 Unifonic NextGenController 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 | |-----------|-------------| | basicAuthUserName | The username to use with basic authentication | | basicAuthPassword | The password to use with basic authentication |

API client can be initialized as following:

const lib = require('lib');

// Configuration parameters and credentials
lib.Configuration.basicAuthUserName = "basicAuthUserName"; // The username to use with basic authentication
lib.Configuration.basicAuthPassword = "basicAuthPassword"; // The password to use with basic authentication

Class Reference

List of Controllers

• WrapperController
• RestController

WrapperController

Get singleton instance

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

var controller = lib.WrapperController;

createGetMsgQuery

Unifonic Get message query API allows you to get details of specified message.

function createGetMsgQuery(appsid, msgid, to, callback)

Parameters

| Parameter | Tags | Description | |-----------|------|-------------| | appsid | Required | A character string that uniquely identifies your app | | msgid | Required | A unique ID that identifies a message | | to | Optional | Destination mobile number, mobile numbers must be in international format without 00 or + Example: (4452023498) |

Example Usage

    var appsid = '6v253153s1g7831s5';
    var msgid = 3200017891630;
    var to = 966505980169;

    controller.createGetMsgQuery(appsid, msgid, to, function(error, response, context) {

    
    });

Errors

| Error Code | Error Description | |------------|-------------------| | 401 | Authentication failed | | 402 | Missing parameter AppSid | | 432 | MessageId must be numeric | | 452 | User must specify either messageId or recipient parameter |

createSendMessage

Unifonic Send Wrapper API allows you to send text messages to multiple users at the same time

function createSendMessage(appsid, msg, to, sender, baseEncode, encoding, callback)

Parameters

| Parameter | Tags | Description | |-----------|------|-------------| | appsid | Required | A character string that uniquely identifies your app | | msg | Required | Message body supports both English and unicodes characters, concatenated messages is supported | | to | Required | Destination mobile number, mobile numbers must be in international format without 00 or + Example: (4452023498) | | sender | Required | The SenderID to send from, App default SenderID is used unless else stated | | baseEncode | Optional DefaultValue | Binary-to-text encoding schemes that represent binary data in an ASCII string format | | encoding | Optional DefaultValue | Converts information from a source into symbols for communication or storage, GSM7 for English and UCS2 for Arabic |

Example Usage

    var appsid = '6v253153s1g7831s5';
    var msg = 'Test';
    var to = 966505980169;
    var sender = 'sender';
    var baseEncode = true;
    var encoding = 'encoding';

    controller.createSendMessage(appsid, msg, to, sender, baseEncode, encoding, function(error, response, context) {

    
    });

Errors

| Error Code | Error Description | |------------|-------------------| | 401 | Authentication failed | | 402 | Missing parameter AppSid | | 459 | Authentication parameters are incorrectly base64 encoded |

Back to List of Controllers

RestController

Get singleton instance

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

var controller = lib.RestController;

createSendScheduledMessages

Unifonic Send Scheduled API allows you to schedule text messages to users around the globe through simple RESTful API to be sent in future.

function createSendScheduledMessages(appSid, senderID, recipient, body, timeScheduled, responseType, correlationID, baseEncode, callback)

Parameters

| Parameter | Tags | Description | |-----------|------|-------------| | appSid | Required | A character string that uniquely identifies your app | | senderID | Required | The SenderID to send from, App default SenderID is used unless else stated | | recipient | Required | Destination mobile number, mobile numbers must be in international format without 00 or + Example: (4452023498) | | body | Required | Message body supports both English and unicodes characters, concatenated messages is supported | | timeScheduled | Required | Schedule send messages, in the following format yyyy-mm-dd HH:mm:ss | | responseType | Optional | Support json format only | | correlationID | Optional | Is a unique identifier value that is attached to requests and messages | | baseEncode | Optional | Binary-to-text encoding schemes that represent binary data in an ASCII string format |

Example Usage

    var appSid = '6v253153s1g7831s5';
    var senderID = 'sender';
    var recipient = 966505980169;
    var body = 'Test';
    var timeScheduled = "2020-04-12 11:50:00";
    var responseType = 'responseType';
    var correlationID = 'CorrelationID';
    var baseEncode = true;

    controller.createSendScheduledMessages(appSid, senderID, recipient, body, timeScheduled, responseType, correlationID, baseEncode, function(error, response, context) {

    
    });

Errors

| Error Code | Error Description | |------------|-------------------| | 401 | Authentication failed | | 406 | Wrong parameter format | | 449 | Message body is empty | | 451 | TimeScheduled parameter must indicate time in the future | | 480 | This user cannot use specified SenderID | | 482 | Invalid dest num |

createSendMessage

Unifonic Send API allows you to send text messages to users around the globe through simple RESTful APIs

function createSendMessage(appSid, senderID, body, recipient, responseType, correlationID, baseEncode, statusCallback, async, callback)

Parameters

| Parameter | Tags | Description | |-----------|------|-------------| | appSid | Required | A character string that uniquely identifies your app | | senderID | Required | The SenderID to send from, App default SenderID is used unless else stated | | body | Required | Message body supports both English and unicodes characters, concatenated messages is supported | | recipient | Required | Destination mobile number, mobile numbers must be in international format without 00 or + Example: (4452023498) | | responseType | Optional | Support json format only | | correlationID | Optional | Is a unique identifier value that is attached to requests and messages | | baseEncode | Optional | Binary-to-text encoding schemes that represent binary data in an ASCII string format | | statusCallback | Optional | Filter messages report according to a specific message status, "Sent", "Queued", "Rejected" or "Failed | | async | Optional DefaultValue | It specifies that the request will be executed asynchronously as soon as it is sent |

Example Usage

    var appSid = '6v253153s1g7831s5';
    var senderID = 'sender';
    var body = 'Test';
    var recipient = 966505980169;
    var responseType = 'responseType';
    var correlationID = 'CorrelationID';
    var baseEncode = true;
    var statusCallback = 'statusCallback';
    var async = true;

    controller.createSendMessage(appSid, senderID, body, recipient, responseType, correlationID, baseEncode, statusCallback, async, function(error, response, context) {

    
    });

Errors

| Error Code | Error Description | |------------|-------------------| | 401 | Authentication failed | | 449 | Message body is empty | | 480 | This user cannot use specified SenderID | | 482 | Invalid dest num |

getScheduledMessageDetails

Unifonic Scheduled message details allows you to get details of scheduled messages through simple RESTful APIs

function getScheduledMessageDetails(appSid, callback)

Parameters

| Parameter | Tags | Description | |-----------|------|-------------| | appSid | Required | A character string that uniquely identifies your app |

Example Usage

    var appSid = '6v253153s1g7831s5';

    controller.getScheduledMessageDetails(appSid, function(error, response, context) {

    
    });

Errors

| Error Code | Error Description | |------------|-------------------| | 401 | Authentication failed |

deleteStopScheduledMessages

Unifonic Stop scheduled messages API allows you to Delete (Stops) scheduled message,If MessageID is specified only one message is stopped, Otherwise all messages are stopped through simple RESTful APIs.

function deleteStopScheduledMessages(appSid, messageID, responseFormat, baseEncode, callback)

Parameters

| Parameter | Tags | Description | |-----------|------|-------------| | appSid | Required | A character string that uniquely identifies your app | | messageID | Optional | A unique ID that identifies a message | | responseFormat | Optional | support json format only | | baseEncode | Optional | Binary-to-text encoding schemes that represent binary data in an ASCII string format |

Example Usage

    var appSid = '6v253153s1g7831s5';
    var messageID = 3200017889502;
    var responseFormat = '';
    var baseEncode = true;

    controller.deleteStopScheduledMessages(appSid, messageID, responseFormat, baseEncode, function(error, response, context) {

    
    });

Errors

| Error Code | Error Description | |------------|-------------------| | 401 | Authentication failed | | 455 | Scheduled message not found for this User |

createGetMessageDetails

Unifonic Get message details API allows you to get details of messages with optional filters,returns paginated messages, next page or previous page through simple RESTful APIs

function createGetMessageDetails(appSid, messageID, senderID, recipient, dateFrom, dateTo, correlationID, limit, baseEncode, callback)

Parameters

| Parameter | Tags | Description | |-----------|------|-------------| | appSid | Required | A character string that uniquely identifies your app | | messageID | Optional | A unique ID that identifies a message | | senderID | Optional | The SenderID to send from, App default SenderID is used unless else stated | | recipient | Optional | Destination mobile number, mobile numbers must be in international format without 00 or + Example: (4452023498) | | dateFrom | Optional | The start date for the report time interval, date format should be yyyy-mm-dd | | dateTo | Optional | The end date for the report time interval, date format should be yyyy-mm-dd | | correlationID | Optional | Is a unique identifier value that is attached to requests and messages | | limit | Optional | The maximum number of messages details | | baseEncode | Optional | Binary-to-text encoding schemes that represent binary data in an ASCII string format |

Example Usage

    var appSid = '6v253153s1g7831s5';
    var messageID = 2000000172800;
    var senderID = 'sender';
    var recipient = 966505980169;
    var dateFrom = "2018-04-12";
    var dateTo = "2018-09-12";
    var correlationID = 'CorrelationID';
    var limit = 20;
    var baseEncode = true;

    controller.createGetMessageDetails(appSid, messageID, senderID, recipient, dateFrom, dateTo, correlationID, limit, baseEncode, function(error, response, context) {

    
    });

Errors

| Error Code | Error Description | |------------|-------------------| | 401 | Authentication failed | | 432 | MessageId must be numeric | | 599 | Request failed |

Back to List of Controllers