Bandwidth Ruby API

Gem for integrating to Bandwidth's Telephony API

Installation

Via rubygems:

gem install ruby-bandwidth

or add to your Gemfile:

gem 'ruby-bandwidth'

Usage

Basic

See {Bandwidth}

Optional, only unless you use Bundler to manage dependencies:

require "ruby-bandwidth"

Initialize API access object and connect to your account data:

USER_ID = "u-ku5k3kzhbf4nligdgweuqie" # Your user id
TOKEN  = "t-apseoipfjscawnjpraalksd" # Your account token
SECRET = "6db9531b2794663d75454fb42476ddcb0215f28c" # Your secret
bandwidth = Bandwidth.new USER_ID, TOKEN, SECRET

Examples

See examples folder for real world examples

Account

See {Bandwidth::API::Account} and {Bandwidth::Types::Account}

bandwidth.account.balance # => 538.3725
bandwidth.account.account_type # => "pre-pay"

Transactions

See {Bandwidth::API::Account} and {Bandwidth::Types::Transaction}

Get a list of transactions

transactions = bandwidth.transactions # => [#<Transaction:0xb642ffc>, #<Transaction:0xb642fe8>]
example_transaction = transactions.first

# A unique identifier for the transaction
example_transaction.id # => "pptx-wqfnffduxiki4fd5ubhv77a"

# The time the transaction was processed
example_transaction.time # => 2013-02-21 13:39:09 UTC

# The transaction amount in dollars, as a string; the currency symbol is not included
example_transaction.amount # => 0.0075

# The type of transaction
example_transaction.type # => "charge"

# The number of product units the transaction charged or credited
example_transaction.units # => "1"

# The product the transaction was related to (not all transactions are related to a product)
example_transaction.product_type # => "sms-out"

# The phone number the transaction was related to (not all transactions are related to a phone number)
example_transaction.number # => "+12345678910"

Filter by time period

from = "2013-02-21T13:38:00Z"
to = "2013-02-21T13:40:00Z"

transactions = bandwidth.transactions from_date: Time.parse(from), to_date: Time.parse(to)

Filter by payment type

transactions = bandwidth.transactions type: Bandwidth::API::Account::TransactionTypes::AUTO_RECHARGE

Available payment types:

CHARGE, PAYMENT, CREDIT, AUTO_RECHARGE

Messages

See {Bandwidth::API::Messages} and {Bandwidth::Types::Message}

Send text messages

from = "+19195551212"
to = "+13125556666"
text = "Good morning, this is a test message"

message_id = bandwidth.send_message from, to, text

Get message

message = bandwidth.message message_id

# A unique ID of the message
message.id # => "m-6usiz7e7tsjjafn5htk5huy"

# Message direction. One of:
# in: A message that came from the telephone network to one of your numbers (an "inbound" message)
# out: A message that was sent from one of your numbers to the telephone network (an "outbound" message)
message.direction # => "out"

# The message sender's telephone number
message.from # => "+19195551212"

# The message sender's telephone number
message.to # => "+13125556666"

# One of the message states
message.state # => "sent"

# The time the message resource was created (follows the ISO 8601 format)
message.time # => 2012-10-05 20:38:11 UTC

# The message contents
message.text # => "Good morning, this is a test message"

Get a list of messages

messages = bandwidth.messages # => [#<Message:0xb642ffc>, #<Message:0xb642fe8>]

Get a list of messages filtering by sender or/and recipient

messages = bandwidth.messages from: "+19195551212", to:"+13125556666" # => [#<Message:0xa8526e0>, #<Message:0xa85ee7c>]

Available phone numbers

Lets you search for numbers that are available for use with your application.

See {Bandwidth::API::AvailableNumbers}, {Bandwidth::Types::PhoneNumber} and {Bandwidth::Types::LocalPhoneNumber}

Local

Searches for available local numbers by location or pattern criteria.

bandwidth.available_numbers # => [#<LocalPhoneNumber:+19195551212>, #<LocalPhoneNumber:+13125556666>, ...]

Filter by state, ZIP code or area code

You can filter by one of those criterias:

bandwidth.available_numbers zip: '12345'

bandwidth.available_numbers state: 'CA'

bandwidth.available_numbers area_code: '919'

Filter by city

You can additionally specify a city:

bandwidth.available_numbers state: 'NC', city: 'Cary'

Filter phone number by pattern

bandwidth.available_numbers pattern: "*2?9*" # => [#<LocalPhoneNumber:+19192972393>, ...]

Toll free

Searches for available Toll Free numbers.

bandwidth.available_toll_free_numbers # => [#<PhoneNumber:+19195551212>, #<PhoneNumber:+13125556666>, ...]

