Class: Vonage::Voice

Inherits:
Namespace
  • Object
show all
Defined in:
lib/vonage/voice.rb

Defined Under Namespace

Classes: DTMF, ListResponse, Ncco, Stream, Talk

Instance Method Summary collapse

Instance Method Details

#create(params) ⇒ Response

Create an outbound Call.

Examples:

response = client.voice.create({
  to: [{type: 'phone', number: '14843331234'}],
  from: {type: 'phone', number: '14843335555'},
  answer_url: ['https://example.com/answer']
})

Parameters:

  • params (Hash)

Options Hash (params):

  • :to (required, Array<Hash>) —

    Connect to a Phone (PSTN) number, SIP Endpoint, Websocket, or VBC extension. The to Hash can contain a number of different properties depending on the type. See the API reference for specific details.

  • :from (Hash) —

    Connect to a Phone (PSTN) number. Should not be set if :random_from_number is true If not set, then :random_from_number will automatically be set to true

  • :random_from_number (Boolean) —

    Set to true to use random phone number as from. The number will be selected from the list of the numbers assigned to the current application. random_from_number: true cannot be used together with :from.

  • :ncco (Array<String>) —

    The Vonage Call Control Object to use for this call. Required unless :answer_url is provided.

  • :answer_url (Array<String>) —

    The webhook endpoint where you provide the Vonage Call Control Object that governs this call. Required unless :ncco is provided.

  • :answer_method (String) —

    The HTTP method used to send event information to answer_url.

  • :event_url (required, Array<String>) —

    The webhook endpoint where call progress events are sent to.

  • :event_method (String) —

    The HTTP method used to send event information to event_url.

  • :machine_detection (String) —

    Configure the behavior when Vonage detects that the call is answered by voicemail.

  • :advanced_machine_detection (Hash) —

    Configure the behavior of Vonage's advanced machine detection. Overrides machine_detection if both are set. Hash with three possible properties:

    • :behavior [String]: Must be one of continue or hangup. When hangup is used, the call will be terminated if a machine is detected. When continue is used, the call will continue even if a machine is detected.
    • :mode [String]: Must be one of detect or detect_beep. Detect if machine answered and sends a human or machine status in the webhook payload. When set to detect_beep, the system also attempts to detect voice mail beep and sends an additional parameter sub_state in the webhook with the value beep_start.
    • :beep_timeout [Integer]: Min: 45, Max: 120. Maximum time in seconds Vonage should wait for a machine beep to be detected. A machine event with sub_state set to beep_timeout will be sent if the timeout is exceeded.
  • :length_timer (Integer) —

    Set the number of seconds that elapse before Vonage hangs up after the call state changes to in_progress.

  • :ringing_timer (Integer) —

    Set the number of seconds that elapse before Vonage hangs up after the call state changes to ringing.

Returns:

See Also:



76
77
78
79
80
81
82
83
84
85
86
 
# File 'lib/vonage/voice.rb', line 76

def create(params)
  if params.key?(:from) && params[:random_from_number] == true
    raise ClientError.new("`from` should not be set if `random_from_number` is `true`")
  end

  if params && !params.key?(:from)
    params.merge!(random_from_number: true)
  end

  request('/v1/calls', params: params, type: Post)
end

#dtmf ⇒ DTMF

Returns:



281
282
283
 
# File 'lib/vonage/voice.rb', line 281

def dtmf
  @dtmf ||= DTMF.new(@config)
end

#earmuff(id) ⇒ Response

Earmuff an in progress call.

Examples:

response = client.voice.earmuff(id)

Parameters:

  • id (String)

Returns:

See Also:



227
228
229
 
# File 'lib/vonage/voice.rb', line 227

def earmuff(id)
  update(id, action: 'earmuff')
end

#get(id) ⇒ Response

Get detail of a specific call.

Examples:

response = client.voice.get(id)

Parameters:

  • id (String)

Returns:

See Also:



146
147
148
 
# File 'lib/vonage/voice.rb', line 146

def get(id)
  request('/v1/calls/' + id)
end

#hangup(id) ⇒ Response

Hangup an in progress call.

Examples:

response = client.voice.hangup(id)

Parameters:

  • id (String)

Returns:

See Also:



