ruby-bandwidth

Deprecation Notice

This project is deprecated. Please go to https://github.com/Bandwidth/ruby-sdk

Bandwidth Bandwidth's App Platform Ruby SDK

Notice: As of April 2019, versions of ruby-bandwidth less than 2.0.0 will not be compatible with Bandwidth's V2 Messaging. If you are using Bandwidth's V2 Messaging, you will need to update your ruby-bandwidth gem version to 2.0.0 or above. If you are not using Bandwidth's V2 Messaging, you do not need to update.

With ruby-bandwidth you have access to the entire set of API methods including:

• Account - get user's account data and transactions,
• Application - manage user's applications,
• AvailableNumber - search free local or toll-free phone numbers,
• Bridge - control bridges between calls,
• Call - get access to user's calls,
• Conference - manage user's conferences,
• ConferenceMember - make actions with conference members,
• Domain - get access to user's domains,
• EntryPoint - control of endpoints of domains,
• Error - list of errors,
• Media - list, upload and download files to Bandwidth API server,
• Message - send SMS/MMS, list messages,
• NumberInfo - receive CNUM info by phone number,
• PhoneNumber - get access to user's phone numbers,
• Recording - mamange user's recordings.

Also you can work with Bandwidth XML using special types (in namespace Bandwidth::Xml).

Release Notes

Version	Notes
2.0.4	Fixed SIP Headers fields for creating a call
2.0.5	Fixed SIP key names
2.0.6	Changed timeout to 140 seconds
3.0.0	Update error responses. Errors::GenericError now returns the status code as code and the response body as message. Errors::GenericIrisError now returns only when the http code is >= 400

Install

Via rubygems:

gem install ruby-bandwidth

or add to your Gemfile:

gem "ruby-bandwidth"

Getting Started

• Install ruby-bandwidth,
• Get user id, api token and secret - to use the Catapult API you need these data. You can get them here on the tab "Account",
• Set user id, api token and secret - you can do that with 2 ways:

client=Bandwidth::Client.new(:user_id=>"userId",:api_token=>"token",:api_secret=>"secret")# Or you can use default client instance# Do that only onceClient.global_options={:user_id=>"userId",:api_token=>"token",:api_secret=>"secret"}

Usage

All "static" (classs) functions support 2 ways to be called: with client instance as first arg or without client instance (default client instance will be used then)

client=Bandwidth::Client.new(:user_id=>"userId",:api_token=>"token",:api_secret=>"secret")calls=Bandwidth::Call.list(client,{:page=>1})# Or you can use default client instance# You should set up its global options before using of api functionscalls=Bandwidth::Call.list(:page=>1)

Read Catapult Api documentation for more details

Examples

All examples assume you have already setup your auth data!

List all calls from special number

calls=Bandwidth::Call.list({:from=>"+19195551212"})#orclient=Bandwidth::Client.new(:user_id=>"userId",:api_token=>"token",:api_secret=>"secret")calls=Bandwidth::Call.list(client,{:from=>"+19195551212"})

List all received messages

messages=Bandwidth::Message.list({:state=>"received"})#orclient=Bandwidth::Client.new(:user_id=>"userId",:api_token=>"token",:api_secret=>"secret")messages=Bandwidth::Message.list(client,{:state=>"received"})

Send SMS

message=Bandwidth::Message.create({:from=>"+19195551212",:to=>"+191955512142",:text=>"Test"})#orclient=Bandwidth::Client.new(:user_id=>"userId",:api_token=>"token",:api_secret=>"secret")message=Bandwidth::Message.create(client,{:from=>"+19195551212",:to=>"+191955512142",:text=>"Test"})

Send some SMSes

statuses=Bandwidth::Message.create([{:from=>"+19195551212",:to=>"+191955512142",:text=>"Test"},{:from=>"+19195551212",:to=>"+191955512143",:text=>"Test2"}])#orclient=Bandwidth::Client.new(:user_id=>"userId",:api_token=>"token",:api_secret=>"secret")statuses=Bandwidth::Message.create(client,[{:from=>"+19195551212",:to=>"+191955512142",:text=>"Test"},{:from=>"+19195551212",:to=>"+191955512143",:text=>"Test2"}])

Upload file

Bandwidth::Media.upload("avatar.png",File.open("/local/path/to/file.png","r"),"image/png")#orclient=Bandwidth::Client.new(:user_id=>"userId",:api_token=>"token",:api_secret=>"secret")Bandwidth::Media.upload(client,"avatar.png",File.open("/local/path/to/file.png","r"),"image/png")

