Skip to main content
Get startedGuidesTechnical Reference

connect

Dial a SIP URI or phone number.

connect
objectrequired

An object that contains the connect parameters.

connect Parameters​

connect.answer_on_bridge
boolean
Default: false

Delay answer until the B-leg answers.

connect.call_state_events
string[]
Default: ['ended']

An array of call state event names to be notified about. Allowed event names are created, ringing, answered, and ended. Can be overwritten on each destination.

connect.call_state_url
string

Webhook url to send call status change notifications to for all legs. Can be overwritten on each destination. Authentication can also be set in the url in the format of username:password@url.

connect.codecs
string
Default: Based on SignalWire settings

Comma-separated string of codecs to offer. Has no effect on calls to phone numbers.

connect.confirm
string

A URL that returns SWML to execute when the call is connected.

connect.confirm_timeout
integer
Default: 60 seconds

The amount of time, in seconds, to wait for the confirm URL to return a response.

connect.encryption
string
Default: optional

The encryption method to use for the call.
Possible values: mandatory, optional, forbidden.

connect.from
string
Default: Calling party's caller ID number

Caller ID number. Optional. Can be overwritten on each destination.

connect.headers
object[]

Custom SIP headers to add to INVITE. Has no effect on calls to phone numbers. The object accepts headers parameters.

See headers for details.

connect.max_duration
integer
Default: 14400 seconds (4 hours)

Maximum duration, in seconds, allowed for the call.

connect.result
object | object[]

Action to take based on the result of the call. This will run once the peer leg of the call has ended.

Will use the switch method parameters when the return_value is a object, and will use the cond method parameters method when the return_value is an array.
See Variables for details.

connect.ringback
string[]
Default: Plays audio from the provider

Array of play URIs to play as ringback tone.

connect.session_timeout
integer
Default: Based on SignalWire settings

Time, in seconds, to set the SIP Session-Expires header in INVITE. Must be a positive, non-zero number. Has no effect on calls to phone numbers.

connect.timeout
integer
Default: 60 seconds

Maximum time, in seconds, to wait for an answer.

connect.username
string

SIP username to use for authentication when dialing a SIP URI. Has no effect on calls to phone numbers.

connect.password
string

SIP password to use for authentication when dialing a SIP URI. Has no effect on calls to phone numbers.

connect.webrtc_media
boolean
Default: false

If true, WebRTC media is offered to the SIP endpoint. Has no effect on calls to phone numbers. Optional. Default is false.

In addition, you are required to specify one and only one of the following dialing parameters:

connect.to
string

Single destination to dial. Possible values are a phone number (i.e.: "+15552345678") or sip uri (i.e. "sip:alice@example.com").

connect.serial
object[]

Array of destination objects to dial in order.

connect.parallel
object[]

Array of destination objects to dial simultaneously.

connect.serial_parallel
object[][]

Array of arrays. Inner arrays contain destination objects to dial simultaneously. Outer array attempts each parallel group in order.

Parameters for destination​

connect.to
stringrequired

Phone number or SIP URI to dial.

connect.from
string
Default: Calling party's caller ID number

Caller ID number. Optional.

connect.timeout
integer
Default: 60 seconds

Maximum time, in seconds, to wait for destination to answer.

connect.call_state_url
string

Webhook url to send call state change notifications to. Authentication can also be set in the url in the format of username:password@url.

connect.call_state_events
string[]
Default: ['ended']

An array of call state event names to be notified about. Allowed event names are created, ringing, answered, and ended.

Variables​

Set by the method:

  • connect_result: (out) connected | failed.
  • connect_failed_reason: (out) Detailed reason for failure.
  • return_value: (out) Same value as connect_result.

Examples​

Use connect with Call Fabric​

Use a Call Fabric Resource with the connect method by simply including the Resource Address.

Learn more by reading our Introduction to Call Fabric or the guide to Managing Resources.

version: 1.0.0
sections:
  main:
    - answer: {}
    - play:
        volume: 10
        urls:
          - 'silence:1.0'
          - 'say:Hello, connecting to a fabric Resource that is a room'
    - connect:
        to: /public/test_room

Dial a single phone number​

version: 1.0.0
sections:
  main:
    - connect:
        from: "+15553214321"
        to: "+15551231234"

Dial numbers in parallel​

version: 1.0.0
sections:
  main:
    - connect:
        parallel:
          - to: "+15551231234"
          - to: "+15553214321"

Dial SIP serially with a timeout​

version: 1.0.0
sections:
  main:
    - connect:
        timeout: 20
        serial:
          - from: "sip:chris@example.com"
            to: "sip:alice@example.com"
          - to: "sip:bob@example.com"
            codecs: PCMU