***

id: 23836b49-53b5-4b7e-a63e-ae1384bd30bc
title: connect
slug: /reference/connect
description: >-
Connect to a phone number, SIP URI, Call Fabric resource, queue, or WebSocket
stream.
max-toc-depth: 3
----------------

[statuscallbacks]: #statuscallbacks

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

## **Properties**

<ParamField path="connect" type="object" required={true} toc={true}>
  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](#dialing-strategies) below.
</ParamField>

<Indent>
  <ParamField path="connect.answer_on_bridge" type="boolean" default="false" toc={true}>
    Delay answer until the B-leg answers.
  </ParamField>

  <ParamField path="connect.authorization_bearer_token" type="string" toc={true}>
    Bearer token sent as an `Authorization` header during the WebSocket handshake. **Stream destinations only.**
  </ParamField>

  <ParamField path="connect.call_state_events" type="string[]" default="['ended']" toc={true}>
    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](#properties-for-destination).
  </ParamField>

  <ParamField path="connect.call_state_url" type="string" toc={true}>
    Webhook url to send call status change notifications to for all legs. Can be overwritten on each [destination](#properties-for-destination). Authentication can also be set in the url in the format of `username:password@url`. Learn more about [status callbacks][statuscallbacks].
  </ParamField>

  <ParamField path="connect.codec" type="string" default="PCMU" toc={true}>
    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.**
  </ParamField>

  <ParamField path="connect.codecs" type="string" default="Based on SignalWire settings" toc={true}>
    Comma-separated string of codecs to offer. Has no effect on calls to phone numbers.
  </ParamField>

  <ParamField path="connect.confirm" type="string | object[]" toc={true}>
    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
  </ParamField>

  <ParamField path="connect.confirm_timeout" type="integer" default="Inherits from timeout" toc={true}>
    The amount of time, in seconds, to wait for the `confirm` script to execute.
  </ParamField>

  <ParamField path="connect.custom_parameters" type="object" toc={true}>
    Custom key-value pairs sent in the WebSocket start message. **Stream destinations only.**
  </ParamField>

  <ParamField path="connect.encryption" type="string" default="optional" toc={true}>
    The encryption method to use for the call. Possible values: `mandatory`, `optional`, `forbidden`.
  </ParamField>

  <ParamField path="connect.from" type="string" default="Calling party's caller ID number" toc={true}>
    Caller ID number. Optional. Can be overwritten on each [destination](#properties-for-destination).
  </ParamField>

  <ParamField path="connect.headers" type="object[]" toc={true}>
    Custom SIP headers to add to INVITE. Has no effect on calls to phone numbers.
  </ParamField>

  <Indent>
    <ParamField path="headers[].name" type="string" required={true} toc={true}>
      The name of the header.
    </ParamField>

    <ParamField path="headers[].value" type="string" required={true} toc={true}>
      The value of the header.
    </ParamField>
  </Indent>

  <ParamField path="connect.max_duration" type="integer" default="14400 seconds (4 hours)" toc={true}>
    Maximum duration, in seconds, allowed for the call.
  </ParamField>

  <ParamField path="connect.name" type="string" toc={true}>
    Stream name identifier. **Stream destinations only.**
  </ParamField>

  <ParamField path="connect.password" type="string" toc={true}>
    SIP password to use for authentication when dialing a SIP URI. Has no effect on calls to phone numbers.
  </ParamField>

  <ParamField path="connect.realtime" type="boolean" default="false" toc={true}>
    Enable realtime mode for bidirectional audio. **Stream destinations only.**
  </ParamField>

  <ParamField path="connect.result" type="object | object[]" toc={true}>
    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`](/docs/swml/reference/switch#properties) when the `return_value` is a object, and will use the [`cond properties`](/docs/swml/reference/cond#properties) method when the `return_value` is an array.
    See [Variables](#variables) for details.
  </ParamField>

  <ParamField path="connect.ringback" type="string[]" default="Plays audio from the provider" toc={true}>
    Array of `play` URIs to play as ringback tone.
  </ParamField>

  <ParamField path="connect.session_timeout" type="integer" default="Based on SignalWire settings" toc={true}>
    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.
  </ParamField>

  <ParamField path="connect.status_url" type="string" toc={true}>
    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](#connect-status-callbacks). For stream destinations, reports stream status notifications. See [Stream Status Callbacks](#stream-status-callbacks).
  </ParamField>

  <ParamField path="connect.status_url_method" type="string" default="POST" toc={true}>
    HTTP method for the status webhook. Possible values: `GET`, `POST`. **Stream destinations only.**
  </ParamField>

  <ParamField path="connect.timeout" type="integer" default="60 seconds" toc={true}>
    Maximum time, in seconds, to wait for an answer.
  </ParamField>

  <ParamField path="connect.transfer_after_bridge" type="string" toc={true}>
    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:`).
  </ParamField>

  <ParamField path="connect.username" type="string" toc={true}>
    SIP username to use for authentication when dialing a SIP URI. Has no effect on calls to phone numbers.
  </ParamField>

  <ParamField path="connect.webrtc_media" type="boolean" default="false" toc={true}>
    If true, WebRTC media is offered to the SIP endpoint. Has no effect on calls to phone numbers.
  </ParamField>
</Indent>

## **Dialing strategies**

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

<Tabs>
  <Tab title="to">
    <ParamField path="connect.to" type="string" required={true} toc={true}>
      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`)
    </ParamField>
  </Tab>

  <Tab title="serial">
    <ParamField path="connect.serial" type="object[]" required={true} toc={true}>
      Array of [`destination`](#properties-for-destination) objects to dial in order.
      Each destination is tried sequentially — if the first fails, the next is attempted.
    </ParamField>
  </Tab>

  <Tab title="parallel">
    <ParamField path="connect.parallel" type="object[]" required={true} toc={true}>
      Array of [`destination`](#properties-for-destination) objects to dial simultaneously.
      The first destination to answer is bridged and the rest are cancelled.
    </ParamField>
  </Tab>

  <Tab title="serial_parallel">
    <ParamField path="connect.serial_parallel" type="object[][]" required={true} toc={true}>
      Array of arrays combining both strategies. Each inner array is a group of destinations dialed simultaneously.
      The outer array attempts each group in order — if no destination answers in the first group, the next group is tried.
    </ParamField>
  </Tab>
</Tabs>

## **Properties for `destination`**

<ParamField path="connect.to" type="string" required={true} toc={true}>
  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`)
</ParamField>

<ParamField path="connect.call_state_events" type="string[]" default="['ended']" toc={true}>
  An array of call state event names to be notified about. Allowed event names are `created`, `ringing`, `answered`, and `ended`.
</ParamField>

<ParamField path="connect.call_state_url" type="string" toc={true}>
  Webhook url to send call state change notifications to. Authentication can also be set in the url in the format of `username:password@url`.
</ParamField>

<ParamField path="connect.confirm" type="string | object[]" toc={true}>
  Confirmation script to execute on this destination when answered. Overrides the top-level `confirm`. Applies to phone, SIP, and Call Fabric destinations.
</ParamField>

<ParamField path="connect.confirm_timeout" type="integer" toc={true}>
  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.
</ParamField>

<ParamField path="connect.encryption" type="string" toc={true}>
  Media encryption (SRTP) for this destination. Overrides the top-level `encryption`. **Applies to SIP destinations only.**
  Possible values: `mandatory`, `optional`, `forbidden`.
</ParamField>

<ParamField path="connect.from" type="string" default="Calling party's caller ID number" toc={true}>
  Caller ID number. Optional.
</ParamField>

<ParamField path="connect.timeout" type="integer" default="60 seconds" toc={true}>
  Maximum time, in seconds, to wait for destination to answer.
</ParamField>

## **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`).

<ParamField path="event_type" type="string" toc={true}>
  The type of event. Always `calling.call.state` for this method.
</ParamField>

<ParamField path="event_channel" type="string" toc={true}>
  The channel for the event, includes the SWML session ID.
</ParamField>

<ParamField path="timestamp" type="number" toc={true}>
  Unix timestamp (float) when the event was generated.
</ParamField>

<ParamField path="project_id" type="string" toc={true}>
  The project ID associated with the call.
</ParamField>

<ParamField path="space_id" type="string" toc={true}>
  The Space ID associated with the call.
</ParamField>

<ParamField path="params" type="object" toc={true}>
  An object containing call state parameters.
</ParamField>

<Indent>
  <ParamField path="params.call_id" type="string" toc={true}>
    The call ID.
  </ParamField>

  <ParamField path="params.node_id" type="string" toc={true}>
    The node handling the call.
  </ParamField>

  <ParamField path="params.call_state" type="string" toc={true}>
    The current call state. **Valid values:** `created`, `ringing`, `answered`, `ended`.
  </ParamField>

  <ParamField path="params.direction" type="string" toc={true}>
    The direction of the call leg (e.g., `outbound`).
  </ParamField>

  <ParamField path="params.device" type="object" toc={true}>
    Details about the device involved in the call.
  </ParamField>

  <Indent>
    <ParamField path="device.type" type="string" toc={true}>
      The type of device (e.g., `phone`, `sip`).
    </ParamField>

    <ParamField path="device.params.from_number" type="string" toc={true}>
      The originating phone number.
    </ParamField>

    <ParamField path="device.params.to_number" type="string" toc={true}>
      The destination phone number.
    </ParamField>
  </Indent>

  <ParamField path="params.end_reason" type="string" toc={true}>
    The reason the call ended (only present when `call_state` is `ended`). **Valid values:** `hangup`, `busy`, `no_answer`, `cancel`, `declined`, `error`.
  </ParamField>
</Indent>

### Raw JSON example

```json
{
  "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.

<ParamField path="event_type" type="string" toc={true}>
  The type of event. Always `calling.call.connect` for connect status events.
</ParamField>

<ParamField path="event_channel" type="string" toc={true}>
  The channel for the event, includes the SWML session ID.
</ParamField>

<ParamField path="timestamp" type="number" toc={true}>
  Unix timestamp (float) when the event was generated.
</ParamField>

<ParamField path="project_id" type="string" toc={true}>
  The project ID associated with the call.
</ParamField>

<ParamField path="space_id" type="string" toc={true}>
  The Space ID associated with the call.
</ParamField>

<ParamField path="params" type="object" toc={true}>
  An object containing connect status parameters.
</ParamField>

<Indent>
  <ParamField path="params.call_id" type="string" toc={true}>
    The call ID.
  </ParamField>

  <ParamField path="params.node_id" type="string" toc={true}>
    The node handling the call.
  </ParamField>

  <ParamField path="params.segment_id" type="string" toc={true}>
    The segment ID for the call leg. Present when a segment ID has been assigned.
  </ParamField>

  <ParamField path="params.tag" type="string" toc={true}>
    The tag associated with the call. Present when a tag has been set.
  </ParamField>

  <ParamField path="params.connect_state" type="string" toc={true}>
    The current connect state. Possible values:

    * `connecting` — Attempting to connect
    * `connected` — Successfully connected
    * `failed` — Connection failed
    * `disconnected` — Connection ended
  </ParamField>

  <ParamField path="params.failed_reason" type="string" toc={true}>
    The reason the connection failed. Only present when `connect_state` is `failed`.
  </ParamField>

  <ParamField path="params.peer" type="object" toc={true}>
    Details about the connected peer. Present when `connect_state` is `connected`.
  </ParamField>

  <Indent>
    <ParamField path="peer.call_id" type="string" toc={true}>
      The peer's call ID.
    </ParamField>

    <ParamField path="peer.tag" type="string" toc={true}>
      The tag associated with the peer call. Present when a tag has been set on the peer.
    </ParamField>

    <ParamField path="peer.node_id" type="string" toc={true}>
      The node ID of the node handling this call.
    </ParamField>

    <ParamField path="peer.queue_id" type="string" toc={true}>
      The queue ID when the peer was connected via a queue. Only present for queue-based connections.
    </ParamField>

    <ParamField path="peer.queue_name" type="string" toc={true}>
      The queue name when the peer was connected via a queue. Only present for queue-based connections.
    </ParamField>

    <ParamField path="peer.device" type="object" toc={true}>
      Details about the peer's device.
    </ParamField>
  </Indent>
</Indent>

### Raw JSON example

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

```json
{
  "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.

<ParamField path="event_type" type="string" toc={true}>
  The type of event. Always `calling.call.stream` for stream status events.
</ParamField>

<ParamField path="event_channel" type="string" toc={true}>
  The channel for the event, includes the SWML session ID.
</ParamField>

<ParamField path="timestamp" type="number" toc={true}>
  Unix timestamp (float) when the event was generated.
</ParamField>

<ParamField path="project_id" type="string" toc={true}>
  The project ID associated with the call.
</ParamField>

<ParamField path="space_id" type="string" toc={true}>
  The Space ID associated with the call.
</ParamField>

<ParamField path="params" type="object" toc={true}>
  An object containing stream status parameters.
</ParamField>

<Indent>
  <ParamField path="params.control_id" type="string" toc={true}>
    The control identifier for the stream.
  </ParamField>

  <ParamField path="params.state" type="string" toc={true}>
    The current stream state. Possible values:

    * `streaming` — Stream is active
    * `finished` — Stream has ended
  </ParamField>

  <ParamField path="params.url" type="string" toc={true}>
    The WebSocket URL of the stream.
  </ParamField>

  <ParamField path="params.name" type="string" toc={true}>
    The stream name, if one was provided.
  </ParamField>
</Indent>

### Raw JSON example

```json
{
  "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](/docs/platform/resources) and [Addresses](/docs/platform/addresses).

<CodeBlocks>
  <CodeBlock title="YAML">
    ```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
    ```
  </CodeBlock>

  <CodeBlock title="JSON">
    ```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"
            }
          }
        ]
      }
    }
    ```
  </CodeBlock>
</CodeBlocks>

### Dial a single phone number

<CodeBlocks>
  <CodeBlock title="YAML">
    ```yaml
    version: 1.0.0
    sections:
      main:
        - connect:
            from: "+15553214321"
            to: "+15551231234"
    ```
  </CodeBlock>

  <CodeBlock title="JSON">
    ```json
    {
      "version": "1.0.0",
      "sections": {
        "main": [
          {
            "connect": {
              "from": "+15553214321",
              "to": "+15551231234"
            }
          }
        ]
      }
    }
    ```
  </CodeBlock>
</CodeBlocks>

### Dial numbers in parallel

<CodeBlocks>
  <CodeBlock title="YAML">
    ```yaml
    version: 1.0.0
    sections:
      main:
        - connect:
            parallel:
              - to: "+15551231234"
              - to: "+15553214321"
    ```
  </CodeBlock>

  <CodeBlock title="JSON">
    ```json
    {
      "version": "1.0.0",
      "sections": {
        "main": [
          {
            "connect": {
              "parallel": [
                {
                  "to": "+15551231234"
                },
                {
                  "to": "+15553214321"
                }
              ]
            }
          }
        ]
      }
    }
    ```
  </CodeBlock>
</CodeBlocks>

### Dial SIP serially with a timeout

<CodeBlocks>
  <CodeBlock title="YAML">
    ```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
    ```
  </CodeBlock>

  <CodeBlock title="JSON">
    ```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"
                }
              ]
            }
          }
        ]
      }
    }
    ```
  </CodeBlock>
</CodeBlocks>

### Connect to a queue with transfer after bridge

<CodeBlocks>
  <CodeBlock title="YAML">
    ```yaml
    version: 1.0.0
    sections:
      main:
        - connect:
            to: "queue:support"
            transfer_after_bridge: "https://example.com/post-call-swml"
    ```
  </CodeBlock>

  <CodeBlock title="JSON">
    ```json
    {
      "version": "1.0.0",
      "sections": {
        "main": [
          {
            "connect": {
              "to": "queue:support",
              "transfer_after_bridge": "https://example.com/post-call-swml"
            }
          }
        ]
      }
    }
    ```
  </CodeBlock>
</CodeBlocks>

### Connect to a WebSocket stream

<CodeBlocks>
  <CodeBlock title="YAML">
    ```yaml
    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"
    ```
  </CodeBlock>

  <CodeBlock title="JSON">
    ```json
    {
      "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"
            }
          }
        ]
      }
    }
    ```
  </CodeBlock>
</CodeBlocks>