Connect

Dial a SIP URI or phone number.

Parameters

Name	Type	Default	Description
confirmOptional	string		A URL that returns SWML to execute when the call is connected.
fromOptional	string	Calling party's caller ID number	Caller ID number. Optional. Can be overwritten on each destination.
headersOptional	object		Custom SIP headers to add to INVITE. Has no effect on calls to phone numbers.
codecsOptional	string	Based on SignalWire settings	Comma-separated string of codecs to offer. Has no effect on calls to phone numbers.
webrtc_mediaOptional	boolean	false	If true, WebRTC media is offered to the SIP endpoint. Has no effect on calls to phone numbers. Optional. Default is false.
session_timeoutOptional	integer	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.
ringbackOptional	string[]	Plays audio from the provider	Array of play URIs to play as ringback tone.
timeoutOptional	integer	60 seconds	Maximum time, in seconds, to wait for an answer.
max_durationOptional	integer	14400 seconds (4 hours)	Maximum duration, in seconds, allowed for the call.
answer_on_bridgeOptional	boolean	false	Delay answer until the B-leg answers.
call_state_urlOptional	string		Webhook url to send call state change notifications to for all legs. Can be overwritten on each destination.
call_state_eventsOptional	string[]	['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.

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

Name	Type	Description
to	string	Single destination to dial. Possible values are a phone number (i.e.: "+15552345678") or sip uri (i.e. "sip:alice@example.com").
serial	object[]	Array of destination objects to dial in order.
parallel	object[]	Array of destination objects to dial simultaneously.
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

Name	Type	Default	Description
toRequired	string		Phone number or SIP URI to dial.
fromOptional	string	Calling party's caller ID number	Caller ID number. Optional.
timeoutOptional	integer	60 seconds	Maximum time, in seconds, to wait for destination to answer.
call_state_urlOptional	string		Webhook url to send call state change notifications to.
call_state_eventsOptional	string[]	['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.

YAML

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"

JSON

{
  "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

YAML

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

JSON

{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "connect": {
          "from": "+15553214321",
          "to": "+15551231234"
        }
      }
    ]
  }
}

Dial a single phone number and go to voicemail on failure

YAML

version: 1.0.0
sections:
  main:
    - connect:
        from: "+15553214321"
        to: "+15551231234"
        result:
          case:
            connected:
              - hangup
          default:
            - execute: "voicemail"
            - hangup

JSON

{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "connect": {
          "from": "+15553214321",
          "to": "+15551231234",
          "result": {
            "case": {
              "connected": [
                "hangup"
              ]
            },
            "default": [
              {
                "execute": "voicemail"
              },
              "hangup"
            ]
          }
        }
      }
    ]
  }
}

Dial numbers in parallel

YAML

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

JSON

{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "connect": {
          "parallel": [
            {
              "to": "+15551231234"
            },
            {
              "to": "+15553214321"
            }
          ]
        }
      }
    ]
  }
}

Dial SIP serially with a timeout

YAML

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

JSON

{
  "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"
            }
          ]
        }
      }
    ]
  }
}