flowroutenumberslib v1.0.0

flowroute-numbers-nodejs

Flowroute-numbers-nodejs is a NodeJS SDK that provides methods for interacting with Flowroute's v1 API. These methods can be used to accomplish the following:

• Search for purchasable phone numbers
• Purchase phone numbers
• View your owned phone numbers and their related details
• Create new inbound routes
• Update the primary and failover route on a phone number

Documentation

The full documentation for v2 of the Flowroute API is available here.

##Before you begin

The following are required before you can deploy the SDK.

Have your API credentials

You will need your Flowroute API credentials (Access Key and Secret Key). These can be found on the Preferences > API Control page of the Flowroute portal. If you do not have API credentials, contact support@flowroute.com.

Get a code text editor

Steps in this SDK describe creating one or more script files that allow you to execute the methods. Script files can be created either using a terminal window shell or through using a code text editor. For example, Sublime Text.

###Download Node.js

The flowroute-messaging-nodejs SDK requires Node.js. The installation file can be downloaded here. Choose the installer that matches your operating system. Download the file, but do not install it.

##Install the libraries

Note: You must be connected to the Internet in order to install the required libraries.

1. Open a terminal session.

2. If needed, create a parent directory folder where you want to install the SDK.

3. Go to the newly created folder, and run the following:

   git clone https://github.com/flowroute/flowroute-messaging-nodejs.git

   The git clone command clones the flowroute-numbers-nodejs repository as a sub directory within the parent folder.

4. Change directories to the newly created flowroute-numbers-nodejs directory.

##Install Node.js

1. Install the downloaded Node.js file.

   After installing Node.js, a dependency is required for the request module.

2. To add the request module dependency, in a terminal window go to your flowroute-numbers-nodejs directory.

3. Run the following:

   npm install request

   The request module is installed.

   Important: Depending on your Node.js installation, as you execute methods you might run into errors indicating that modules are missing. To fix this issue, run the npm install line above with the name of each missing module.

4. After creating the libraries and installing Node.js, create a file that contains the flowroute-numbers-nodejs methods. This file can then be run from a command line.

Create a Node.js file to import the Controllers

Importing the SDK allows you to instantiate the Controllers, which contain the methods used to perform tasks with the SDK. In order to do this, create and run a Node.js file.

1. Using a code text editor create a new file.

2. Add the following lines at the top of the file to require the flowroutenumberslib and to process any method which returns information within an array:

   //Import the Numbers SDK var flowroute = require('./flowroutenumberslib'); var util = require('util');

   Important: The location where you save your Node.js file determines how the path to flowroutenumberslib should be declared.

   • If the Node.js file is saved in the same directory as the flowroutenumberslib directory, then declare the path as ./flowroutenumberslib.

   • If the file will be saved in a different directory, you must explicitly call the path to flowroutenumberslib. For example, /users/<user>/<directory path>/flowroute-numbers-nodejs/flowroutenumberslib/.

   This SDK assumes the Node.js file is in the same location as the flowroutenumberslib directory.

3. Add the following lines to set up up your API Access Key and Secret Key:

   //Set your API credentials
   flowroute.configuration.username = "Access Key";
   flowroute.configuration.password = "Secret Key";

4. Replace Access Key and Secret Key with your Flowroute credentials.

