connect

Dial a SIP URI or phone number.

Parameters

Name	Type	Description
from	string	Caller ID number. Optional. Default is calling party caller ID number. Can be overwritten on each destination.
headers	object	Custom SIP headers to add to INVITE. Has no effect on calls to phone numbers. Optional. Default is not set.
codecs	string	Comma-separated string of codecs to offer. Has no effect on calls to phone numbers. Optional. Default is set based on SignalWire settings.
webrtc_media	boolean	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	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. Optional. Default is set based on SignalWire settings.
ringback	string[]	Array of play URIs to play as ringback tone. Optional. Default will play audio from the provider.
timeout	integer	Maximum time, in seconds, to wait for an answer. Optional. Default is 60.
max_duration	integer	Maximum duration, in seconds, allowed for the call. Optional. Default is 14400 (4 hours).
answer_on_bridge	boolean	Delay answer until the B-leg answers. Optional. Default is false.
call_state_url	string	Webhook url to send call state change notifications to for all legs. Optional. Default is not set. Can be overwritten on each destination.
call_state_events	string[]	An array of call state event names to be notified about. Allowed event names are created, ringing, answered, and ended. Optional. Default is ["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
serial_parallel	object[][]	Array of arrays. Inner arrays contain destination objects to dial simultaneously. Outer array attempts each parallel group in order.
serial	object[]	Array of destination objects to dial in order.
parallel	object[]	Array of destination objects to dial simultaneously.
to	string	Single destination to dial. Possible values are a phone number (i.e.: "+15552345678") or sip uri (i.e. "sip:alice@example.com").

Parameters for destination

Name	Type	Description
to	string	Phone number or SIP URI to dial. Required.
from	string	Caller ID number. Optional. Default is calling party caller ID number.
timeout	integer	Maximum time, in seconds, to wait for destination to answer. Optional. Default is 60.
call_state_url	string	Webhook url to send call state change notifications to. Optional. Default is not set.
call_state_events	string[]	An array of call state event names to be notified about. Allowed event names are created, ringing, answered, and ended. Optional. Default is ["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

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" },
            { "codecs": "PCMU", "to": "sip:bob@example.com" }
          ]
        }
      }
    ]
  }
}

---