Make a call

call=Bandwidth::Call.create({:from=>"+19195551212",:to=>""+191955512142"}) #or client = Bandwidth::Client.new(:user_id => "userId", :api_token => "token", :api_secret => "secret") call = Bandwidth::Call.create(client, {:from => "+19195551212", :to => ""+191955512142"})

Reject incoming call

call.reject_incoming()

Create a gather

gather=call.create_gather({:max_digits=>3,:inter_digit_timeout=>5,:prompt=>{:sentence=>"Please enter 3 digits"}})

Start a conference

conference=Bandwidth::Conference.create({:from=>"+19195551212"})#orclient=Bandwidth::Client.new(:user_id=>"userId",:api_token=>"token",:api_secret=>"secret")conference=Bandwidth::Conference.create(client,{:from=>"+19195551212"})

Connect 2 calls to a bridge

bridge=Bandwidth::Bridge.create({:call_ids=>[call_id1,call_id2]})#orclient=Bandwidth::Client.new(:user_id=>"userId",:api_token=>"token",:api_secret=>"secret")bridge=Bandwidth::Bridge.create(client,{:call_ids=>[call_id1,call_id2]})

Search available local numbers to buy

numbers=Bandwidth::AvailableNumber.search_local({:state=>"NC",:city=>"Cary"})#orclient=Bandwidth::Client.new(:user_id=>"userId",:api_token=>"token",:api_secret=>"secret")numbers=Bandwidth::AvailableNumber.search_local(client,{:state=>"NC",:city=>"Cary"})

Get CNAM info for a number

info=Bandwidth::NumberInfo.get("+19195551212")#orclient=Bandwidth::Client.new(:user_id=>"userId",:api_token=>"token",:api_secret=>"secret")info=Bandwidth::NumberInfo.get(client,"+19195551212")

Buy a phone number

number=Bandwidth::PhoneNumber.create({:number=>"+19195551212"})#orclient=Bandwidth::Client.new(:user_id=>"userId",:api_token=>"token",:api_secret=>"secret")number=Bandwidth::PhoneNumber.create(client,{:number=>"+19195551212"})

List recordings

list=Bandwidth::Recording.list()#orclient=Bandwidth::Client.new(:user_id=>"userId",:api_token=>"token",:api_secret=>"secret")list=Bandwidth::Recording.list(client)

Generate Bandwidth XML

response=Bandwidth::Xml::Response.new()speak_sentence=Bandwidth::Xml::Verbs::SpeakSentence.new({:sentence=>"Transferring your call, please wait.",:voice=>"paul",:gender=>"male",:locale=>"en_US"})transfer=Bandwidth::Xml::Verbs::Transfer.new({:transfer_to=>"+13032288849",:transfer_caller_id=>"private",:speak_sentence=>{:sentence=>"Inner speak sentence.",:voice=>"paul",:gender=>"male",:locale=>"en_US"}})hangup=Bandwidth::Xml::Verbs::Hangup.new()response << speak_sentence << transfer << hangup# as alternative way we can pass list of verbs to constructor of Response# response = Bandwidth::Xml::Response.new([speak_sentence, transfer, hangup])putsresponse.to_xml()

See directory samples for more examples. See ruby-bandwidth-example for more complex examples of using this module.

Messaging 2.0

Send SMS (v2)

auth_data={user_name: 'user',password: 'password',account_id: 'accountId',subaccount_id: 'subaccountId'}# Before sending sms you should have messaging application on Bandwidth dashboard. You should create it by next callapplication=Bandwidth::V2::Message.create_messaging_application(auth_data,{:name=>'My messaging application',:callback_url=>'http://server/to/handle/messages/events',:location_name=>'current',:is_default_location=>false,:sms_options=>{:toll_free_enabled=>true},:mms_options=>{:enabled=>true}})# After that you should reserve 1 or some phone nubmers on Bandwidth Dashboardnumbers=Bandwidth::V2::Message.search_and_order_numbers(auth_data,application)do |query|
query.AreaCodeSearchAndOrderTypedo |b|
b.AreaCode("910")b.Quantity(1)endend# Now you can send messages from reserved numbers. Don't forget to pass :application_idclient=Bandwidth::Client.new(:user_id=>"userId",:api_token=>"token",:api_secret=>"secret")message=Bandwidth::V2::Message.create(client,{:from=>numbers[0],:to=>["+191955512142"],:text=>"Test",:application_id=>application[:application_id]})

Documentation generation

Generates documentation:

yard doc

Samples

More sample applications