Filter phone number by pattern

bandwidth.available_toll_free_numbers pattern: "*2?9*" # => [#<PhoneNumber:+18557626967>, #<PhoneNumber:+18557712996>]

Phone numbers

Lets you get phone numbers and manage numbers you already have

See {Bandwidth::API::PhoneNumbers} and {Bandwidth::Types::AllocatedPhoneNumber}

List allocated numbers

Get a list of allocated numbers

numbers = bandwidth.phone_numbers # => [#<AllocatedPhoneNumber:+19195551212>, #<AllocatedPhoneNumber:+13125556666>, ...]

number = numbers.first

# Phone number identifier
number.id # => "n-6nuymbplrb3zd5yazve2ley"

# Phone number in E.164 format
number.number # => "+19195551212"

# Phone number in human readable format
number.national_number # => "(919) 555-1212"

# Custom name
number.name # => "home phone"

# State
number.state # => "NC"

Allocate a number

number_id = bandwidth.allocate_number "+19195551212"

Check allocated phone number details

bandwidth.phone_number_details # => #<AllocatedPhoneNumber:+19195551212>

Remove a number from account

bandwidth.remove_number number_id

Calls

Lets you make phone calls and view information about previous inbound and outbound calls

See {Bandwidth::API::Calls}, {Bandwidth::Types::Call}, {Bandwidth::Types::DTMF}, {Bandwidth::Types::Record}, {Bandwidth::Audio::Sentence} and {Bandwidth::Audio::File}

List previous calls that were made or received

Gets a list of active and historic calls you made or received

calls = bandwidth.calls # => [#<Call:0x9906e34>, ...]
call = calls.first

# Call unique ID
call.id # => "c-clgsmnrn4ruwdx36rxf7zoi"

# Call direction (in: incoming Call, out: outgoing Call)
call.direction # => "out"

# Caller ID
call.from # => "+19195551212"

# Called ID
call.to # => "+13125556666"

# Call state
call.state # => "completed"

# Date when the call was created
call.start_time # => 2013-02-08 13:15:47 UTC

# Date when the call was answered
call.active_time # => 2013-02-08 13:15:52 UTC

# Date when the call ended
call.end_time # => 2013-02-08 13:15:55 UTC

# Chargeable call duration (seconds between activeTime and endTime)
call.chargeable_duration # => 60

Filtering calls

You can filter by any combination of caller, callee, bridge id and conference id:

bandwidth.calls from: "+19195551212"

bandwidth.calls from: "+19195551212", to: "+13125556666"

bandwidth.calls bridge_id: "brg-72x6e5d6gbthaw52vcsouyq"

bandwidth.calls conference_id: "conf-7qrj2t3lfixl4cgjcdonkna"

Make a phone call

call_id = bandwidth.dial "+19195551212", "+13125556666"

Recording call

This will make a call and start recording immediately:

call_id = bandwidth.dial "+19195551212", "+13125556666", recording_enabled: true

Bridging a call

This will create a call in a bridge:

bridge_id = "brg-72x6e5d6gbthaw52vcsouyq"
call_id = bandwidth.dial "+19195551212", "+13125556666", bridge_id: bridge_id

Get information about a call that was made or received

Gets information about an active or completed call

call = bandwidth.call_info "c-xytsl6nfcayzsxdbqq7q36i"

Make changes to an active phone call

Changes properties of an active phone call

Hang up

bandwidth.hangup "c-xytsl6nfcayzsxdbqq7q36i"

Transfer

bandwidth.transfer "c-xytsl6nfcayzsxdbqq7q36i", "+19195551212"

It's also possible to set caller id:

bandwidth.transfer "c-xytsl6nfcayzsxdbqq7q36i", "+19195551212", transfer_caller_id: "+19195553131"

and/or play audio file or speak some text:

audio = Bandwidth::Audio::Sentence.new "Call has been transferred"
bandwidth.transfer "c-xytsl6nfcayzsxdbqq7q36i", "+19195551212", audio: audio

Set recording state

To start recording:

bandwidth.recording_state "c-xytsl6nfcayzsxdbqq7q36i", true

Play an audio or speak a sentence in a call

Plays an audio file or speak a sentence in a phone call

sentence = Bandwidth::Audio::Sentence.new "Hello, thank you for calling."
audio_file = Bandwidth::Audio::File.new "http://example.com/audio.mp3"

bandwidth.play call_id, sentence
bandwidth.play call_id, audio_file

Sentence options

You can set a locale and gender (default is female):

audio = Bandwidth::Audio::Sentence.new "Guten Tag",
  locale: Bandwidth::Audio::Sentence::LOCALE_DE,
  gender: Bandwidth::Audio::Sentence::MALE