182
183
184
 
# File 'lib/vonage/voice.rb', line 182

def hangup(id)
  update(id, action: 'hangup')
end

#list(params = nil, auto_advance = true) ⇒ ListResponse

Get details of your calls.

Examples:

response = client.voice.list
response.each do |item|
  puts "#{item.uuid} #{item.direction} #{item.status}"
end

Parameters:

  • params (Hash) (defaults to: nil)

Options Hash (params):

  • :status (String) —

    Filter by call status.

  • :date_start (String) —

    Return the records that occurred after this point in time.

  • :date_end (String) —

    Return the records that occurred before this point in time.

  • :page_size (Integer) —

    Return this amount of records in the response.

  • :record_index (Integer) —

    Return calls from this index in the response.

  • :order (String) —

    Either ascending or descending order.

  • :conversation_uuid (String) —

    Return all the records associated with a specific conversation.

  • :auto_advance (Boolean) —

    Set this to false to not auto-advance through all the pages in the record and collect all the data. The default is true.

Returns:

See Also:



127
128
129
130
131
132
133
 
# File 'lib/vonage/voice.rb', line 127

def list(params = nil, auto_advance = true)
  if params && !params.key?(:auto_advance)
    params.merge!(auto_advance: true)
  end

  request('/v1/calls', params: params, response_class: ListResponse)
end

#mute(id) ⇒ Response

Mute an in progress call.

Examples:

response = client.voice.mute(id)

Parameters:

  • id (String)

Returns:

See Also:



197
198
199
 
# File 'lib/vonage/voice.rb', line 197

def mute(id)
  update(id, action: 'mute')
end

#stream ⇒ Stream

Returns:



269
270
271
 
# File 'lib/vonage/voice.rb', line 269

def stream
  @stream ||= Stream.new(@config)
end

#talk ⇒ Talk

Returns:



275
276
277
 
# File 'lib/vonage/voice.rb', line 275

def talk
  @talk ||= Talk.new(@config)
end

#transfer(id, destination:) ⇒ Response

Transfer an in progress call.

Examples:

destination = {
  type: 'ncco',
  url: ['https://example.com/ncco.json']
}

response = client.voice.transfer(id, destination: destination)

Parameters:

  • id (String)
  • destination (Hash)

Returns:

See Also:



263
264
265
 
# File 'lib/vonage/voice.rb', line 263

def transfer(id, destination:)
  update(id, action: 'transfer', destination: destination)
end

#unearmuff(id) ⇒ Response

Unearmuff an in progress call.

Examples:

response = client.voice.unearmuff(id)

Parameters:

  • id (String)

Returns:

See Also:



242
243
244
 
# File 'lib/vonage/voice.rb', line 242

def unearmuff(id)
  update(id, action: 'unearmuff')
end

#unmute(id) ⇒ Response

Unmute an in progress call.

Examples:

response = client.voice.unmute(id)

Parameters:

  • id (String)

Returns:

See Also:



212
213
214
 
# File 'lib/vonage/voice.rb', line 212

def unmute(id)
  update(id, action: 'unmute')
end

#update(id, params) ⇒ Response

Modify an in progress call.

Examples:

response = client.voice.update(id, action: 'hangup')

Parameters:

  • id (String)
  • params (Hash)

Options Hash (params):

  • :action (required, String)
  • :destination (Hash) —

    Required when :action is transfer.

Returns:

See Also:



167
168
169
 
# File 'lib/vonage/voice.rb', line 167

def update(id, params)
  request('/v1/calls/' + id, params: params, type: Put)
end

#verify_webhook_token(token:, signature_secret: @config.signature_secret) ⇒ Boolean

Validate a JSON Web Token from a Voice API Webhook.

Parameters:

  • :token (String, required) —

    The JWT from the Webhook's Authorization header

  • :signature_secret (String, optional) —

    The account signature secret. Required, unless signature_secret is set in Config

Returns:

  • (Boolean) —

    true, if the JWT is verified, false otherwise



292
293
294
 
# File 'lib/vonage/voice.rb', line 292

def verify_webhook_token(token:, signature_secret: @config.signature_secret)
  JWT.verify_hs256_signature(token: token, signature_secret: signature_secret)
end