Method: Plivo::Resources::CallInterface#create

Defined in:
lib/plivo/resources/calls.rb

#create(from, to, answer_url, answer_method = 'POST', options = nil) ⇒ Call

Makes an outbound call

Parameters:

  • from (String)
  • to (Array)
  • answer_url (String)
  • answer_method (String) (defaults to: 'POST')
  • options (Hash) (defaults to: nil)

Options Hash (options):

  • :answer_method (String) —

    • The method used to call the answer_url. Defaults to POST.

  • :ring_url (String) —

    • The URL that is notified by Plivo when the call is ringing. Defaults not set.

  • :ring_method (String) —

    • The method used to call the ring_url. Defaults to POST.

  • :hangup_url (String) —

    • The URL that will be notified by Plivo when the call hangs up. Defaults to answer_url.

  • :hangup_method (String) —

    • The method used to call the hangup_url. Defaults to POST.

  • :fallback_url (String) —

    • Invoked by Plivo only if answer_url is unavailable or the XML response is invalid. Should contain a XML response.

  • :fallback_method (String) —

    • The method used to call the fallback_answer_url. Defaults to POST.

  • :caller_name (String) —

    • Caller name to use with the call.

  • :send_digits (String) —

    • Plivo plays DTMF tones when the call is answered. This is useful when dialing a phone number and an extension. Plivo will dial the number, and when the automated system picks up, sends the DTMF tones to connect to the extension. E.g. If you want to dial the 2410 extension after the call is connected, and you want to wait for a few seconds before sending the extension, add a few leading ‘w’ characters. Each ‘w’ character waits 0.5 second before sending a digit. Each ‘W’ character waits 1 second before sending a digit. You can also add the tone duration in ms by appending @duration after the string (default duration is 2000 ms). For example, 1w2w3@1000 See the DTMF API for additional information.

  • :send_on_preanswer (Boolean) —

    • If set to true and send_digits is also set, digits are sent when the call is in preanswer state. Defaults to false.

  • :time_limit (Int) —

    • Schedules the call for hangup at a specified time after the call is answered. Value should be an integer > 0(in seconds).

  • :hangup_on_ring (Int) —

    • Schedules the call for hangup at a specified time after the call starts ringing. Value should be an integer >= 0 (in seconds).

  • :machine_detection (String) —

    • Used to detect if the call has been answered by a machine. The valid values are true and hangup. Default time to analyze is 5000 milliseconds (or 5 seconds). You can change it with the machine_detection_time parameter. Note that no XML is processed during the analysis phase. If a machine is detected during the call and machine_detection is set to true, the Machine parameter will be set to true and will be sent to the answer_url, hangup_url, or any other URL that is invoked by the call. If a machine is detected during the call and machine_detection is set to hangup, the call hangs up immediately and a request is made to the hangup_url with the Machine parameter set to true

  • :machine_detection_time (Int) —

    • Time allotted to analyze if the call has been answered by a machine. It should be an integer >= 2000 and <= 10000 and the unit is ms. The default value is 5000 ms.

  • :machine_detection_url (String) —

    • A URL where machine detection parameters will be sent by Plivo. This parameter should be used to make machine detection asynchronous

  • :machine_detection_method (String) —

    • The HTTP method which will be used by Plivo to request the machine_detection_url. Defaults to POST.

  • :sip_headers- (String) —

    List of SIP headers in the form of ‘key=value’ pairs, separated by commas. E.g. head1=val1,head2=val2,head3=val3,…,headN=valN. The SIP headers are always prefixed with X-PH-. The SIP headers are present for every HTTP request made by the outbound call. Only [A-Z], [a-z] and [0-9] characters are allowed for the SIP headers key and value. Additionally, the ‘%’ character is also allowed for the SIP headers value so that you can encode this value in the URL.

  • :ring_timeout (Int) —

    • Determines the time in seconds the call should ring. If the call is not answered within the ring_timeout value or the default value of 120s, it is canceled.

  • :parent_call_uuid (String) —

    • The call_uuid of the first leg in an ongoing conference call. It is recommended to use this parameter in scenarios where a member who is already present in the conference intends to add new members by initiating outbound API calls. This minimizes the delay in adding a new memeber to the conference.

  • :error_parent_not_found (Boolean) —

    • if set to true and the parent_call_uuid cannot be found, the API request would return an error. If set to false, the outbound call API request will be executed even if the parent_call_uuid is not found. Defaults to false.

Returns:



263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
 
# File 'lib/plivo/resources/calls.rb', line 263

def create(from, to, answer_url, answer_method = 'POST', options = nil)
  valid_param?(:from, from, [String, Symbol, Integer], true)
  valid_param?(:to, to, Array, true)
  to.each do |to_num|
    valid_param?(:to_num, to_num, [Integer, String, Symbol], true)
  end
  valid_param?(:answer_url, answer_url, [String, Symbol], true)
  valid_param?(:answer_method, answer_method, [String, Symbol],
               true, %w[GET POST])

  params = {
    from: from,
    to: to.join('<'),
    answer_url: answer_url,
    answer_method: answer_method
  }

  return perform_create(params) if options.nil?

  perform_create(params.merge(options))
end