Class: Bandwidth::Call

Inherits:
Object
  • Object
show all
Extended by:
ClientWrapper
Includes:
ApiItem, PlayAudioExtensions
Defined in:
lib/bandwidth/call.rb

Overview

The Calls resource lets you make phone calls and view information about previous inbound and outbound calls.

Class Method Summary collapse

Instance Method Summary collapse

Methods included from ClientWrapper

wrap_client_arg

Methods included from PlayAudioExtensions

#play_recording, #speak_sentence

Methods included from ApiItem

#[], #[]=, #initialize, #to_data

Class Method Details

.create(client, data) ⇒ Call

Make a phone call

Examples:

call = Call.create(client, {:from=>"from", :to=>"to"})

Parameters:

  • client (Client)

    optional client instance to make requests

  • data (Hash)

    data to create a call

Returns:

  • (Call)

    created call



41
42
43
44
45
# File 'lib/bandwidth/call.rb', line 41

def self.create(client, data)
  headers = client.make_request(:post, client.concat_user_path(CALL_PATH), data)[1]
  id = Client.get_id_from_location_header(headers[:location])
  self.get(client, id)
end

.get(client, id) ⇒ Call

Get information about a call that was made or received

Examples:

call = Call.get(client, "1")

Parameters:

  • client (Client)

    optional client instance to make requests

  • id (String)

    id of call

Returns:

  • (Call)

    Call instance



16
17
18
19
# File 'lib/bandwidth/call.rb', line 16

def self.get(client, id)
  item = client.make_request(:get, client.concat_user_path("#{CALL_PATH}/#{id}"))[0]
  Call.new(item, client)
end

.list(client, query = nil) ⇒ Array

Get a list of previous calls that were made or received

Examples:

calls = Call.list(client)

Parameters:

  • client (Client)

    optional client instance to make requests

  • query (Hash) (defaults to: nil)

    query options

Returns:

  • (Array)

    array of Call ionstances



28
29
30
31
32
# File 'lib/bandwidth/call.rb', line 28

def self.list(client, query = nil)
  client.make_request(:get, client.concat_user_path(CALL_PATH), query)[0].map do |item|
    Call.new(item, client)
  end
end

Instance Method Details

#answer_on_incomingObject

Answer on an incoming call



142
143
144
145
# File 'lib/bandwidth/call.rb', line 142

def answer_on_incoming()
  update({:state => 'active'})
  reload()
end

#create_gather(data) ⇒ Hash

Gather the DTMF digits pressed

Examples:

gather = call.create_gather("Press a digit")
gather = call.create_gather(:max_digits => 1, :prompt => {:sentence => "Press a digit",  :bargeable => true })

Parameters:

  • data (String|Hash)

    sentence to speak on creating cather if string, otherwise it is hash with gather options

Returns:

  • (Hash)

    created gather



78
79
80
81
82
83
84
85
86
87
88
89
90
# File 'lib/bandwidth/call.rb', line 78

def create_gather(data)
  d = if data.is_a?(String)
        {
          :tag => id, :max_digits => 1,
          :prompt => {:locale => 'en_US', :gender => 'female', :sentence => data, :voice => 'kate', :bargeable => true }
        }
      else
        data
      end
  headers = @client.make_request(:post, @client.concat_user_path("#{CALL_PATH}/#{id}/gather"), d)[1]
  id = Client.get_id_from_location_header(headers[:location])
  get_gather(id)
end

#get_event(event_id) ⇒ Hash

Gets information about one call event

Examples:

e = call.get_event("id")

Parameters:

  • event_id (String)

    id of event

Returns:

  • (Hash)

    event data



115
116
117
# File 'lib/bandwidth/call.rb', line 115

def get_event(event_id)
  @client.make_request(:get, @client.concat_user_path("#{CALL_PATH}/#{id}/events/#{event_id}"))[0]
end

#get_eventsArray

Gets the list of call events for a call

Examples:

events = call.get_events()

Returns:

  • (Array)

    list of events



123
124
125
# File 'lib/bandwidth/call.rb', line 123

def get_events()
  @client.make_request(:get, @client.concat_user_path("#{CALL_PATH}/#{id}/events"))[0]
end

#get_gather(gather_id) ⇒ Hash

Get the gather DTMF parameters and results

Examples:

gather = call.get_gather("id")

Parameters:

  • gather_id (String)

    id of gather

Returns:

  • (Hash)

    gather options



106
107
108
# File 'lib/bandwidth/call.rb', line 106

def get_gather(gather_id)
  @client.make_request(:get, @client.concat_user_path("#{CALL_PATH}/#{id}/gather/#{gather_id}"))[0]
end

#get_recordingsArray

Retrieve all recordings related to the call

Examples:

recordings = call.get_recordings()

Returns:

  • (Array)

    list of recordings



131
132
133
# File 'lib/bandwidth/call.rb', line 131

def get_recordings()
  @client.make_request(:get, @client.concat_user_path("#{CALL_PATH}/#{id}/recordings"))[0]
end

#hangupObject

Hangup a call



136
137
138
139
# File 'lib/bandwidth/call.rb', line 136

def hangup()
  update({:state => 'completed'})
  reload()
end

#play_audio(data) ⇒ Object

Play an audio or speak a sentence in a call

Examples:

call.play_audio(:file_url => "http://host1")

Parameters:

  • data (Hash)

    options for play audio



60
61
62
# File 'lib/bandwidth/call.rb', line 60

def play_audio(data)
  @client.make_request(:post, @client.concat_user_path("#{CALL_PATH}/#{id}/audio"), data)[0]
end

#recording_offObject

Tune off recording of a call



160
161
162
163
# File 'lib/bandwidth/call.rb', line 160

def recording_off()
  update({:recording_enabled => false})
  reload()
end

#recording_onObject

Tune on recording of a call



154
155
156
157
# File 'lib/bandwidth/call.rb', line 154

def recording_on()
  update({:recording_enabled => true})
  reload()
end

#reject_incomingObject

Reject a call



148
149
150
151
# File 'lib/bandwidth/call.rb', line 148

def reject_incoming()
  update({:state => 'rejected'})
  reload()
end

#set_dtmf(dtmf) ⇒ Object

Send DTMF

Examples:

call.send_dtmf("0")

Parameters:

  • dtmf (String)

    dtmf value to send



68
69
70
# File 'lib/bandwidth/call.rb', line 68

def set_dtmf(dtmf)
  @client.make_request(:post, @client.concat_user_path("#{CALL_PATH}/#{id}/dtmf"), {:dtmf_out => dtmf})[0]
end

#update(data) ⇒ Object

Make changes to an active phone call. E.g.: transfer, hang up, answer or reject incoming calls, call recording, etc.

Examples:

call.update(:state=>"completed") #hangup a call

Parameters:

  • data (Hash)

    changed data



52
53
54
# File 'lib/bandwidth/call.rb', line 52

def update(data)
  @client.make_request(:post, @client.concat_user_path("#{CALL_PATH}/#{id}"), data)[0]
end

#update_gather(gather_id, data) ⇒ Object

Update the gather DTMF (Stop Gather)

Examples:

call.update_gather("1", :state => "completed")

Parameters:

  • gather_id (String)

    id of gather

  • data (Hash)

    changed data



97
98
99
# File 'lib/bandwidth/call.rb', line 97

def update_gather(gather_id, data)
  @client.make_request(:post, @client.concat_user_path("#{CALL_PATH}/#{id}/gather/#{gather_id}"), data)[0]
end