connect

Dial a SIP URI or phone number.

Name	Type	Default	Description
connectRequired	object	-	An object that contains the connect parameters.

connect 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. The object accepts headers parameters
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. Authentication can also be set in the url in the format of username:password@url.
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.
resultOptional	object | object[]	-	Action to take based on the result of the call. This will run once the peer leg of the call has ended. See Variables for details. 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.

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

Name	Type	Default	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. Authentication can also be set in the url in the format of username:password@url.
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

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

JSON

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

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