Method: Adhearsion::CallController::Dial#dial

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

#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/19095551001@my.sip.voip.terminator.us"

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:foo@bar.com, 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)

    Confirmation controller to execute. 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.

  • :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).

  • :apology (CallController)

    controller to execute on calls which lose the race to complete confirmation before they are hung up

  • :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



62
63
64
65
66
67
68
69
70
71
# File 'lib/adhearsion/call_controller/dial.rb', line 62

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