Connect

Connect to a phone number, SIP URI, Call Fabric resource, queue, or WebSocket stream.

Properties

objectRequired

Connects the current call to a destination — a phone number, SIP URI, Call Fabric Resource, queue, or WebSocket stream. The connection mode is determined by which property you use. See dialing strategies below.

connect.answer_on_bridge

booleanDefaults to false

Delay answer until the B-leg answers.

connect.authorization_bearer_token

string

Bearer token sent as an Authorization header during the WebSocket handshake. Stream destinations only.

connect.call_state_events

string[]Defaults to ['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. Learn more about status callbacks.

connect.codec

stringDefaults to PCMU

Audio codec for the stream. Supported values: PCMU, PCMA, G722, L16. Codec can include rate and ptime modifiers (e.g., PCMU@40i, L16@24000h@40i). Stream destinations only.

connect.codecs

stringDefaults to Based on SignalWire settings

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

connect.confirm

string | object[]

Confirmation to execute when the call is connected. Can be either:

A URL (string) that returns a SWML document
An array of SWML methods to execute inline

connect.confirm_timeout

integerDefaults to Inherits from timeout

The amount of time, in seconds, to wait for the confirm script to execute.

connect.custom_parameters

object

Custom key-value pairs sent in the WebSocket start message. Stream destinations only.

connect.encryption

stringDefaults to optional

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

connect.from

stringDefaults to 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.

headers[].name

stringRequired

The name of the header.

headers[].value

stringRequired

The value of the header.

connect.max_duration

integerDefaults to 14400 seconds (4 hours)

Maximum duration, in seconds, allowed for the call.

connect.name

string

Stream name identifier. Stream destinations only.

connect.password

string

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

connect.realtime

booleanDefaults to false

Enable realtime mode for bidirectional audio. Stream destinations only.

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 properties when the return_value is a object, and will use the cond properties method when the return_value is an array. See Variables for details.

connect.ringback

string[]Defaults to Plays audio from the provider

Array of play URIs to play as ringback tone.

connect.session_timeout

integerDefaults to 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.status_url

string

Webhook URL to deliver status events. For phone, SIP, and Call Fabric destinations, reports the connect operation status (connecting, connected, failed, disconnected). See Connect Status Callbacks. For stream destinations, reports stream status notifications. See Stream Status Callbacks.

connect.status_url_method

stringDefaults to POST

HTTP method for the status webhook. Possible values: GET, POST. Stream destinations only.

connect.timeout

integerDefaults to 60 seconds

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

connect.transfer_after_bridge

string

SWML to execute after the bridge completes. This defines what should happen after the call is connected and the bridge ends.

Can be either:

A URL (http or https) that returns a SWML document
An inline SWML document (as a JSON string)

Required when connecting to a queue (when to starts with queue:).

connect.username

string

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

connect.webrtc_media

booleanDefaults to false

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

Dialing strategies

The connect object supports four mutually exclusive dialing strategies. Use exactly one of the following properties:

to

serial

parallel

serial_parallel

connect.to

stringRequired

Single destination to dial. The value format determines the destination type:

Phone number — E.164 format (e.g., +15552345678)
SIP URI — (e.g., sip:alice@example.com)
Call Fabric Resource — address path (e.g., /public/test_room)
Queue — queue: prefix (e.g., queue:support)
WebSocket stream — stream:wss:// prefix (e.g., stream:wss://example.com/audio)

Properties for `destination`

connect.to

stringRequired

Destination to dial. Can be:

Phone number in E.164 format (e.g., +15552345678)
SIP URI (e.g., sip:alice@example.com)
Call Fabric Resource address (e.g., /public/test_room)
Queue (e.g., queue:support)
WebSocket stream (e.g., stream:wss://example.com/audio)

connect.call_state_events

string[]Defaults to ['ended']

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

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.confirm

string | object[]

Confirmation script to execute on this destination when answered. Overrides the top-level confirm. Applies to phone, SIP, and Call Fabric destinations.

connect.confirm_timeout

integer

Seconds to wait for the confirm script to execute on this destination. Overrides the top-level confirm_timeout. Applies to phone, SIP, and Call Fabric destinations.

connect.encryption

string

Media encryption (SRTP) for this destination. Overrides the top-level encryption. Applies to SIP destinations only. Possible values: mandatory, optional, forbidden.

connect.from

stringDefaults to Calling party's caller ID number

Caller ID number. Optional.

connect.timeout

integerDefaults to 60 seconds

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

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.

StatusCallbacks

A POST request will be sent to call_state_url with a JSON payload when the call state changes. Only events listed in call_state_events will be sent (default: ended).

event_type

string

The type of event. Always calling.call.state for this method.

event_channel

string

The channel for the event, includes the SWML session ID.

timestamp

number

Unix timestamp (float) when the event was generated.

project_id

string

The project ID associated with the call.

space_id

string

The Space ID associated with the call.

params

object

An object containing call state parameters.

params.call_id

string

The call ID.

params.node_id

string

The node handling the call.

params.call_state

string

The current call state. Valid values:created, ringing, answered, ended.

params.direction

string

The direction of the call leg (e.g., outbound).

params.device

object

Details about the device involved in the call.

device.type

string

The type of device (e.g., phone, sip).

device.params.from_number

string

The originating phone number.

device.params.to_number

string

The destination phone number.

params.end_reason

string

The reason the call ended (only present when call_state is ended). Valid values:hangup, busy, no_answer, cancel, declined, error.

Raw JSON example

{

  "event_type": "calling.call.state",

  "event_channel": "swml:xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",

  "timestamp": 1640000000.123,

  "project_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",

  "space_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",

  "params": {

    "call_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",

    "node_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",

    "call_state": "answered",

    "direction": "outbound",

    "device": {

      "type": "phone",

      "params": {

        "from_number": "+15551231234",

        "to_number": "+15553214321"

      }

    },

    "end_reason": null

  }

}

Connect Status Callbacks

When you provide a top-level status_url, SignalWire sends HTTP POST requests reporting the overall status of the connect operation.

event_type

string

The type of event. Always calling.call.connect for connect status events.

event_channel

string

The channel for the event, includes the SWML session ID.

timestamp

number

Unix timestamp (float) when the event was generated.

project_id

string

The project ID associated with the call.

space_id

string

The Space ID associated with the call.

params

object

An object containing connect status parameters.

params.call_id

string

The call ID.

params.node_id

string

The node handling the call.

params.segment_id

string

The segment ID for the call leg. Present when a segment ID has been assigned.

params.tag

string

The tag associated with the call. Present when a tag has been set.

params.connect_state

string

The current connect state. Possible values:

connecting — Attempting to connect
connected — Successfully connected
failed — Connection failed
disconnected — Connection ended

params.failed_reason

string

The reason the connection failed. Only present when connect_state is failed.

params.peer

object

Details about the connected peer. Present when connect_state is connected.

peer.call_id

string

The peer’s call ID.

peer.tag

string

The tag associated with the peer call. Present when a tag has been set on the peer.

peer.node_id

string

The node ID of the node handling this call.

peer.queue_id

string

The queue ID when the peer was connected via a queue. Only present for queue-based connections.

peer.queue_name

string

The queue name when the peer was connected via a queue. Only present for queue-based connections.

peer.device

object

Details about the peer’s device.

Raw JSON example

{

  "event_type": "calling.call.connect",

  "event_channel": "swml:xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",

  "timestamp": 1640000000.123,

  "project_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",

  "space_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",

  "params": {

    "call_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",

    "node_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",

    "connect_state": "connected",

    "peer": {

      "call_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",

      "node_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",

      "device": {

        "type": "phone",

        "params": {

          "from_number": "+15551231234",

          "to_number": "+15553214321"

        }

      }

    }

  }

}

Failed state example

{

  "event_type": "calling.call.connect",

  "event_channel": "swml:xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",

  "timestamp": 1640000000.123,

  "project_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",

  "space_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",

  "params": {

    "call_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",

    "node_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",

    "connect_state": "failed",

    "failed_reason": "no_answer"

  }

}

Stream Status Callbacks

When connecting to a WebSocket stream destination with a status_url, SignalWire sends HTTP requests reporting the stream status.

event_type

string

The type of event. Always calling.call.stream for stream status events.

event_channel

string

The channel for the event, includes the SWML session ID.

timestamp

number

Unix timestamp (float) when the event was generated.

project_id

string

The project ID associated with the call.

space_id

string

The Space ID associated with the call.

params

object

An object containing stream status parameters.

params.control_id

string

The control identifier for the stream.

params.state

string

The current stream state. Possible values:

streaming — Stream is active
finished — Stream has ended

params.url

string

The WebSocket URL of the stream.

params.name

string

The stream name, if one was provided.

Raw JSON example

{

  "event_type": "calling.call.stream",

  "event_channel": "swml:xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",

  "timestamp": 1640000000.123,

  "project_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",

  "space_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",

  "params": {

    "control_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",

    "state": "streaming",

    "url": "wss://example.com/audio",

    "name": "my-stream"

  }

}

Examples

Use `connect` with Call Fabric

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

Learn more about Resources and Addresses.

YAMLJSON

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

YAMLJSON

version: 1.0.0

sections:

  main:

    - connect:

        from: "+15553214321"

        to: "+15551231234"

Dial numbers in parallel

YAMLJSON

version: 1.0.0

sections:

  main:

    - connect:

        parallel:

          - to: "+15551231234"

          - to: "+15553214321"

Dial SIP serially with a timeout

YAMLJSON

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

Connect to a queue with transfer after bridge

YAMLJSON

version: 1.0.0

sections:

  main:

    - connect:

        to: "queue:support"

        transfer_after_bridge: "https://example.com/post-call-swml"

Connect to a WebSocket stream

YAMLJSON

version: 1.0.0

sections:

  main:

    - answer: {}

    - connect:

        to: "stream:wss://example.com/audio"

        codec: PCMU

        realtime: true

        name: my-stream

        status_url: "https://example.com/stream-status"

Properties ​

connect ​

connect.answer_on_bridge ​

connect.authorization_bearer_token ​

connect.call_state_events ​

connect.call_state_url ​

connect.codec ​

connect.codecs ​

connect.confirm ​

connect.confirm_timeout ​

connect.custom_parameters ​

connect.encryption ​

connect.from ​

connect.headers ​

headers[].name ​

headers[].value ​

connect.max_duration ​

connect.name ​

connect.password ​

connect.realtime ​

connect.result ​

connect.ringback ​

connect.session_timeout ​

connect.status_url ​

connect.status_url_method ​

connect.timeout ​

connect.transfer_after_bridge ​

connect.username ​

connect.webrtc_media ​

Dialing strategies ​

to ​

serial ​

parallel ​

serial_parallel ​

connect.to ​

Properties for destination ​

connect.to ​

connect.call_state_events ​

connect.call_state_url ​

connect.confirm ​

connect.confirm_timeout ​

connect.encryption ​

connect.from ​

connect.timeout ​

Variables ​

StatusCallbacks ​

event_type ​

event_channel ​

timestamp ​

project_id ​

space_id ​

params ​

params.call_id ​

params.node_id ​

params.call_state ​

params.direction ​

params.device ​

device.type ​

device.params.from_number ​

device.params.to_number ​

params.end_reason ​

Raw JSON example ​

Connect Status Callbacks ​

event_type ​

event_channel ​

timestamp ​

project_id ​

space_id ​

params ​

params.call_id ​

params.node_id ​

params.segment_id ​

params.tag ​

params.connect_state ​

params.failed_reason ​

params.peer ​

peer.call_id ​

peer.tag ​

peer.node_id ​

peer.queue_id ​

Properties

connect

connect.answer_on_bridge

connect.authorization_bearer_token

connect.call_state_events

connect.call_state_url

connect.codec

connect.codecs

connect.confirm

connect.confirm_timeout

connect.custom_parameters

connect.encryption

connect.from

connect.headers

headers[].name

headers[].value

connect.max_duration

connect.name

connect.password

connect.realtime

connect.result

connect.ringback

connect.session_timeout

connect.status_url

connect.status_url_method

connect.timeout

connect.transfer_after_bridge

connect.username

connect.webrtc_media

Dialing strategies

to

serial

parallel

serial_parallel

connect.to

Properties for `destination`

connect.to

connect.call_state_events

connect.call_state_url

connect.confirm

connect.confirm_timeout

connect.encryption

connect.from

connect.timeout

Variables

StatusCallbacks

event_type

event_channel

timestamp

project_id

space_id

params

params.call_id

params.node_id

params.call_state

params.direction

params.device

device.type

device.params.from_number

device.params.to_number

params.end_reason

Raw JSON example

Connect Status Callbacks

event_type

event_channel

timestamp

project_id

space_id

params

params.call_id

params.node_id

params.segment_id

params.tag

params.connect_state

params.failed_reason

params.peer

peer.call_id

peer.tag

peer.node_id

peer.queue_id