Ruby Client library for IRIS / BBS API
| Release Version | Notes |
|---|---|
| 1.0.5 | Fixed incorrect generation of XML for a Disconnect request |
| 2.0.0 | Added importTnOrders, removeImportedTnOrders, inserviceNumbers, and importTnChecker endpoints. This release also changed the response body of BandwidthIris::InServiceNumber.list(). Please make sure to update your code to include this change. |
| 2.0.1 | Updated gem dependencies to be less restrictive |
| 2.1.0 | Added csrs endpoints |
| 2.2.0 | Added loas endpoints to importTnOrders |
| 2.2.0 | Added loas endpoints to importTnOrders |
| 2.3.0 | Added get_tns_by_order_id to the Orders class |
| 2.4.0.pre | Added application management and sippeer products endpoints |
| 2.5.0 | Added get_order_response to pull full <OrderResponse> object from API, added id back to order object on get requests. Fixed TN Reservation and updated tests to match reality |
| 2.6.0 | Added Emergency Calling Notification, Emergeny Notification Group, Emergency Notification Endpoint, and Alternate End User Identity methods |
| 2.7.0 | Added TNOptions endpoints |
| 3.0.0 | Removed functionality that causes an error to be raised when some type of error field is returned in the XML body response. This change reduces the situations that cause an error to be thrown to simply be 4XX and 5XX http responses. This change was made to improve communication when an error is found. Please update your code to handle this change. |
| 3.0.2 | Fixed an incorrect retrieval of DLDA objects |
| 4.0.0 | Removed certify gem. Users will now need to set their own SSL settings |
| 4.1.0 | Added support for SIP credentials. |
failed_import_tn_order="some_id"beginresponse=BandwidthIris::ImportTnOrders.get_import_tn_order(failed_import_tn_order)putsresponse[0]rescueBandwidthIris::Errors::GenericError=>eputseendMessaging route of External Third Party TNs is not configured.
{:customer_order_id=>"custom_id", :order_create_date=>Mon, 02 Mar 2020 20:56:48 +0000, :account_id=>123, :created_by_user=>"user", :order_id=>"0f2", :last_modified_date=>Mon, 02 Mar 2020 20:56:48 +0000, :site_id=>123, :subscriber=>{:name=>"Company INC", :service_address=>{:house_number=>123, :street_name=>"Street", :city=>"City", :state_code=>"XY", :zip=>12345, :county=>"County", :country=>"Country", :address_type=>"Service"}}, :loa_authorizing_person=>"Person", :telephone_numbers=>{:telephone_number=>"5554443333"}, :processing_status=>"FAILED", :errors=>{:error=>{:code=>19005, :description=>"Messaging route of External Third Party TNs is not configured.", :telephone_numbers=>{:telephone_number=>"5554443333"}}}, :sip_peer_id=>123}
Run
gem install ruby-bandwidth-iris
Run
bundle install
rake spec
to run the tests
require'ruby-bandwidth-iris'# Using directlyclient=BandwidthIris::Client.new('accountId','userName','password')# Basic Authclient=BandwidthIris::Client.new({access_token: 'accessToken'})# Bearer Token Authclient=BandwidthIris::Client.new({client_id: 'clientId',client_secret: 'clientSecret'})# OAuth 2 using Client Credentialssites=BandwidthIris::Site.list(client)# Or you can use default client instance (do this only once)BandwidthIris::Client.global_options={:account_id=>'accountId',:username=>'userName',:password=>'password',:access_token=>'accessToken',:access_token_expiration=>Time.now + 3600
:client_id=> 'client_id',:client_secret=>'client_secret'}# Now you can call any functions without first arg 'client'sites=BandwidthIris::Site.list()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.yml.example config.ymlEdit the config.yml to match your IRIS credentials and run the examples individually. e.g.
ruby covered_rate_centers.rbIf 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:
site=BandwidthIris::Site.create({siteObject})# orsite=BandwidthIris::Site.create(client,{siteObject})Each entity has a get, list, create, update and delete method if appropriate.
All properties are underscored and low-cased for Ruby readability, and are converted on the fly to the proper case by the internals of the API when converted to XML.
list=BandwidthIris::AvailableNumber.list(query)list=BandwidthIris::AvailableNpaNxx.list({:area_code=>"818",:quantity=>5})list=BandwidthIris::City.list({:available=>true,:state=>"CA"})BandwidthIris::CoveredRateCenter.list({:zip=>"27601"})Retrieves a list of disconnected numbers for an account
BandwidthIris::DiscNumber.list({:area_code=>"919"})The Disconnect object is used to disconnect numbers from an account. Creates a disconnect order that can be tracked
order=BandwidthIris::Disconnect.create("Disconnect Order Name",["9195551212","9195551213"])order.add_note({:user_id=>"my id",:description=>"Test"})order.get_notes()dlda_data={:customer_order_id=>"Your Order Id",:dlda_tn_groups=>[:dlda_tn_group=>{:telephone_numbers=>["9195551212"],:subscriber_type=>"RESIDENTIAL",:listing_type=>"LISTED",:listing_name=>{:first_name=>"John",:last_name=>"Smith"},:list_address=>true,:address=>{:house_number=>"123",:street_name=>"Elm",:street_suffix=>"Ave",:city=>"Carpinteria",:state_code=>"CA",:zip=>"93013",:address_type=>"DLDA"}}]}BandwidthIris::Dlda.create(dlda_data)dlda=Bandwidth::Dlda.get("dlda_id")dlda.get_history()BandwidthIris::Dlda.list({:telephone_number=>"9195551212"})This path is generally not available to Bandwidth accounts, and as such is not documented in this API
BandwidthIris::InServiceNumber.list({:area_code=>"919"})BandwidthIris::InServiceNumber.get("9195551212")data={:customer_order_id=>"A test order",:lidb_tn_groups=>{:lidb_tn_group=>{:telephone_numbers=>["8048030097","8045030098"],:subscriber_information=>"Joes Grarage",:use_type=>"RESIDENTIAL",:visibility=>"PUBLIC"}}}BandwidthIris::Lidb.create(data)BandwidthIris::Lidb.get("lidb_id")BandwidthIris::Lidb.list({:telephone_number=>"9195551212"})numbers=["9195551212","9195551213"]full_check=trueBandwidthIris::LnpChecker.check(numbers,full_check)data={:pon=>"Some Pon",:customer_order_id=>"MyId5",'sPID'=>"123C",:billing_telephone_number=>"9192381468",:requested_foc_date=>"2015-11-15",:authorizing_person=>"Jim Hopkins",:subscriber=>{:subscriber_type=>"BUSINESS",:business_name=>"BusinessName",:service_address=>{:house_number=>"11",:street_name=>"Park",:street_suffix=>"Ave",:city=>"New York",:state_code=>"NY",:zip=>"90025"},:account_number=>"123463",:pin_number=>"1231"},:list_of_telephone_numbers=>{:telephone_number=>["9192381848","9192381467"]}}BandwidthIris::LsrOrder.create(data)BandwidthIris::LsrOrder.get("lsr_order_response_id")BandwidthIris::LsrOrder.list({:pon=>"Some Pon"})order.requestedFocDate="2015-11-16"BandwidthIris::LsrOrder.update(order)order.get_history()order.get_notes()note={:user_id=>"my id",:description=>"Test"}order.add_note(note)order_data={:name=>"A Test Order",:site_id=>1111,:existing_telephone_number_order_type=>{:telephone_number_list=>{:telephone_number=>["9195551212"]}}}BandwidthIris::Order.create(order_data)order=BandwidthIris::Order.get("order_id")The order response object contains more details returned in the GET/orders/order-id API.
order=BandwidthIris::Order.get_order_response(client,"101")completed_number=order.completed_numbers[:telephone_number][:full_number]BandwidthIris::Order.list(query)//getAreaCodesorder.get_area_codes()//addnotetoordernote={:user_id=>"my id",:description=>"Test"}order.add_note(note)//getNpaNxxsorder.get_npa_nxx()//getnumbertotalsorder.get_totals()//getallTnsforanorderorder.get_tns()##Use the below method to grab TNs via an already existing Order ID##BandwidthIris::Order.get_tns_by_order_id("id")
// get order historyorder.get_history()// getordernotesorder.get_notes()page=BandwidthIris::PortIn.list(client,{'page': 1,'size': 5})data={:site_id=>1234,:peer_id=>5678,:billing_telephone_number=>"9195551212",:subscriber=>{:subscriber_type=>"BUSINESS",:business_name=>"Company",:service_address=>{:house_number=>"123",:street_name=>"EZ Street",:city=>"Raleigh",:state_code=>"NC",:county=>"Wake"}},:loa_authorizing_person=>"Joe Blow",:list_of_phone_numbers=>{:phone_number=>["9195551212"]},:billing_type=>"PORTIN"}portin_response=BandwidthIris::PortIn.create(data)portIn=BandwidthIris::PortIn.get("portin_id",callback)portIn.update(data)portIn.delete()# Add FileportIn.create_file(IO.read("myFile.txt"))# Update FileportIn.update_file("myFile.txt",IO.read("myFile.txt"))# Get FileportIn.get_file("myFile.txt")# Get File MetadataportIn.get_file_metadata("myFile.txt")# Get FilesportIn.get_files()query={:status=>"complete"}list=BandwidthIris::PortOut.list(query)portout=BandwidthIris::PortOut.get("portout_id")query={:available=>true,:state=>"CA"}BandwidthIris::RateCenter.list(query)A Sip Peer is what is called Location in the web UI.
data={:peer_name=>"A New SIP Peer",:is_default_peer=>false,:short_messaging_protocol=>"SMPP",:site_id=>selectedSite,:voice_hosts=>{:host=>[{:host_name=>"1.1.1.1"}]},:sms_hosts=>{:host=>[{:host_name=>"1.1.1.1"}]},:termination_hosts=>{:termination_host=>[{:host_name=>"1.1.1.1",:port=>5060}]}}BandwidthIris::SipPeer.create(data)sipPeer=BandwidthIris::SipPeer.get("sippeer_id")BandwidthIris::SipPeer.list(sipPeer.siteId)sipPeer.delete()#peer_idsipPeer.peer_id#peer_namesipPeer.peer_name#is_default_peersipPeer.is_default_peer#productssipPeer.products#ss_send_to_customersipPeer.ss_send_to_customer#site_idsipPeer.site_id# get TN for this peersipPeer.get_tns(number)# get all TNs for this peersipPeer.get_tns()# Update TNs for this peertns={:full_number=>"123456",:rewrite_user=>"test"}sipPeer.update_tns(number,tns)# Move Tns to new peernumbers_to_move=["9195551212","9195551213"]sipPeer.move_tns(numbers_to_move)A site is what is called Sub-Account in the web UI.
site={:name=>"A new site",:description=>"A new description",:address=>{:house_number=>"123",:street_name=>"Anywhere St",:city=>"Raleigh",:state_code=>"NC",:zip=>"27609",:address_type=>"Service"}};site=BandwidthIris::Site.create(site)site=BandwidthIris::Site.get("site_id")site.update({:name=>"New name"})site.delete()BandwidthIris::Site.list()# get Sip Peerssite.get_sip_peers()# get Sip Peersite.get_sip_peer("sip_peer_id")# create Sip Peersip_peer={:name=>"SIP Peer"}site.create_sip_peer(sipPeer)subscription={:order_type=>"orders",:callback_subscription=>{:URL=>"http://mycallbackurl.com",:user=>"userid",:expiry=>12000}}BandwidthIris::Subscription.create(subscription)BandwidthIris::Subscription.get("subscription_id")BandwidthIris::Subscription.list(query)# update subscriptionupdatedData={:order_type=>"portins"}subscription.update(updatedData)# delete subscriptionsubscription.delete()});tn=BandwidthIris::Tn.get("9195555555")BandwidthIris::Tn.list(query)# Get TN Detailstn=tn.geti_tn_details()# Get Sitestn.get_sites()# Get Sip Peerstn.get_sip_peers()# Get Rate Centertn.get_rate_center()BandwidthIris::TnReservation.create("9195551212")tn=BandwidthIris::TnReservation.get("tn_reservation_id")tn.delete()import_tn_order={:customer_order_id=>"id",:site_id=>"12345",:sip_peer_id=>"23456",:subscriber=>{:service_address=>{:city=>"city",:house_number=>"1",:street_name=>"Street",:state_code=>"XY",:zip=>"54345",:county=>"County"},:name=>"Company INC"},:loa_authorizing_person=>"Test Person",:telephone_numbers=>{:telephone_number=>["5554443333"]}}response=BandwidthIris::ImportTnOrders.create_import_tn_order(import_tn_order)putsresponseresponse=BandwidthIris::ImportTnOrders.get_import_tn_orders({:createdDateFrom=>"2013-10-22T00:00:00.000Z",:createdDateTo=>"2013-10-25T00:00:00.000Z"})putsresponseresponse=BandwidthIris::ImportTnOrders.get_import_tn_order("id")putsresponseresponse=BandwidthIris::ImportTnOrders.get_import_tn_order_history("id")putsresponseresponse=BandwidthIris::ImportTnChecker.check_tns_portability({:telephone_numbers=>{:telephone_number=>["5554443333","5553334444"]}})putsresponseresponse=BandwidthIris::InServiceNumber.list()putsresponse[0]#{:total_count=>2, :links=>{:first=>"Link=<https://dashboard.bandwidth.com:443/v1.0/accounts/99/inserviceNumbers?page=1&size=500>;rel=\"first\";"}, :telephone_numbers=>{:count=>2, :telephone_number=>["5554443333", "5554442222"]}}response=BandwidthIris::RemoveImportedTnOrders.get_remove_imported_tn_orders({:createdDateFrom=>"2013-10-22T00:00:00.000Z",:createdDateTo=>"2013-10-25T00:00:00.000Z"})putsresponseresponse=BandwidthIris::RemoveImportedTnOrders.get_remove_imported_tn_order("order_id")putsresponseresponse=BandwidthIris::RemoveImportedTnOrders.get_remove_imported_tn_order_history("order_id")putsresponseremove_imported_tn_order={:customer_order_id=>"custom string",:telephone_numbers=>{:telephone_number=>["5554443333","5554442222"]}}response=BandwidthIris::RemoveImportedTnOrders.create_remove_imported_tn_order(remove_imported_tn_order)putsresponseresponse=BandwidthIris::ImportTnOrders.get_loa_files("order_id")putsresponse[0][:result_message]putsresponse[0][:file_names]#this can be a single string (if there's 1 file) or an array of strings (if there's multiple files)Valid mime_types can be found on the Dashboard API Reference under /accounts /{accountId} /importTnOrders /{orderid} /loas
Mime types are expected to be in the format x/y, such as application/pdf or text/plain
BandwidthIris::ImportTnOrders.upload_loa_file("order_id","binary_file_contents","mime_type")f=open("loa.pdf","rb")file_content=f.readf.close()BandwidthIris::ImportTnOrders.upload_loa_file("order_id",file_content,"application/pdf")Note: Make sure to grab the desired file ID from the response of BandwidthIris::ImportTnOrders.get_loa_files("order_id") in the field response[0][:file_names]
f=open("write.pdf","wb")response=BandwidthIris::ImportTnOrders.download_loa_file("order_id","file_id")f.puts(response)f.close()BandwidthIris::ImportTnOrders.replace_loa_file("order_id","file_id","binary_file_contents","mime_type")BandwidthIris::ImportTnOrders.delete_loa_file("order_id","file_id")response=BandwidthIris::ImportTnOrders.get_loa_file_metadata("order_id","file_id")putsresponse[0][:document_name]putsresponse[0][:file_name]metadata={:document_name=>"file_name",:document_type=>"LOA"}BandwidthIris::ImportTnOrders.update_loa_file_metadata("order_id","file_id",metadata)BandwidthIris::ImportTnOrders.delete_loa_file_metadata("order_id","file_id")csr_data={:customer_order_id=>"order id",:working_or_billing_telephone_number=>"5554443333"}response=BandwidthIris::Csr.create(csr_data)putsresponse[0][:order_id]csr_data={:customer_order_id=>"order id",:working_or_billing_telephone_number=>"5554443333"}response=BandwidthIris::Csr.replace("csr_id",csr_data)putsresponse[0][:order_id]response=BandwidthIris::Csr.get("csr_id")putsresponse[0][:order_id]response=BandwidthIris::Csr.get_notes("csr_id")putsresponse[0][:note][0][:id]note_data={:user_id=>"id",:description=>"description"}BandwidthIris::Csr.add_note("csr_id",note_data)note_data={:user_id=>"id",:description=>"description"}BandwidthIris::Csr.update_note("csr_id","note_id",note_data)data={:service_type=>"Messaging-V2",:app_name=>"Name",:msg_callback_url=>"https://test.com"}application=BandwidthIris::Applications.create_application(data)putsapplicationapplications=BandwidthIris::Applications.get_applications()putsapplications[0]application=BandwidthIris::Applications.get_application("id")putsapplicationdata={:app_name=>"Name2"}application=BandwidthIris::Applications.partial_update_application("id",data)putsapplicationdata={:service_type=>"Messaging-V2",:app_name=>"Name2",:msg_callback_url=>"https://test2.com"}application=BandwidthIris::Applications.complete_update_application("id",data)putsapplicationBandwidthIris::Applications.delete_application("id")sippeers=BandwidthIris::Applications.get_application_sippeers("id")putssippeers[0]putsBandwidthIris::SipPeerProducts.get_origination_settings("site_id","sippeer_id")data={:voice_protocol=>"HTTP"}putsBandwidthIris::SipPeerProducts.create_origination_settings("site_id","sippeer_id",data)data={:voice_protocol=>"HTTP"}BandwidthIris::SipPeerProducts.update_origination_settings("site_id","sippeer_id",data)putsBandwidthIris::SipPeerProducts.get_termination_settings("site_id","sippeer_id")data={:voice_protocol=>"HTTP"}putsBandwidthIris::SipPeerProducts.create_termination_settings("site_id","sippeer_id",data)data={:voice_protocol=>"HTTP"}BandwidthIris::SipPeerProducts.update_termination_settings("site_id","sippeer_id",data)putsBandwidthIris::SipPeerProducts.get_sms_feature_settings("site_id","sippeer_id")data={:sip_peer_sms_feature_settings=>{:toll_free=>true,:protocol=>"HTTP",:zone_1=>true,:zone_2=>false,:zone_3=>false,:zone_4=>false,:zone_5=>false},:http_settings=>{}}putsBandwidthIris::SipPeerProducts.create_sms_feature_settings("site_id","sippeer_id",data)data={:sip_peer_sms_feature_settings=>{:toll_free=>true,:protocol=>"HTTP",:zone_1=>true,:zone_2=>false,:zone_3=>false,:zone_4=>false,:zone_5=>false},:http_settings=>{}}putsBandwidthIris::SipPeerProducts.update_sms_feature_settings("site_id","sippeer_id",data)BandwidthIris::SipPeerProducts.delete_sms_feature_settings("site_id","sippeer_id")putsBandwidthIris::SipPeerProducts.get_mms_feature_settings("site_id","sippeer_id")data={:mms_settings=>{:protocol=>"HTTP"},:protocols=>{:HTTP=>{:http_settings=>{}}}}putsBandwidthIris::SipPeerProducts.create_mms_feature_settings("site_id","sippeer_id",data)data={:mms_settings=>{:protocol=>"HTTP"},:protocols=>{:HTTP=>{:http_settings=>{}}}}BandwidthIris::SipPeerProducts.update_mms_feature_settings("site_id","sippeer_id",data)BandwidthIris::SipPeerProducts.delete_mms_feature_settings("site_id","sippeer_id")putsBandwidthIris::SipPeerProducts.get_mms_feature_mms_settings("site_id","sippeer_id")putsBandwidthIris::SipPeerProducts.get_messaging_application_settings("site_id","sippeer_id")data={:http_messaging_v2_app_id=>"4-d-4-8-5"}putsBandwidthIris::SipPeerProducts.update_messaging_application_settings("site_id","sippeer_id",data)putsBandwidthIris::SipPeerProducts.get_messaging_settings("site_id","sippeer_id")data={:break_out_countries=>{:country=>"CAN"}}putsBandwidthIris::SipPeerProducts.update_messaging_settings("site_id","sippeer_id",data)data={:description=>"Email to Bldg. 3 Front Desk",:type=>"EMAIL",:email_address=>"foo@bar.com"}enr=BandwidthIris::EmergencyNotificationRecipients.create_emergency_notification_recipient(data)putsenrenrs=BandwidthIris::EmergencyNotificationRecipients.get_emergency_notification_recipients()putsenrsenr=BandwidthIris::EmergencyNotificationRecipients.get_emergency_notification_recipient("id")putsenrdata={:description=>"Email to Bldg. 3 Front Desk",:type=>"EMAIL",:email_address=>"foo@bar.com"}enr=BandwidthIris::EmergencyNotificationRecipients.replace_emergency_notification_recipient("id",data)putsenrBandwidthIris::EmergencyNotificationRecipients.delete_emergency_notification_recipient("id")data={:customer_order_id=>"value",:added_emergency_notification_group=>{:description=>"description",:added_emergency_notification_recipients=>{:emergency_notification_recipient=>[{:identifier=>"123"}]}}}order=BandwidthIris::EmergencyNotificationGroups.create_emergency_notification_group_order(data)putsorderorders=BandwidthIris::EmergencyNotificationGroups.get_emergency_notification_group_orders()putsordersorder=BandwidthIris::EmergencyNotificationGroups.get_emergency_notification_group_order("id")putsordergroups=BandwidthIris::EmergencyNotificationGroups.get_emergency_notification_groups()putsgroupsgroup=BandwidthIris::EmergencyNotificationGroups.get_emergency_notification_group("id")putsgroupdata={:customer_order_id=>"123",:emergency_notification_endpoint_associations=>{:emergency_notification_group=>{:identifier=>"456"}}}order=BandwidthIris::EmergencyNotificationEndpoints.create_emergency_notification_endpoint_order(data)putsorderorders=BandwidthIris::EmergencyNotificationEndpoints.get_emergency_notification_endpoint_orders()putsordersorder=BandwidthIris::EmergencyNotificationEndpoints.get_emergency_notification_endpoint_order("id")putsorderaeuis=BandwidthIris::AlternateEndUserIdentity.get_alternate_end_user_information()putsaeuisaeui=AlternateEndUserIdentity.get_alternate_caller_information("id")putsaeuiorders=BandwidthIris::TnOptions.get_tn_option_orders()putsordersorder=BandwidthIris::TnOptions.get_tn_option_order("order_id")putsorderbeginorder=BandwidthIris::TnOptions.get_tn_option_order("error_id")rescueBandwidthIris::Errors::GenericError=>eputseenddata={:customer_order_id=>"custom order",:tn_option_groups=>{:tn_option_group=>[{:port_out_passcode=>"12abd38",:telephone_numbers=>{:telephone_number=>["2018551020"]}}]}}order=BandwidthIris::TnOptions.create_tn_option_order(data)putsorderdata={:customer_order_id=>"custom order",:tn_option_groups=>{:tn_option_group=>[{:call_forward=>"2018551022",:telephone_numbers=>{:telephone_number=>["2018551020"]}}]}}order=BandwidthIris::TnOptions.create_tn_option_order(data)putsorderdata={:customer_order_id=>"custom order",:tn_option_groups=>{:tn_option_group=>[{:sms=>"on",:telephone_numbers=>{:telephone_number=>["2018551020"]}}]}}order=BandwidthIris::TnOptions.create_tn_option_order(data)putsorder