Module: Adhearsion::CallController::Dial

Included in:: Adhearsion::CallController

Defined in:: lib/adhearsion/call_controller/dial.rb

Defined Under Namespace

Classes: Dial, DialStatus, JoinStatus, ParallelConfirmationDial

Instance Method Summary collapse

#dial(to, options = {}) ⇒ DialStatus

Dial one or more third parties and join one to this call.
#dial_and_confirm(to, options = {}) ⇒ Object

Dial one or more third parties and join one to this call after execution of a confirmation controller.

Instance Method Details

#dial(to[String], options = {}) ⇒ `DialStatus` #dial(to[Array], options = {}) ⇒ `DialStatus` #dial(to[Hash], options = {}) ⇒ `DialStatus`

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

Examples:

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

dial "SIP/[email protected]"

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

Make a call using the IAX provider to the PSTN

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

Overloads:

#dial(to[String], options = {}) ⇒ DialStatus
Parameters:
- to (String) —
  
  The target URI to dial. You must specify a properly formatted string that your VoIP platform understands. eg. sip:[email protected], tel:+14044754840, or SIP/foo/1234
- options (Hash) (defaults to: {}) —
  
  see below
#dial(to[Array], options = {}) ⇒ DialStatus
Parameters:
- to (Array<String>) —
  
  Target URIs to dial. Each will be called with the same options simultaneously. The first call answered is joined, the others are hung up.
- options (Hash) (defaults to: {}) —
  
  see below
#dial(to[Hash], options = {}) ⇒ DialStatus
Parameters:
- to (Hash<String => Hash>) —
  
  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.
- options (Hash) (defaults to: {}) —
  
  see below

Parameters:

options (Hash) (defaults to: {}) —

a customizable set of options

Options Hash (options):

:from (String) —

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.
:for (Numeric) —

this option can be thought of best as a timeout. i.e. timeout after :for if no one answers the call
:confirm (CallController) —

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.
:confirm_metadata (Hash) —

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).
:cleanup (CallController) —

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.
:cleanup_metadata (Hash) —

Metadata to set on the cleanup controller before executing it. Defaults to :confirm_metadata if not specified.
:join_options (Hash) —

Options to specify the kind of join operation to perform. See ‘Call#join` for details.
:join_target (Call, String, Hash) —

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.
:pre_join (#call) —

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.
:ringback (Array, #call) —

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.

Returns:

(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 = {}) ⇒ `Object`

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.