Calling

connect

View as MarkdownOpen in Claude

Connect to a phone number, SIP URI, Resource Address, queue, or WebSocket stream.

Properties

connect
objectRequired

Connects the current call to a destination — a phone number, SIP URI, Resource Address, queue, or WebSocket stream. The object shape depends on the connection type — select a tab below to see the full property schema for each mode.

Dial a single destination directly using the to property.

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)
  • Resource Address — 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)
connect.answer_on_bridge
booleanDefaults to false

Delay answer until the B-leg answers.

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 status change notifications to. Authentication can also be set in the url in the format of username:password@url. Learn more about status callbacks.

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

connect.from_name
string

The caller ID name shown to the person you’re calling, displayed alongside the from number (sometimes called CNAM). Applies to SIP calls only — it has no effect on calls to phone numbers.

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.password
string

SIP authentication password (sip_auth_password) for the outbound leg. Only applies to SIP URI targets — ignored for phone, Resource Address, queue, and stream destinations.

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 Resource Address 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 authentication username (sip_auth_username) for the outbound leg. Only applies to SIP URI targets — ignored for phone, Resource Address, queue, and stream destinations.

connect.webrtc_media
booleanDefaults to false

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

Stream-specific properties

The following properties apply only when to starts with stream:wss://.

connect.authorization_bearer_token
string

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

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

connect.custom_parameters
object

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

connect.name
string

Stream name identifier.

connect.realtime
booleanDefaults to false

Enable realtime mode for bidirectional audio.

Example

1version: 1.0.0
2sections:
3  main:
4    - connect:
5        to: "sip:alice@example.com"
6        from: "+15551112222"
7        username: "sipuser"
8        password: "s3cret"

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

1{
2  "event_type": "calling.call.state",
3  "event_channel": "swml:xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
4  "timestamp": 1640000000.123,
5  "project_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
6  "space_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
7  "params": {
8    "call_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
9    "node_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
10    "call_state": "answered",
11    "direction": "outbound",
12    "device": {
13      "type": "phone",
14      "params": {
15        "from_number": "+15551231234",
16        "to_number": "+15553214321"
17      }
18    },
19    "end_reason": null
20  }
21}

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

1{
2  "event_type": "calling.call.connect",
3  "event_channel": "swml:xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
4  "timestamp": 1640000000.123,
5  "project_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
6  "space_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
7  "params": {
8    "call_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
9    "node_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
10    "connect_state": "connected",
11    "peer": {
12      "call_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
13      "node_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
14      "device": {
15        "type": "phone",
16        "params": {
17          "from_number": "+15551231234",
18          "to_number": "+15553214321"
19        }
20      }
21    }
22  }
23}

Failed state example

1{
2  "event_type": "calling.call.connect",
3  "event_channel": "swml:xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
4  "timestamp": 1640000000.123,
5  "project_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
6  "space_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
7  "params": {
8    "call_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
9    "node_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
10    "connect_state": "failed",
11    "failed_reason": "no_answer"
12  }
13}

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

1{
2  "event_type": "calling.call.stream",
3  "event_channel": "swml:xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
4  "timestamp": 1640000000.123,
5  "project_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
6  "space_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
7  "params": {
8    "control_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
9    "state": "streaming",
10    "url": "wss://example.com/audio",
11    "name": "my-stream"
12  }
13}

Examples

Use connect with a Resource Address

Connect to a Resource by using its Address as the to value.

1version: 1.0.0
2sections:
3  main:
4    - answer: {}
5    - play:
6        volume: 10
7        urls:
8          - 'silence:1.0'
9          - 'say:Hello, connecting to a fabric Resource that is a room'
10    - connect:
11        to: /public/test_room

Dial a single phone number

1version: 1.0.0
2sections:
3  main:
4    - connect:
5        from: "+15553214321"
6        to: "+15551231234"

Dial numbers in parallel

1version: 1.0.0
2sections:
3  main:
4    - connect:
5        parallel:
6          - to: "+15551231234"
7          - to: "+15553214321"

Dial SIP serially with a timeout

1version: 1.0.0
2sections:
3  main:
4    - connect:
5        timeout: 20
6        serial:
7          - from: "sip:chris@example.com"
8            to: "sip:alice@example.com"
9          - to: "sip:bob@example.com"
10            codecs: PCMU

Set the caller ID name on SIP legs

Set from_name at the top level so every device inherits it, then override it on a single destination. agent1 sees the caller ID name “Support Team” (inherited); agent2 sees “Billing Dept” (overridden).

1version: 1.0.0
2sections:
3  main:
4    - connect:
5        from: "+15551000001"
6        from_name: "Support Team"
7        serial:
8          - to: "sip:agent1@pbx.example.com"
9          - to: "sip:agent2@pbx.example.com"
10            from_name: "Billing Dept"

Connect to a queue with transfer after bridge

1version: 1.0.0
2sections:
3  main:
4    - connect:
5        to: "queue:support"
6        transfer_after_bridge: "https://example.com/post-call-swml"

Connect to a WebSocket stream

1version: 1.0.0
2sections:
3  main:
4    - answer: {}
5    - connect:
6        to: "stream:wss://example.com/audio"
7        codec: PCMU
8        realtime: true
9        name: my-stream
10        status_url: "https://example.com/stream-status"