bandwidth.play audio

General options

You can play audio in a loop:

audio = Bandwidth::Audio::File.new "http://example.com/audio.mp3", loop_enabled: true
bandwidth.play audio

Send DTMF

Send DTMF to the call

bandwidth.dtmf call_id, "1234"

Wait until the specified number of DTMF digits are pressed

dtmf = bandwidth.gather call_id
dtmf.digits # => "*123#"

Options

You can specify options.

The maximum number of digits to collect, not including terminating digits (maximum 30)

dtmf = bandwidth.gather call_id, max_digits: 3

Stop gathering if a DTMF digit is not detected in this many seconds (default 5.0; maximum 30.0)

dtmf = bandwidth.gather call_id, inter_digit_timeout: 10

A string of DTMF digits that end the gather operation immediately if any one of them is detected (default "#"; an empty string means collect all DTMF until max_digits or the timeout). The gather ends if either 0, #, or * is detected:

dtmf = bandwidth.gather call_id, terminating_digits: "0#*"

A string you choose that will be included with the response and events for this gather operation

dtmf = bandwidth.gather call_id, tag: 'abc123'

Plays or speaks to a call when gathering DTMF. Note a specical bargeable parameter to interrupt prompt (audio or sentence) at first digit gathered (default is true).

audio = Bandwidth::Audio::File.new "http://example.com/audio.mp3", bargeable: false
dtmf = bandwidth.gather call_id, audio: audio

Retrieve all recordings related to the call

records = bandwidth.call_records call_id
record = records.first

record.id # => "rec-togfrwqp2bxxezstzbzadra"
record.media # => "c-j4gferrrn72ivf3ov56ccay-1.wav"
record.start_time # => 2013-02-08 12:05:17 UTC
record.end_time # => 2013-02-08 13:15:55 UTC
record.state # => "complete"

Media

Media API lets you upload your media files to Bandwidth servers so they can be used in scripts without requiring a separate hosting provider. You can upload files up to 50 MB and file storage is free for an unlimited number of files. These files are not available for public download. Media files include all call recordings.

See {Bandwidth::API::Media} and {Bandwidth::Types::Medium}

Get a list of your media files

media = bandwidth.media # => [#<Medium:0xa3e7948>, ...]

medium = media.first
medium.content_length # => 2703360
medium.media_name # => "mysong.mp3"

Uploads a media file to the name you choose

bandwidth.upload "greeting.mp3", File.new("greeting.mp3")

bandwidth.upload "greeting.mp3", StringIO.new(some_binary_data_here)

Download media file

data = bandwidth.download "c-bonay3r4mtwbplurq4nkt7q-1.wav"

Permanently deletes a media file you uploaded

bandwidth.delete_media "greeting.mp3"

Recordings

Retrieve call recordings, filtering by Id, user and/or calls. The recording information retrieved by GET method contains only textual data related to call recording as described on Properties section. To properly work with recorded media content such as download and removal of media file, please access Media documentation.

See {Bandwidth::API::Records} and {Bandwidth::Types::RecordWithCall}

List records

List a user's call records

records = bandwidth.records # => [#<Record:0xa798bf0>, ...]

record = records.first
record.end_time # => 2013-02-08 13:15:47 UTC
record.id # => "rec-togfrwqp2bxxezstzbzadra"
record.media # => "c-bonay3r4mtwbplurq4nkt7q-1.wav"
record.call # => "call": "c-bonay3r4mtwbplurq4nkt7q"
record.start_time # => 2013-02-08 13:16:35 UTC
record.state # => "complete"

Get recording information

bandwidth.record "rec-togfrwqp2bxxezstzbzadra" # => #<Record:0xa798bf0>

Bridges

Bridge two calls allowing two way audio between them.

See {Bandwidth::API::Bridges} and {Bandwidth::Types::Bridge}

Get a list of previous bridges

bridges = bandwidth.bridges # => [#<Bridge:0xa466c5c>, ...]

bridge = bridges.first
bridge.id # => "brg-7cp5tvhydw4a3esxwpww5qa"
bridge.state # => "completed"
bridge.bridge_audio # => true
bridge.created_time => 2013-04-22 13:55:30 UTC
bridge.activated_time => 2013-04-22 13:55:30 UTC
bridge.completed_time => 2013-04-22 13:56:30 UTC

Create a bridge

bandwidth.bridge "c-mxdxhidpjr6a2bp2lxq6vaa", "c-c2rui2kbrldsfgjhlvlnjaq"

Disable two way audio path

Audio is bridged by default, but it's possible to override that passing an option:

