0.16
Repository is archived
A long-lived project that still receives updates
Gem for integrating to Bandwidth's Catapult API
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
 Project Readme

ruby-bandwidth

Deprecation Notice

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

Build

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 once
  Client.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 functions
  calls = 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"})
  #or
  client = 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"})
  #or
  client = 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"})
  #or
  client = 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"}])
  #or
  client = 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")
  #or
  client = 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"})
  #or
  client = 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]})
  #or
  client = 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"})
  #or
  client = 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")
  #or
  client = 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"})
  #or
  client = 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()
  #or
  client = 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])

  puts response.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 call
  application = 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 Dashboard
  numbers = Bandwidth::V2::Message.search_and_order_numbers(auth_data, application) do |query|
      query.AreaCodeSearchAndOrderType do |b|
         b.AreaCode("910")
         b.Quantity(1)
      end
  end

  # Now you can send messages from reserved numbers. Don't forget to pass :application_id
  client = 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