5. Add a callback function that returns both error and success messages:

   //Set up your callback function
   var cb =  function(err, response){
    if(err){
     console.log(err);
     }
     console.log(util.inspect(response, false, null));

   // console.log(response); };

   Note: The callback function name is a user-defined variable that can be any name of your own choosing, but whatever name you choose must be used consistently throughout the file. Throughout this SDK, cb is the variable named assigned to this function.

6. Save the file with a .js extension in. For example, sendmsg.js.

7. Add the Controllers and methods to the file.

8. After adding the MessageController methods, the file can be run from a terminal window as follows:

   node numbers.js

Example Node.js file

The following shows an example of a single Node.js file that imports and instantiates the Controller:

	//Import the Numbers SDK
	var flowroute = require('./flowroutenumberslib');
	
	//Set your API credentials
	flowroute.configuration.username = "1111111";
	flowroute.configuration.password = "m8axLA45yds7kmi2225OQ7BshaADg6vr";

	//Set up your callback function
	var cb =  function(err, response){
		if(err){
			console.log(err);
		}
		console.log(response);
	};

With this in mind, you can then decide the approach you want to take towards creating a file. You can create your own Node.js file using any of the following options:

1. Create a single file that contains all of the Controllers and methods, then commenting (#) out the lines for each Controller and method you don't want to run.

2. Create a unique file for each Controller, adding only those lines relevant to that Controller and related methods, and then commenting out the lines for each method you're not using. This procedure creates three unique Node.js files.

3. Create a unique file for each method. Each file will then contain the only the lines for the relevant Controller and method.

This SDK describes the second option, creating three Node.js files, one for each Controller. However, regardless of which option you select, the file(s) should be saved in the flowroute-numbers-nodejs directory. When you want to run a method, run the following on the command line in the flowroute-numbers-nodejs directory:

run <node.js file>

Controllers

This following sections describe flowroute-numbers-nodejs Controllers:

• PurchasablePhoneNumbersController

• TelephoneNumbersController

• InboundRoutesController

Important: The SDK displays sample responses. Formatting of the responses is provided for clarity only. They are not intended to show the formatting of your own response.

PurchasablePhoneNumbersController

Location: ./flowroute-numbers-nodejs/flowroutenumberslib/lib/Controllers

The Purchasable Phone Numbers Controller contains all of the methods necessary to search through Flowroute's phone number inventory. The following shows a sample file named purchase.nodejs file, which invokes only that Controller's methods:

/Import the Flowroute-numbers-nodejs SDK
var flowroute = require('./flowroutenumberslib/');
var util = require('util');

//Set your API credentials
flowroute.configuration.username = "1111111";
flowroute.configuration.password = "m8axLA45yds7kmi2225OQ7BshaADg6vr";

//Set up your callback function
var cb =  function(err, response){

if(err){ console.log(err); } console.log(util.inspect(response, false, null)); // console.log(response); };

//List NPAs
flowroute.PurchasablePhoneNumbersController.listAvailableNPAs(limit,callback)

//List Area and Exchange
flowroute.PurchasablePhoneNumbersController.listAreaAndExchange(null,null,null,cb);

//Search
flowroute.PurchasablePhoneNumbersController.search(limit:null, npa:null, nxx:null, page:null, ratecenter:"null", state:"null",tn:null,callback:callback);

Add any of the following methods after the end of the callback function you added to the file. If you do not want to execute a specific method, comment that method's lines out with //.

• listAvailableNPAs()

• [`listAreaAndExchange()`](#listnpanxx)

• [`search()`](#searchno)

listAvailableNPAs(limit, callback)

The listAvailableNPAs method allows you to retrieve a list of every NPA (area code) available in Flowroute's phone number inventory.

#####Usage

Add the following lines to the end of your Node.js file:

//List NPAs
flowroute.PurchasablePhoneNumbersController.listAvailableNPAs(limit,callback);

Example Usage

//List NPAs
flowroute.PurchasablePhoneNumbersController.listAvailableNPAs(3,cb)

#####Example response

Based on the request above, the following three NPAs are returned:

{ npas:

{ '201': { nxxs: '/v1/available-tns/npanxxs/?npa=201', tns: '/v1/available-tns/tns/?npa=201' }, '202': { nxxs: '/v1/available-tns/npanxxs/?npa=202', tns: '/v1/available-tns/tns/?npa=202' }, '203': { nxxs: '/v1/available-tns/npanxxs/?npa=203', tns: '/v1/available-tns/tns/?npa=203' } }, links: { next: '/v1/available-tns/npas/?limit=3&page=2' } } #####Error response

The following errors can be returned:

listAreaAndExchange(limit, npa, page, callback)

The listAreaAndExchange method allows you to retrieve a list of every NPANXX (area code and exchange) combination available in Flowroute's phone number inventory.

#####Usage

Add the following lines to the end of your Node.js file:

//List Area and Exchange
flowroute.PurchasablePhoneNumbersController.listAreaAndExchange(null,null,null,cb);

The method takes the following parameters:

Example Usage

In the following, a request is made to limit the results to 2, the NPA to 203, display page 3, and cb for the callback:

//List Area and Exchange
flowroute.PurchasablePhoneNumbersController.listAreaAndExchange(2,203,3,cb);

Example response

Based on the parameters passed above, 2 NPAs are returned for NXX 203, displayed on page 3:

	{ npanxxs:

{ '203648': { tns: '/v1/available-tns/tns/?npa=203&nxx=648' }, '203654': { tns: '/v1/available-tns/tns/?npa=203&nxx=654' } }, links: { prev: '/v1/available-tns/npanxxs/?npa=203&limit=2&page=2', next: '/v1/available-tns/npanxxs/?npa=203&limit=2&page=4' } }

Note: If no results are found for the passed parameters, {} is returned.

#####Error response

search(limit, npa, nxx, page, ratecenter, state, tn, callback)

The search method is the most robust option for searching through Flowroute's purchasable phone number inventory. It allows you to search by NPA, NXX, Ratecenter, State, and/or TN.

#####Usage

Add the following lines to the end of your Node.js file:

//Search
flowroute.PurchasablePhoneNumbersController.search(limit:null, npa:null, nxx:null, page:null, ratecenter:"null", state:"null",tn:null,callback:callback);

The method takes the following parameters:

Example Usage

In the following example, a search request sets the limit to 3, 206 for the npa, 641 for the nxx, 2 for the page, SEATTLE for the ratecenter, WA for the state, and null for the tn, and cb for the callback.

//Search
flowroute.PurchasablePhoneNumbersController.search(3,206,641,2,"SEATTLE","WA",null,cb);

#####Example response

Based on the parameters passed in the method above, the following results are returned:

{ tns:

{ '12066417727': { initial_cost: '1.00', monthly_cost: '1.25', billing_methods: Object, ratecenter: 'SEATTLE', state: 'WA' }, '12066417667': { initial_cost: '1.00', monthly_cost: '1.25', billing_methods: Object, ratecenter: 'SEATTLE', state: 'WA' }, '12066417669': { initial_cost: '1.00', monthly_cost: '1.25', billing_methods: Object, ratecenter: 'SEATTLE', state: 'WA' } }, links: { prev: '/v1/available-tns/tns/?npa=206&nxx=641&state=WA&ratecenter=SEATTLE&limit=3&page=1', next: '/v1/available-tns/tns/?npa=206&nxx=641&state=WA&ratecenter=SEATTLE&limit=3&page=3' } }

Note: If no results are found for the passed parameters, {} is returned.

#####Response field descriptions

The following information is returned in the response:

Error response

TelephoneNumbersController

Location: ./flowroute-numbers-nodejs/flowroutenumberslib/lib/Controllers

The Purchasable Phone Numbers Controller contains all of the methods necessary to search through Flowroute's phone number inventory. The following shows a sample file named purchase.nodejs file, which invokes only that Controller's methods:

/Import the Flowroute-numbers-nodejs SDK
var flowroute = require('./flowroutenumberslib/');
var util = require('util');

//Set your API credentials
flowroute.configuration.username = "1111111";
flowroute.configuration.password = "m8axLA45yds7kmi2225OQ7BshaADg6vr";

//Set up your callback function
var cb =  function(err, response){

if(err){ console.log(err); } console.log(util.inspect(response, false, null)); // console.log(response); };

//Purchase a Phone Number
var billingMethod = {"billing_method":"METERED"};
flowroute.TelephoneNumbersController.purchase(billingMethod,number,callback);)

//List Account Telephone Numbers
flowroute.TelephoneNumbersController.listAccountTelephoneNumbers(limit:null,page:null,pattern:null,callback);

//Telephone Number Details
flowroute.TelephoneNumbersController.telephoneNumberDetails("number", callback);

//Update Routes
var rtes = '[{"name":"primary route name"}, {"name":"failover route name"}]';
flowroute.TelephoneNumbersController.update("number", rtes, callback);

Add any of the following methods after the end of the callback function you added to the file. If you do not want to execute a specific method, comment that method's lines out with //.

• purchase
• listAccountTelephoneNumbers
• telephoneNumberDetails
• update

purchase(billing, number, callback)

The purchase method is used to purchase a telephone number from Flowroute's inventory.

#####Usage

Add the following lines to the end of your Node.js file:

//Purchase a Telephone Number
var billingMethod = {"billing_method":"METERED"};
flowroute.TelephoneNumbersController.purchase(billingMethod,number,callback);

First, define the variable name used in the method:

Next, set the variables that define the billingMethod.

Finally, define the Flowroute number to purchase and set the callback variable.

Example Usage

In the following method, the billing method is METERED, and the phone number is a number retrieved from the search method.

//Purchase a Telephone Number
var billingMethod = {"billing_method":"METERED"};
flowroute.TelephoneNumbersController.purchase(billingMethod, 12066417667,cb);

#####Example response

A successful purchase returns an empty string (''). No other success message is returned

#####Error response

listAccountTelephoneNumbers(limit, page, pattern, callback)

The listAccountTelephoneNumbers method is used to retrieve a list of all of the phone numbers on your Flowroute account.

#####Usage

Add the following lines to the end of your Node.js file:

//List Account Telephone Numbers
flowroute.TelephoneNumbersController.listAccountTelephoneNumbers(limit:null,page:null,pattern:null,callback);

The method takes the following parameters:

Example Usage

For this example, the limit is 3, the page is null, the pattern includes 206, and the callback is cb.

//List Account Telephone Numbers
flowroute.TelephoneNumbersController.listAccountTelephoneNumbers(3,null,206,cb);

#####Example response

Based on the passed parameters, the number purchased using the purchase method above is included within the response:

{ tns:

{ '12062092845': { billing_method: 'METERED', routes: { type: 'SIP-REG', name: 'sip-reg' }, { type: 'SIP-REG', name: 'sip-reg' } , detail: '/v1/tns/12062092844' }, '12066417667': { billing_method: 'METERED', { type: 'SIP-REG', name: 'sip-reg' }, { type: 'PSTN', name: 'PSTNroute1', value: '178 } ], detail: '/v1/tns/12066417667' } } }

Note: If no results are found for the passed parameters, {} is returned.

#####Response field descriptions

The following information is returned in the response:

#####Error response

telephoneNumberDetails(telephoneNumber, callback)

The telephone_number_details method is used to retrieve the billing method, primary route, and failover route for the specified telephone number.

#####Usage

Add the following lines to your Node.js file:

//Telephone Number Details
flowroute.TelephoneNumbersController.telephoneNumberDetails("number", callback);

The method takes the following parameters:

Example Usage

For the following example, details are requested on the telephone number purchased above using the purchase method:

//Telephone Number Details
flowroute.TelephoneNumbersController.telephoneNumberDetails("12066417667", cb);

#####Example response

The response returns the following phone number details:

{
  "billing_method": "METERED",

"routes": { "type": "SIP-REG", "name": "sip-reg" }, { "type": "SIP-REG", "name": "sip-reg" } }

#####Response field descriptions

The following information is returned in the response:

#####Error response

update(number, routes, callback)

The update method is used to update both the primary and failover route for a phone number, specified within an array. See Example Usage below. The first route name specified within the array is assigned as the primary route and the second route name assigned as the failover route. The list of available route names can be retrieved by using the the list method in the InboundRoutesController.

Note: In order to apply an existing route to a number, the route must first be created using the createNewRoute method. To view a list of your existing routes, use the list method.

#####Usage

Add the following lines to your Node.js file:

//Update Routes
var rtes = '[{"name":"primary route name"}, {"name":"failover route name"}]';
flowroute.TelephoneNumbersController.update("number", rtes, callback);

First, define the variable name that identifies the array:

Next, define the variables that compose the array:

Example usage

In the following example, the primary route is updated to use MyPSTN, while the failover route is updated to use MyHost2:

//Update Routes
var rtes = '[{"name":"MyPSTN"}, {"name":"MyHost2"}]';
flowroute.TelephoneNumbersController.update("12066417667", rtes, cb);

#####Example response

An empty string ('') is returned for a successful update. To view the route changes on the phone number, run the listAccountTelephoneNumbers() or telephoneNumberDetails() methods.

Error response

InboundRoutesController

Location: ./flowroute-numbers-nodejs/flowroutenumberslib/lib/Controllers

The InboundRoutesController contains all of the methods necessary to search through Flowroute's phone number inventory. The following shows a sample file named routes.nodejs file, which invokes that Controller's methods:

/Import the Flowroute-numbers-nodejs SDK
var flowroute = require('./flowroutenumberslib/');
var util = require('util');

//Set your API credentials
flowroute.configuration.username = "1111111";
flowroute.configuration.password = "m8axLA45yds7kmi2225OQ7BshaADg6vr";

//Set up your callback function
var cb =  function(err, response){

if(err){ console.log(err); } console.log(util.inspect(response, false, null)); // console.log(response); };

//List Routes
flowroute.InboundRoutesController.list(limit, page, callback);

//Create a New Route
flowroute.InboundRoutesController.createNewRoute("routeName", "type", "value", callback);

Add any of the following TelephoneNumbersController methods at the end of your Node.js file. If you do not want to execute a specific method, comment those lines out with //.

The Controller contains the following methods:

• list

• [`createNewRoute`](#createroute)

list (limit, page, callback)

The list method is used to return all of the existing inbound routes from your Flowroute account.

#####Usage

//List Routes
flowroute.InboundRoutesController.list(limit, page, callback);

The method takes the following parameters:

Example Usage

In the following example, a limit of 10 routes is to be returned, and only page 1 displayed:

//List Routes
flowroute.InboundRoutesController.list(10, 1, cb)

#####Example response

Based on the parameters passed in the method, the following results are returned:

{ routes:

{ MyNewURIroute: { type: 'URI', value: 'sip:18002364456@215.122.69.152:5060' }, MyHost2: { type: 'HOST', value: '24.239.24.45:5060' }, MyURI2: { type: 'URI', value: 'sip:112066417744@215.122.69.152:5060' }, 'sip-reg': { type: 'SIP-REG', value: null }, MyPSTN2: { type: 'PSTN', value: '18002364455' }, MyPSTN: { type: 'PSTN', value: '12065551212' }, MyNewPSTNroute: { type: 'PSTN', value: '18002364456' }, PSTNroute1: { type: 'PSTN', value: '178' }, URIroute1: { type: 'URI', value: 'sip:16476998778@215.122.69.152:5060' }, MyHost: { type: 'HOST', value: '24.239.23.45:5060' } }, links: { next: '/v1/routes/?limit=10&page=2' } }

#####Response field descriptions

The following information is returned in the response:

#####Error response

The following error can be returned:

createNewRoute (routeName, type, value, callback))

The createNewRoute method is used to create a new inbound route.

#####Usage //Create a New Route flowroute.InboundRoutesController.createNewRoute("routeName", "type", "value", callback);

The method takes the following parameters:

Example Usage

In the following example, three new routes are created:

//Create a New Route
flowroute.InboundRoutesController.createNewRoute("MyNewPSTNroute", "PSTN", "18002364456", cb);
flowroute.InboundRoutesController.createNewRoute("MyNewHOSTroute","HOST","24.239.23.40:5060", cb);
flowroute.InboundRoutesController.createNewRoute("MyNewURIroute","URI","sip: 18002364456@215.122.69.152:5060", cb);

#####Example response

An empty string, '', is returned for each newly created route. No other success message is returned.

#####Error response

The following error can be returned: