Connect

Dial a SIP URI or phone number.

Parameters

Name	Type	Required?	Default	Description
from	string	Optional	Calling party's caller ID number	Caller ID number. Optional. Can be overwritten on each destination.
headers	object	Optional		Custom SIP headers to add to INVITE. Has no effect on calls to phone numbers.
codecs	string	Optional	Based on SignalWire settings	Comma-separated string of codecs to offer. Has no effect on calls to phone numbers.
webrtc_media	boolean	Optional	false	If true, WebRTC media is offered to the SIP endpoint. Has no effect on calls to phone numbers. Optional. Default is false.
session_timeout	integer	Optional	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.
ringback	string[]	Optional	Plays audio from the provider	Array of play URIs to play as ringback tone.
timeout	integer	Optional	60 seconds	Maximum time, in seconds, to wait for an answer.
max_duration	integer	Optional	14400 seconds (4 hours)	Maximum duration, in seconds, allowed for the call.
answer_on_bridge	boolean	Optional	false	Delay answer until the B-leg answers.
call_state_url	string	Optional		Webhook url to send call state change notifications to for all legs. Can be overwritten on each destination.
call_state_events	string[]	Optional	['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	Required?	Default	Description
to	string	Required		Phone number or SIP URI to dial.
from	string	Optional	Calling party's caller ID number	Caller ID number. Optional.
timeout	integer	Optional	60 seconds	Maximum time, in seconds, to wait for destination to answer.
call_state_url	string	Optional		Webhook url to send call state change notifications to.
call_state_events	string[]	Optional	['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"
            }
          ]
        }
      }
    ]
  }
}