NodeJs Client library for Bandwidth Numbers API
- Messaging: https://github.com/Bandwidth/node-messaging
- Voice: https://github.com/Bandwidth/node-voice
This SDK stable for node versions 7 and above
| Version | Support Level | |
|---|---|---|
| <7 | Unsupported | |
| > 7 | Supported |
| Version | Notes |
|---|---|
| 1.1.0 | Added import tn functionality, added promise based Async functions |
| 1.2.0 | Added CSR lookup functionality |
| 1.2.1 | Fixed Subscription List functionality. Example code at: examples/subscription_list_and_delete |
| 1.2.2 | Readme Typo for RemoveImportedTnOrder |
| 1.3.0 | Added Emergency Calling Notification endpoints |
| 1.4.0 | Added TnOptions endpoints and functionality, along with SMS options on sip peers. |
| 1.6.0 | Added create origination settings for sip peers |
| 1.7.0 | Added get products to account |
| 1.7.1 | Fix TnOptions.create() callback bug |
Run
npm install @bandwidth/numbers varnumbers=require("@bandwidth/numbers");//Using client directlyvarclient=newnumbers.Client("accountId","userName","password");numbers.Site.list(client,function(err,sites){...});//Or you can use default client instance (do this only once)numbers.Client.globalOptions.accountId="accountId";numbers.Client.globalOptions.userName="userName";numbers.Client.globalOptions.password="password";//Now you can call any functions without first arg 'client'numbers.Site.list(function(err,sites){//Default client will be used to do this call});Each API Call also contains an async method that returns a promise for use with .then or async/await.
The async method is the original method name with Async added.
numbers.Site.create:numbers.Site.createAsyncnumbers.AvailableNumbers.list:numbers.AvailableNumbers.listAsyncnumbers.Order.create:numbers.Order.createAsync
// Callbacksnumbers.AvailableNumbers.list(query,(err,availableNumbers)=>{if(err){console.log(err);}else{console.log(availableNumbers);}});//Promise chainingnumbers.AvailableNumbers.listAsync(query).then(availableNumbers=>{console.log(availableNumbers);}).catch(e=>{console.log(e);});//Async/awaittry{constavailableNumbers=awaitnumbers.AvailableNumbers.listAsync(query);console.log(availableNumbers);}catch(e){console.log(e)}There is an 'examples' folder in the source tree that shows how each of the API objects work with simple example code. To run the examples:
$ cd examples $ cp config.js.example config.jsEdit the config.js to match your IRIS credentials and run the examples individually. e.g.
node coveredRateCenters-sample.jsIf the examples take command line parameters, you will get the usage by just executing the individual script.
When fetching objects from the API, it will always return an object that has the client instantiated so that you can call dependent methods as well as update, delete.
Example:
numbers.Site.create({siteObject},function(err,item){console.log("the site ID is: "+item.id);item.delete(function(err,res){//no need to pass the client again});});Each entity has a get, list, create, update and delete method if appropriate.
All properties are camel-cased for Javascript readability, and are converted on the fly to the proper case by the internals of the API when converted to XML.
varorders=numbers.Account.getMoveTnsOrders(function(err,res){if(err){console.log(err)};console.log(res);});numbers=["19195551234","19195554321"]data={CustomerOrderId: "abc123",SiteId: "12345",// DESTINATION sub-account (site)SipPeerId: "54321"// DESTINATION location (sip-peer) (optional - if not inclided, tn(s) will provision to default sip-peer)}data.telephoneNumbers=[numbers.map(number=>{return{telephoneNumber: number}})];numbers.account.moveTns(client,data,callback);numbers.account.getMoveTnsOrder(client,'my-order-id-12345',callback);numbers.account.getMoveTnsOrderHistory(client,'my-order-id-12345',callback);vardata={appName:"test app",callInitiatedCallbackUrl: "http://example.com",callInitiatedMethod: "POST",callStatusCallbackUrl: "http://example.com",callStatusMethod: "POST"callbackCreds: {userId: 'my-id',password: 'my-password'}};numbers.Application.createVoiceApplication(data,callback);vardata={appName:"test app",msgCallbackUrl: "http://example.com",callbackCreds: {userId: 'my-id',password: 'my-password'}};numbers.Application.createMessagingApplication(data,callback);numbers.Application.list(callback);numbers.Application.get(id,callback);numbers.Application.get(id,(err,app)=>{app.appName="new name";app.update(app,callback);});numbers.Application.get(id,(err,app)=>{app.delete(callback)});numbers.Application.get(id,(err,app)=>{app.getSipPeers(callback);});varres=awaitnumbers.AvailableNumbers.listAsync({areaCode:"919",quantity:"5"});console.log(res);varres=awaitnumbers.AvailableNumbers.listAsync({areaCode:"919",localVanity:"298",quantity:"5"});console.log(res);res=awaitnumbers.AvailableNumbers.listAsync({areaCode:"919",localVanity:"2982",quantity:"5"});console.log(res);res=awaitnumbers.AvailableNumbers.listAsync({areaCode:"919",localVanity:"29822",quantity:"5"});console.log(res);res=awaitnumbers.AvailableNumbers.listAsync({areaCode:"919",localVanity:"298227",quantity:"5"});console.log(res);res=awaitnumbers.AvailableNumbers.listAsync({areaCode:"919",localVanity:"2982272",quantity:"5"});console.log(res);numbers.AvailableNpaNxx.list({areaCode:"818",quantity:5},callback);numbers.City.list({"available":true,"state":"CA"},callback);numbers.CoveredRateCenter.list({"zip":"27601"},callback);Retrieves a list of disconnected numbers for an account
numbers.DiscNumber.list({"areaCode":"919"},callback);The Disconnect object is used to disconnect numbers from an account. Creates a disconnect order that can be tracked
numbers.Disconnect.create("Disconnect Order Name",["9195551212","9195551213"],callback);numbers.Disconnect.get("orderId",{tnDetail:true},callback);varnote={userId: "my id",description: "Test"};numbers.Disconnect.get("orderId",{tnDetail:true},function(err,order){order.addNote(note,callback);});numbers.Disconnect.get("orderId",{tnDetail:true},function(err,order){order.getNotes(callback);});vardlda={customerOrderId:"Your Order Id",dldaTnGroups: [dldaTnGroup: {telephoneNumbers: ["9195551212"],subscriberType: "RESIDENTIAL",listingType: "LISTED",listingName:{firstName:"John",lastName:"Smith"},listAddress:true,address:{houseNumber: "123",streetName: "Elm",streetSuffix: "Ave",city: "Carpinteria",stateCode:"CA",zip:"93013",addressType: "DLDA"}}]}numbers.Dlda.create(dlda,callback);numbers.Dlda.get(id,callback);numbers.Dlda.get(id,function(err,dlda){dlda.getHistory(callback);});numbers.Dlda.list({telephoneNumber:"9195551212"},callback);This path is generally not available to Bandwidth accounts, and as such is not documented in this API
numbers.InServiceNumber.list({"areaCode":"919"},callback);numbers.InServiceNumber.get("9195551212",callback);vardata={customerOrderId:"A test order",lidbTnGroups:{lidbTnGroup:{telephoneNumbers:["8048030097","8045030098"],subscriberInformation:"Joes Grarage",useType: "RESIDENTIAL",visibility: "PUBLIC"}}}numbers.Lidbs.create(data,callback);numbers.Lidbs.get(id,callback);numbers.Lidbs.list({telephoneNumber:"9195551212"},callback);varnumbersList=["9195551212","9195551213"];varfullCheck=true;numbers.LnpChecker.check(numbersList,fullCheck,callback);vardata={pon:"Some Pon",customerOrderId: "MyId5",sPID:"123C",billingTelephoneNumber:"9192381468",requestedFocDate: "2015-11-15",authorizingPerson: "Jim Hopkins",subscriber:{subscriberType:"BUSINESS",businessName:"BusinessName",serviceAddress: {houseNumber:"11",streetName: "Park",streetSuffix: "Ave",city:"New York",stateCode: "NY",zip: "90025"},accountNumber:"123463",pinNumber:"1231"},listOfTelephoneNumbers: {telephoneNumber:["9192381848","9192381467"]}};numbers.LsrOrder.create(data,callback);numbers.LsrOrder.get(id,callback);numbers.LsrOrder.list({pon:"Some Pon"},callback);numbers.LsrOrder.get("id",function(err,order){order.requestedFocDate="2015-11-16";numbers.LsrOrder.update(order,callback);})numbers.LsrOrder.get("id",function(err,order){order.getHistory(callback);});numbers.LsrOrder.get("id",function(err,order){order.getNotes(callback);});varnote={userId: "my id",description: "Test"};numbers.LsrOrder.get("id",function(err,order){order.addNote(note,callback);});varorder={name:"A Test Order",siteId: 1111,existingTelephoneNumberOrderType: {telephoneNumberList:[{telephoneNumber:"9195551212"}]}};numbers.Order.create(order,callback);numbers.Order.get(id,callback);numbers.Order.list(query,callback);numbers.Order.get(id,function(err,order){order.getAreaCodes(callback);});// get Area Codesorder.getAreaCodes(callback);// add note to ordervarnote={userId: "my id",description: "Test"};order.addNote(note,callback);//get Npa Nxxsorder.getNpaNxx(callback);// get number totalsorder.getTotals(callback);// get all Tns for an orderorder.getTns(callback)// get order historyorder.getHistory(callback);// get order notesorder.getNotes(callback);vardata={siteId:1234,peerId:5678,billingTelephoneNumber: "9195551212",subscriber: {subscriberType: "BUSINESS",businessName: "Company",serviceAddress: {houseNumber: "123",streetName: "EZ Street",city: "Raleigh",stateCode: "NC",county: "Wake"}},loaAuthorizingPerson: "Joe Blow",listOfPhoneNumbers: {phoneNumber:["9195551212"]},billingType: "PORTIN"};numbers.PortIn.create(data,callback);numbers.PortIn.get("id",callback)varquery={pon:"a pon"};numbers.PortIn.list(query,function(err,list){console.log(JSON.stringify(list));});// fetch instance using PortIn.get(callback, portIn)portIn.update(data,callback);portIn.delete(callback);portIn.getAreaCodes(callback);portIn.getNpaNxx(callback);portIn.getTotals(callback);portIn.getTns(callback);portIn.getNotes(callback);portIn.addNote(callback);portIn.getActivationStatus(callback);numbers.PortIn.get("id",function(err,portIn){// Add FileportIn.createFile(fs.createReadStream("myFile.txt"),callback);// Update FileportIn.updateFile("myFile.txt",fs.createReadStream("myFile.txt"),callback);// Get FileportIn.getFile("myFile.txt",callback);// Get File MetadataportIn.getFileMetadata("myFile.txt",callback);// Get FilesportIn.getFiles(callback);});varquery={"status":"complete"}numbers.PortOut.list(query,callback);numbers.PortOut.get(id,callback);varquery={"available":true,"state":"CA"}numbers.RateCenter.list(query,callback);vardata={peerName:"A New SIP Peer",isDefaultPeer:false,shortMessagingProtocol:"SMPP",// `HTTP` for use with the v2 messaging APIsiteId:selectedSite,voiceHosts:[// optional{host:{hostName:"1.1.1.1"}}],smsHosts:[// optional{host:{hostName:"1.1.1.1"}}]};numbers.SipPeer.create(data,callback);numbers.SipPeer.get(siteId,sipPeerId,callback);numbers.SipPeer.list(siteId,callback);sipPeer.peerName="Some new name";sipPeer.update(sipPeer,callback);numbers.SipPeer.get(function(err,sipPeer){sipPeer.delete(callback);});numbers.SipPeer.get(function(err,sipPeer){// get TN for this peersipPeer.getTns(number,callback);// get all TNs for this peersipPeer.getTns(callback);// Update TNs for this peervartns={fullNumber: "123456",rewriteUser: "test"};sipPeer.updateTns(number,tns,callback);// Move Tns to new peervarnumbersToMove=["9195551212","9195551213"];sipPeer.moveTns(numbersToMove,callback);});numbers.SipPeer.get(function(err,sipPeer){// List application associated with this peersipPeer.listApplication(callback);// Associate an application with this peervarappId="my-application-id";sipPeer.editApplication({httpMessagingV2AppId: appId},callback);// Dissociate all applications with this peersipPeer.removeApplication(callback);numbers.SipPeer.get(function(err,sipPeer){// Get the sms settings associated with the peersipPeer.getSmsSettings(callback);vardesiredsettings={sipPeerSmsFeatureSettings: {tollFree: true,zone1: false,zone2: true,protocol: "HTTP"}};//Change settingssipPeer.editSmsSettings(desiredsettings,callback);//Create settingssipPeer.createSmsSettings(desiredsettings,callback);//DeletesipPeer.deleteSmsSettings(callback);numbers.SipPeer.get(function(err,sipPeer){// Get the mms settings associated with the peersipPeer.getMmsSettings(callback);vardesiredsettings={mmsSettings: {protocol: 'HTTP'},protocols: {HTTP: {httpSettings: {proxyPeerId: 500017}}}}//Change settingssipPeer.editMmsSettings(desiredsettings,callback);//Create settingssipPeer.createMmsSettings(desiredsettings,callback);//DeletesipPeer.deleteMmsSettings(callback);A site is what is called Sub-Account in the web UI.
varsite={name:"A new site",description:"A new description",address:{houseNumber: "123",streetName: "Anywhere St",city: "Raleigh",stateCode:"NC",zip: "27609",addressType: "Service"}};numbers.Site.create(site,callback);site.name="Some new name";site.update(site,callback);site.delete(callback);numbers.Site.list(callback);numbers.Site.get(id,function(err,site){// getInService numberssite.getInserviceNumbers(query,callback);// get Orderssite.getOrders(query,callback);// get PortInssite.getPortIns(query,callback);// get Total Tnssite.getTotalTns(query,callback);});numbers.Site.get(id,function(err,site){// get Sip Peerssite.getSipPeers(callback);// get Sip Peersite.getSipPeer(id,callback);// create Sip PeervarsipPeer={name:"SIP Peer"};site.createSipPeer(sipPeer,callback);});varsubscription={orderType:"orders",callbackSubscription: {URL:"http://mycallbackurl.com",user:"userid",expiry: 12000}};numbers.Subscription.create(subscription,callback);numbers.Subscription.get(id,callback);numbers.Subscription.list(query,callback);numbers.Subscription.get(id,function(err,subscription){// update subscriptionvarupdatedData={orderType:"portins"};subscription.update(updatedData,callback)// delete subscriptionsubscription.delete(callback);});numbers.Tn.get(fullNumber,callback);numbers.Tn.list(query,callback);numbers.Tn.get(fullNumber,function(err,tn){// Get TN Detailstn.getTnDetails(callback);// Get Sitestn.getSites(callback);// Get Sip Peerstn.getSipPeers(callback);// Get Rate Centertn.getRateCenter(callback)});numbers.TnReservation.create({"reservedTn":"9195551212"},callback);numbers.TnReservation.get(id,callback);numbers.TnReservation.get(id,function(err,tn){tn.delete(callback);});constquery={createdDateFrom : "2013-10-22T00:00:00.000Z",orderDetails: true,tn: 123456789}numbers.TnOption.list(client,query,(err,tnOptions)=>{if(err){console.error(err);}console.log(tnOptions);})consttnOptionOrderId='fakeOrderId';numbers.TnOption.get(tnOptionOrderId,(err,tnOption)=>{if(err){console.error(err);}console.log(tnOptions);})consttnOptionsOrder={customerOrderId: 'myOrderId',tnOptionGroups: [{portOutPasscode: 'mypass1',telephoneNumbers: ['1234567890']}]}numbers.TnOption.create(tnOptionsOrder,callback)//for callback example see TnOption.getconsttnOptionsOrder={customerOrderId: 'myOrderId',tnOptionGroups: [{callForward: '2345678901',telephoneNumbers: ['1234567890']}]}numbers.TnOption.create(tnOptionsOrder,callback)//for callback example see TnOption.getconsttnOptionsOrder={customerOrderId: 'myOrderId',tnOptionGroups: [{sms: 'on',telephoneNumbers: ['1234567890']}]}numbers.TnOption.create(tnOptionsOrder,callback)//for callback example see TnOption.getconstnumbers=["1111","2222"];try{constimportResults=awaitImportTnChecker.checkAsync(numbers);console.log(importResults);}catch(e){console.log(e)}constnumbers=["1111","2222"];constdata={customerOrderId: "1111",siteId: "222",sipPeerId: "333",loaAuthorizingPerson: "LoaAuthorizingPerson",subscriber: {name: "ABC Inc.",serviceAddress: {houseNumber: "11235",streetName: "StreetName",stateCode: "NC",city: "City",county: "county",zip: "27606"}}};try{constimportTnOrder=awaitImportTnOrder.createAsync(numbers);console.log(importTnOrder);}catch(e){console.log(e)}To restore the messaging functionality to the original owner, create a removeImportedTnOrder order to remove the numbers from your account.
constnumbers=["1111","2222"];constcustomerOrderId="customerOrderId"try{constimportTnOrder=awaitRemoveImportedTnOrder.createAsync(customerOrderId,numbers);console.log(importTnOrder);}catch(e){console.log(e)}constdata={customerOrderId: "MyId5",WorkingOrBillingTelephoneNumber:"9198675309",accountNumber:"123463",endUserPIN:"1231"};try{constcsrOrderResponse=awaitCsrOrder.createAsync(data);console.log(csrOrderResponse.orderId);//31e0b16b-4720-4f2e-bb99-1399eeb2ff9e}catch(e){console.log(e);}If the CSR order is in an FAILED state, the SDK will throw an error
constcsrOrderId="1234-abc"try{constcsrOrderData=awaitCsrOrder.getAsync(csrOrderId);console.log(csrOrderData.status);//COMPLETE}catch(e){console.log(e);}constcsrOrderId="1234-abc"try{constcsrOrderData=awaitCsrOrder.getAsync(csrOrderId);console.log(csrOrderData.status);//Won't fire, as request is failed}catch(e){console.log(e);// [BandwidthError: CSR is not available for this TN]{// code: 26500,// message: 'CSR is not available for this TN',// httpStatus: 200// }}try{constresponse=awaitEmergencyNotification.listRecipientsAsync(client,{"Size": "20"});console.log(response.emergencyNotificationRecipients.emergencyNotificationRecipient.length);//4}catch(e){console.log(e);}try{constresponse=awaitEmergencyNotification.getRecipientAsync(client,"enrid");console.log(response.emergencyNotificationRecipient.identifier);//63865500-0904-46b1-9b4f-7bd237a26363}catch(e){console.log(e);}varen=newEmergencyNotification();en.enrid=123;try{constresponse=awaiten.replaceRecipientAsync(client,recipient);console.log(response.emergencyNotificationRecipient.identifier);//63865500-0904-46b1-9b4f-7bd237a26363}catch(e){console.log(e);}try{constresponse=awaitEmergencyNotification.createRecipientAsync(client,recipient);console.log(response.emergencyNotificationRecipient.identifier);//63865500-0904-46b1-9b4f-7bd237a26363}catch(e){console.log(e);}varen=newEmergencyNotification();en.enrid=123;try{constresponse=awaiten.deleteRecipientAsync(client);}catch(e){console.log(e);}try{constresponse=awaitEmergencyNotification.listGroupOrdersAsync(helper.createClient(),{Size: "20"});console.log(response.emergencyNotificationGroupOrders.emergencyNotificationGroupOrder.length);//20}catch(e){console.log(e);}try{constresponse=awaitEmergencyNotification.getGroupOrderAsync(helper.createClient(),"orderId");console.log(response.emergencyNotificationGroup.orderId);//orderId}catch(e){console.log(e);}try{constresponse=EmergencyNotification.createGroupOrderAsync(helper.createClient(),groupOrder);console.log(response.OrderId);//900b3646-18df-4626-b237-3a8de648ebf6}catch(e){console.log(e);}try{constresponse=awaitEmergencyNotification.listGroupsAsync(client,{"Size": "20"});console.log(response.emergencyNotificationGroups.emergencyNotificationGroup.length);//20}catch(e){console.log(e);}try{constresponse=awaitEmergencyNotification.getGroupAsync(client,"engid");console.log(response.emergencyNotificationGroup.identifier);//63865500-0904-46b1-9b4f-7bd237a26363}catch(e){console.log(e);}try{constresponse=awaitEmergencyNotification.listEnpointOrdersAsync(client,{"Size": "20"});console.log(response.emergencyNotificationEndpointOrders.emergencyNotificationEndpointOrder.length);//20}catch(e){console.log(e);}try{constresponse=awaitEmergencyNotification.getEndpointOrderAsync(client,"orderId");console.log(response.emergencyNotificationEndpointOrder.orderId);//orderId}catch(e){console.log(e);}try{constresponse=awaitEmergencyNotification.createEndpointOrderAsync(client,endpoint);console.log(response.emergencyNotificationEndpointOrder.orderId);//3e9a852e-2d1d-4e2d-84c3-87223a78cb70}catch(e){console.log(e);}vardata=data={addressLine1: "900 Main Campus Dr",city: 'raleigh',stateCode: 'nc',zip: 27606}numbers.Geocode.request(data,function(error,address){if(error){returncallback(error)}console.log(address.stateCode,address.houseNumber,address.streetName,address.streetSuffix,address.city)//NC, 900, Main Campus, Dr, Raleigh});try{constresponse=awaitAeuis.listAsync(client,{Size: 20});console.log(response.AlternateEndUserIdentifiers.AlternateEndUserIdentifier.length);//20}catch(e){console.log(e);}try{constresponse=awaitAeuis.getAsync(client,"acid");console.log(response.AlternateEndUserIdentifier.Identifier);//acid}catch(e){console.log(e);}varsipPeer=<create/getsippeer>; var voiceHttpSettings = {httpVoiceV2AppId: "abcd-1234"} await sipPeer.createOriginationSettingsAsync({voiceProtocol: "HTTP",httpSettings: voiceHttpSettings})console.log(awaitnumbers.Account.getProductsAsync());