bandwidth.bridge "c-mxdxhidpjr6a2bp2lxq6vaa", "c-c2rui2kbrldsfgjhlvlnjaq", bridge_audio: false

Get information about a specific bridge

bandwidth.bridge_info "brg-7cp5tvhydw4a3esxwpww5qa" # => <Bridge:0xa466c5c>

Bridging audio

bandwidth.bridge_audio "brg-7cp5tvhydw4a3esxwpww5qa", true

Play a media file or speak a sentence in a bridge

sentence = Bandwidth::Audio::Sentence.new "Hello, thank you for calling."
audio_file = Bandwidth::Audio::File.new "http://example.com/audio.mp3"

bandwidth.bridge_play bridge_id, sentence
bandwidth.bridge_play bridge_id, audio_file

Destroy bridge

Removes all calls from bridge. It will also change the bridge state to 'completed' and this bridge can not be updated anymore

bandwidth.unbridge bridge_id

Get the calls that are on the bridge

calls = bandwidth.bridged_calls "brg-7cp5tvhydw4a3esxwpww5qa" # => [#<BridgedCall:0x9906e34>, #<BridgedCall:0xaf0f208>]

call = calls.first
call.bridge_id # => "brg-7cp5tvhydw4a3esxwpww5qa"
call.id # => "c-clgsmnrn4ruwdx36rxf7zoi"
call.direction # => "out"
call.from # => "+19195551212"
call.to # => "+13125556666"
call.state # => "active"
call.startTime # => 2013-02-08 13:15:47 UTC
call.activeTime # => 2013-02-08 13:15:52 UTC
call.recording_enabled # => false

Conferences

Allows you create conferences, add members to it, play audio, speak text, mute/unmute members, hold/unhold members and other things related to conferencing.

See {Bandwidth::API::Conferences}, {Bandwidth::Types::Conference} and {Bandwidth::Types::ConferenceMember}

Create aa conference

Creates a conference with no members

conference_id = bandwidth.conference "+19195551212" # => "conf-7qrj2t3lfixl4cgjcdonkna"

Retrieve conference information

bandwidth.conference_info "conf-7qrj2t3lfixl4cgjcdonkna"

Terminate conference

bandwidth.conference_terminate "conf-7qrj2t3lfixl4cgjcdonkna"

Muting conference

bandwidth.conference_mute "conf-7qrj2t3lfixl4cgjcdonkna", true

Play an audio/speak a sentence in the conference

bandwidth.conference_play "conf-7qrj2t3lfixl4cgjcdonkna", audio

Add a member to a conference

call_id = bandwidth.dial "+19195551212", "+13125556666"
member_id = bandwidth.conference_add "conf-7qrj2t3lfixl4cgjcdonkna", call_id # => "member-ae4b8krsskpuvnw6nsitg78"

List all members from a conference

members = bandwidth.conference_members "conf-7qrj2t3lfixl4cgjcdonkna"

member = members.first
member.id # => "member-i3bgynrxllq3v3wiisiuz2q"
member.added_time # => 2013-07-12 17:54:47 UTC
member.hold # => false
member.mute # => false
member.state # => "active"
member.call # => "c-lem5j6326b2nyrej7ieheki"

Conference member operations

Remove from conference

bandwidth.conference_member_remove conference_id, member_id

Muting

bandwidth.conference_member_mute conference_id, member_id, true

Putting on hold

bandwidth.conference_member_hold conference_id, member_id, true

Play an audio/speak a sentence

sentence = Bandwidth::Audio::Sentence.new "Hello, thank you for calling."
audio_file = Bandwidth::Audio::File.new "http://example.com/audio.mp3"

bandwidth.conference_member_play conference_id, member_id, sentence
bandwidth.conference_member_play conference_id, member_id, audio_file

Retrieve information about a particular conference member

member = bandwidth.conference_member_info conference_id, member_id
member.id # => "member-i3bgynrxllq3v3wiisiuz2q"
member.added_time # => 2013-07-12 17:54:47 UTC
member.hold # => false
member.mute # => false
member.state # => "active"
member.call # => "c-lem5j6326b2nyrej7ieheki"

Useful links

Original api docs: https://catapult.inetwork.com/docs/

For contributors

Prerequisites

You will need some gems to test and develop bandwidth gem. Install them:

gem install bundler
bundle install

Running tests

rake

Building and installing gem

gem build bandwidth.gemspec
gem install bandwidth<VERSION>.gem

Documentation generation

Generates documentation:

yard doc

Check what's not covered by documentation:

yard stats --list-undoc

Start local documentation server at http://localhost:8808/docs

yard server

Contribution guidelines

Create a topic branch. Fix the issue. Cover with tests. Add documentation. Send pull request with commentary.