module Adhearsion::CallController::Dial

Public Instance Methods

dial(to, options = {}) click to toggle source

Dial one or more third parties and join one to this call

@overload dial(to, options = {})

@param [String] to The target URI to dial.
  You must specify a properly formatted string that your VoIP platform understands.
  eg. sip:foo@bar.com, tel:+14044754840, or SIP/foo/1234
@param [Hash] options see below

@overload dial(to, options = {})

@param [Array<String>] to Target URIs to dial.
  Each will be called with the same options simultaneously.
  The first call answered is joined, the others are hung up.
@param [Hash] options see below

@overload dial(to, options = {})

@param [Hash<String => Hash>] to Target URIs to dial, mapped to their per-target options overrides.
  Each will be called with the same options simultaneously.
  The first call answered is joined, the others are hung up.
  Each calls options are deep-merged with the global options hash.
@param [Hash] options see below

@option options [String] :from the caller id to be used when the call is placed. It is advised you properly adhere to the

policy of VoIP termination providers with respect to caller id values. Defaults to the caller ID of the dialing call, so for normal bridging scenarios, you do not need to set this.

@option options [Numeric] :for this option can be thought of best as a timeout.

i.e. timeout after :for if no one answers the call

@option options [CallController] :confirm the controller to execute on the first outbound call to be answered, to give an opportunity to screen the call. The calls will be joined if the outbound call is still active after this controller completes. @option options [Hash] :confirm_metadata Metadata to set on the confirmation controller before executing it. This is shared between all calls if dialing multiple endpoints; if you care about it being mutated, you should provide an immutable value (using eg github.com/harukizaemon/hamster).

@option options [CallController] :cleanup The controller to execute on each call being cleaned up. This can be used, for instance, to notify that the call is being terminated. Calls are terminated right after this controller completes execution. If this is not specified, calls are silently terminated during cleanup. @option options [Hash] :cleanup_metadata Metadata to set on the cleanup controller before executing it. Defaults to :confirm_metadata if not specified.

@option options [Hash] :join_options Options to specify the kind of join operation to perform. See `Call#join` for details. @option options [Call, String, Hash] :join_target the target to join to. May be a Call object, a call ID (String, Hash) or a mixer name (Hash). See `Call#join` for details.

@option options [#call] :pre_join A callback to be executed immediately prior to answering and joining a successful call. Is called with a single parameter which is the outbound call being joined.

@option options [Array, call] :ringback A collection of audio (see play for acceptable values) to render as a replacement for ringback. If a callback is passed, it will be used to start ringback, and must return something that responds to stop! to stop it.

@example Make a call to the PSTN using my SIP provider for VoIP termination

dial "SIP/19095551001@my.sip.voip.terminator.us"

@example Make 3 simulataneous calls to the SIP extensions, try for 15 seconds and use the callerid for this call specified by the variable my_callerid

dial %w{SIP/jay-desk-650 SIP/jay-desk-601 SIP/jay-desk-601-2}, :for => 15.seconds, :from => my_callerid

@example Make a call using the IAX provider to the PSTN

dial "IAX2/my.id@voipjet/19095551234", :from => "John Doe <9095551234>"

@return [DialStatus] the status of the dial operation

# File lib/adhearsion/call_controller/dial.rb, line 60
def dial(to, options = {})
  dial = Dial.new to, options, call
  dial.run(self)
  dial.await_completion
  dial.terminate_ringback
  dial.cleanup_calls
  dial.status
ensure
  catching_standard_errors { dial.delete_logger if dial }
end
dial_and_confirm(to, options = {}) click to toggle source

Dial one or more third parties and join one to this call after execution of a confirmation controller. Confirmation will be attempted on all answered calls, and calls will be allowed to progress through confirmation in parallel. The first to complete confirmation will be joined to the A-leg, with the others being hung up.

@option options [CallController] :apology controller to execute on calls which lose the race to complete confirmation before they are hung up

@see dial

# File lib/adhearsion/call_controller/dial.rb, line 77
def dial_and_confirm(to, options = {})
  dial = ParallelConfirmationDial.new to, options, call
  dial.run(self)
  dial.await_completion
  dial.terminate_ringback
  dial.cleanup_calls
  dial.status
ensure
  catching_standard_errors { dial.delete_logger if dial }
end