> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes. # connect > Connect to a phone number, SIP URI, Resource Address, queue, or WebSocket stream. [statuscallbacks]: #statuscallbacks Connect to a phone number, [SIP URI](/docs/platform/voice/sip), [Resource Address](/docs/platform/addresses), queue, or WebSocket stream. ## **Properties** **`connect`** `object` — required Connects the current call to a destination — a phone number, [SIP URI](/docs/platform/voice/sip), [Resource Address](/docs/platform/addresses), 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. --- #### Single Dial a single destination directly using the `to` property. **`connect.to`** `string` — required 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](/docs/platform/addresses)** — 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`** `boolean` — default: false Delay answer until the B-leg answers. --- **`connect.call_state_events`** `string[]` — default: \['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][statuscallbacks]. --- **`connect.codecs`** `string` — default: 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`** `integer` — default: Inherits from timeout The amount of time, in seconds, to wait for the `confirm` script to execute. --- **`connect.encryption`** `string` — default: optional The encryption method to use for the call. Possible values: `mandatory`, `optional`, `forbidden`. --- **`connect.from`** `string` — default: 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`** `string` — required The name of the header. --- **`headers[].value`** `string` — required The value of the header. --- **`connect.max_duration`** `integer` — default: 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](/docs/platform/voice/sip) 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`](/docs/swml/reference/calling/switch#properties) when the `return_value` is a object, and will use the [`cond properties`](/docs/swml/reference/calling/cond#properties) method when the `return_value` is an array. See [Variables](#variables) for details. --- **`connect.ringback`** `string[]` — default: Plays audio from the provider Array of `play` URIs to play as ringback tone. --- **`connect.session_timeout`** `integer` — default: 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](#connect-status-callbacks). For stream destinations, reports stream status notifications. See [Stream Status Callbacks](#stream-status-callbacks). --- **`connect.status_url_method`** `string` — default: POST HTTP method for the status webhook. Possible values: `GET`, `POST`. **Stream destinations only.** --- **`connect.timeout`** `integer` — default: 60 seconds Maximum time, in seconds, to wait for an answer. --- **`connect.execute_after_queue`** `string` SWML to execute on this call after its bridge with the queued call ends. Only applies when `to` starts with `queue:`. Can be either: * A URL (http or https) that returns a SWML document * An inline SWML document (as a JSON string) When omitted, the call hangs up when the bridge ends. Either way, the script does not continue past `connect` for queue targets, so `result` never runs. --- **`connect.username`** `string` SIP authentication username (`sip_auth_username`) for the outbound leg. **Only applies to [SIP URI](/docs/platform/voice/sip) targets** — ignored for phone, Resource Address, queue, and stream destinations. --- **`connect.webrtc_media`** `boolean` — default: 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`** `string` — default: 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`** `boolean` — default: false Enable realtime mode for bidirectional audio. --- #### Example #### YAML ```yaml version: 1.0.0 sections: main: - connect: to: "sip:alice@example.com" from: "+15551112222" username: "sipuser" password: "s3cret" ``` #### JSON ```json { "version": "1.0.0", "sections": { "main": [ { "connect": { "to": "sip:alice@example.com", "from": "+15551112222", "username": "sipuser", "password": "s3cret" } } ] } } ``` #### Parallel Dial multiple destinations simultaneously — the first to answer is bridged and the rest are cancelled. **`connect.parallel`** `object[]` — required Array of destination objects to dial simultaneously. The first destination to answer is bridged and the rest are cancelled. --- **`parallel[].to`** `string` — required Destination to dial. Can be: * Phone number in E.164 format (e.g., `+15552345678`) * [SIP URI](/docs/platform/voice/sip) (e.g., `sip:alice@example.com`) * [Resource Address](/docs/platform/addresses) (e.g., `/public/test_room`) * Queue (e.g., `queue:support`) * WebSocket stream (e.g., `stream:wss://example.com/audio`) --- **`parallel[].from`** `string` Caller ID number. Overrides the top-level `from`. --- **`parallel[].from_name`** `string` The caller ID name shown to this destination. Overrides the top-level `from_name`. Applies to SIP calls only. --- **`parallel[].username`** `string` SIP authentication username (`sip_auth_username`) for this destination. **Only applies to SIP URI targets.** --- **`parallel[].password`** `string` SIP authentication password (`sip_auth_password`) for this destination. **Only applies to SIP URI targets.** --- **`parallel[].timeout`** `integer` — default: 60 seconds Maximum time, in seconds, to wait for this destination to answer. --- **`parallel[].call_state_events`** `string[]` — default: \['ended'] An array of call state event names to be notified about. Overrides the top-level `call_state_events`. --- **`parallel[].call_state_url`** `string` Webhook url to send call state change notifications to for this destination. Overrides the top-level `call_state_url`. --- **`parallel[].confirm`** `string | object[]` Confirmation script to execute on this destination when answered. Overrides the top-level `confirm`. --- **`parallel[].confirm_timeout`** `integer` Seconds to wait for the `confirm` script to execute on this destination. Overrides the top-level `confirm_timeout`. --- **`parallel[].encryption`** `string` Media encryption (SRTP) for this destination. Overrides the top-level `encryption`. **Applies to SIP destinations only.** Possible values: `mandatory`, `optional`, `forbidden`. --- **`connect.answer_on_bridge`** `boolean` — default: false Delay answer until the B-leg answers. --- **`connect.call_state_events`** `string[]` — default: \['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][statuscallbacks]. --- **`connect.codecs`** `string` — default: 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`** `integer` — default: Inherits from timeout The amount of time, in seconds, to wait for the `confirm` script to execute. --- **`connect.encryption`** `string` — default: optional The encryption method to use for the call. Possible values: `mandatory`, `optional`, `forbidden`. --- **`connect.from`** `string` — default: Calling party's caller ID number Caller ID number. Optional. Can be overwritten on each destination. --- **`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. Can be overridden on each destination. --- **`connect.headers`** `object[]` Custom SIP headers to add to INVITE. Has no effect on calls to phone numbers. --- **`headers[].name`** `string` — required The name of the header. --- **`headers[].value`** `string` — required The value of the header. --- **`connect.max_duration`** `integer` — default: 14400 seconds (4 hours) Maximum duration, in seconds, allowed for the call. --- **`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`](/docs/swml/reference/calling/switch#properties) when the `return_value` is a object, and will use the [`cond properties`](/docs/swml/reference/calling/cond#properties) method when the `return_value` is an array. See [Variables](#variables) for details. --- **`connect.ringback`** `string[]` — default: Plays audio from the provider Array of `play` URIs to play as ringback tone. --- **`connect.session_timeout`** `integer` — default: 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. Reports the connect operation status (connecting, connected, failed, disconnected). See [Connect Status Callbacks](#connect-status-callbacks). --- **`connect.timeout`** `integer` — default: 60 seconds Maximum time, in seconds, to wait for an answer. --- **`connect.webrtc_media`** `boolean` — default: false If true, WebRTC media is offered to the SIP endpoint. Has no effect on calls to phone numbers. --- #### Example #### YAML ```yaml version: 1.0.0 sections: main: - connect: from: "+15551112222" parallel: - to: "sip:alice@example.com" username: "alice_user" password: "alice_pw" - to: "sip:bob@example.com" username: "bob_user" password: "bob_pw" ``` #### JSON ```json { "version": "1.0.0", "sections": { "main": [ { "connect": { "from": "+15551112222", "parallel": [ { "to": "sip:alice@example.com", "username": "alice_user", "password": "alice_pw" }, { "to": "sip:bob@example.com", "username": "bob_user", "password": "bob_pw" } ] } } ] } } ``` #### Serial Dial destinations in sequence — each destination is tried one at a time, moving to the next if the previous fails. **`connect.serial`** `object[]` — required Array of destination objects to dial in order. Each destination is tried sequentially — if the first fails, the next is attempted. --- **`serial[].to`** `string` — required Destination to dial. Can be: * Phone number in E.164 format (e.g., `+15552345678`) * [SIP URI](/docs/platform/voice/sip) (e.g., `sip:alice@example.com`) * [Resource Address](/docs/platform/addresses) (e.g., `/public/test_room`) * Queue (e.g., `queue:support`) * WebSocket stream (e.g., `stream:wss://example.com/audio`) --- **`serial[].from`** `string` Caller ID number. Overrides the top-level `from`. --- **`serial[].from_name`** `string` The caller ID name shown to this destination. Overrides the top-level `from_name`. Applies to SIP calls only. --- **`serial[].username`** `string` SIP authentication username (`sip_auth_username`) for this destination. **Only applies to SIP URI targets.** --- **`serial[].password`** `string` SIP authentication password (`sip_auth_password`) for this destination. **Only applies to SIP URI targets.** --- **`serial[].timeout`** `integer` — default: 60 seconds Maximum time, in seconds, to wait for this destination to answer. --- **`serial[].call_state_events`** `string[]` — default: \['ended'] An array of call state event names to be notified about. Overrides the top-level `call_state_events`. --- **`serial[].call_state_url`** `string` Webhook url to send call state change notifications to for this destination. Overrides the top-level `call_state_url`. --- **`serial[].confirm`** `string | object[]` Confirmation script to execute on this destination when answered. Overrides the top-level `confirm`. --- **`serial[].confirm_timeout`** `integer` Seconds to wait for the `confirm` script to execute on this destination. Overrides the top-level `confirm_timeout`. --- **`serial[].encryption`** `string` Media encryption (SRTP) for this destination. Overrides the top-level `encryption`. **Applies to SIP destinations only.** Possible values: `mandatory`, `optional`, `forbidden`. --- **`connect.answer_on_bridge`** `boolean` — default: false Delay answer until the B-leg answers. --- **`connect.call_state_events`** `string[]` — default: \['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][statuscallbacks]. --- **`connect.codecs`** `string` — default: 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`** `integer` — default: Inherits from timeout The amount of time, in seconds, to wait for the `confirm` script to execute. --- **`connect.encryption`** `string` — default: optional The encryption method to use for the call. Possible values: `mandatory`, `optional`, `forbidden`. --- **`connect.from`** `string` — default: Calling party's caller ID number Caller ID number. Optional. Can be overwritten on each destination. --- **`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. Can be overridden on each destination. --- **`connect.headers`** `object[]` Custom SIP headers to add to INVITE. Has no effect on calls to phone numbers. --- **`headers[].name`** `string` — required The name of the header. --- **`headers[].value`** `string` — required The value of the header. --- **`connect.max_duration`** `integer` — default: 14400 seconds (4 hours) Maximum duration, in seconds, allowed for the call. --- **`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`](/docs/swml/reference/calling/switch#properties) when the `return_value` is a object, and will use the [`cond properties`](/docs/swml/reference/calling/cond#properties) method when the `return_value` is an array. See [Variables](#variables) for details. --- **`connect.ringback`** `string[]` — default: Plays audio from the provider Array of `play` URIs to play as ringback tone. --- **`connect.session_timeout`** `integer` — default: 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. Reports the connect operation status (connecting, connected, failed, disconnected). See [Connect Status Callbacks](#connect-status-callbacks). --- **`connect.timeout`** `integer` — default: 60 seconds Maximum time, in seconds, to wait for an answer. --- **`connect.webrtc_media`** `boolean` — default: false If true, WebRTC media is offered to the SIP endpoint. Has no effect on calls to phone numbers. --- #### Example #### YAML ```yaml version: 1.0.0 sections: main: - connect: from: "+15551112222" serial: - to: "sip:primary@example.com" username: "primary_user" password: "primary_pw" - to: "sip:backup@example.com" username: "backup_user" password: "backup_pw" ``` #### JSON ```json { "version": "1.0.0", "sections": { "main": [ { "connect": { "from": "+15551112222", "serial": [ { "to": "sip:primary@example.com", "username": "primary_user", "password": "primary_pw" }, { "to": "sip:backup@example.com", "username": "backup_user", "password": "backup_pw" } ] } } ] } } ``` #### Serial Parallel Combine both strategies. The outer array is the **serial** dimension — groups are tried one at a time, in order. Each inner array is the **parallel** dimension — all destinations in that group are dialed simultaneously. If no destination answers in the first group, the next group is attempted. **`connect.serial_parallel`** `object[][]` — required Array of arrays combining both strategies. The outer array is the **serial** dimension — each element is a group tried in order. Each inner array is the **parallel** dimension — all destinations in that group are dialed simultaneously. If no destination in the current group answers, the next group is attempted. In the `[][]` notation below, the first `[]` is the serial (group) index and the second `[]` is the parallel (destination) index within that group. --- **`serial_parallel[][].to`** `string` — required Destination to dial. Can be: * Phone number in E.164 format (e.g., `+15552345678`) * [SIP URI](/docs/platform/voice/sip) (e.g., `sip:alice@example.com`) * [Resource Address](/docs/platform/addresses) (e.g., `/public/test_room`) * Queue (e.g., `queue:support`) * WebSocket stream (e.g., `stream:wss://example.com/audio`) --- **`serial_parallel[][].from`** `string` Caller ID number. Overrides the top-level `from`. --- **`serial_parallel[][].from_name`** `string` The caller ID name shown to this destination. Overrides the top-level `from_name`. Applies to SIP calls only. --- **`serial_parallel[][].username`** `string` SIP authentication username (`sip_auth_username`) for this destination. **Only applies to SIP URI targets.** --- **`serial_parallel[][].password`** `string` SIP authentication password (`sip_auth_password`) for this destination. **Only applies to SIP URI targets.** --- **`serial_parallel[][].timeout`** `integer` — default: 60 seconds Maximum time, in seconds, to wait for this destination to answer. --- **`serial_parallel[][].call_state_events`** `string[]` — default: \['ended'] An array of call state event names to be notified about. Overrides the top-level `call_state_events`. --- **`serial_parallel[][].call_state_url`** `string` Webhook url to send call state change notifications to for this destination. Overrides the top-level `call_state_url`. --- **`serial_parallel[][].confirm`** `string | object[]` Confirmation script to execute on this destination when answered. Overrides the top-level `confirm`. --- **`serial_parallel[][].confirm_timeout`** `integer` Seconds to wait for the `confirm` script to execute on this destination. Overrides the top-level `confirm_timeout`. --- **`serial_parallel[][].encryption`** `string` Media encryption (SRTP) for this destination. Overrides the top-level `encryption`. **Applies to SIP destinations only.** Possible values: `mandatory`, `optional`, `forbidden`. --- **`connect.answer_on_bridge`** `boolean` — default: false Delay answer until the B-leg answers. --- **`connect.call_state_events`** `string[]` — default: \['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][statuscallbacks]. --- **`connect.codecs`** `string` — default: 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`** `integer` — default: Inherits from timeout The amount of time, in seconds, to wait for the `confirm` script to execute. --- **`connect.encryption`** `string` — default: optional The encryption method to use for the call. Possible values: `mandatory`, `optional`, `forbidden`. --- **`connect.from`** `string` — default: Calling party's caller ID number Caller ID number. Optional. Can be overwritten on each destination. --- **`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. Can be overridden on each destination. --- **`connect.headers`** `object[]` Custom SIP headers to add to INVITE. Has no effect on calls to phone numbers. --- **`headers[].name`** `string` — required The name of the header. --- **`headers[].value`** `string` — required The value of the header. --- **`connect.max_duration`** `integer` — default: 14400 seconds (4 hours) Maximum duration, in seconds, allowed for the call. --- **`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`](/docs/swml/reference/calling/switch#properties) when the `return_value` is a object, and will use the [`cond properties`](/docs/swml/reference/calling/cond#properties) method when the `return_value` is an array. See [Variables](#variables) for details. --- **`connect.ringback`** `string[]` — default: Plays audio from the provider Array of `play` URIs to play as ringback tone. --- **`connect.session_timeout`** `integer` — default: 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. Reports the connect operation status (connecting, connected, failed, disconnected). See [Connect Status Callbacks](#connect-status-callbacks). --- **`connect.timeout`** `integer` — default: 60 seconds Maximum time, in seconds, to wait for an answer. --- **`connect.webrtc_media`** `boolean` — default: false If true, WebRTC media is offered to the SIP endpoint. Has no effect on calls to phone numbers. --- #### Example #### YAML ```yaml version: 1.0.0 sections: main: - connect: from: "+15551112222" serial_parallel: - - to: "sip:alice@example.com" username: "alice_user" password: "alice_pw" - to: "sip:bob@example.com" username: "bob_user" password: "bob_pw" - - to: "sip:fallback@example.com" username: "fb_user" password: "fb_pw" ``` #### JSON ```json { "version": "1.0.0", "sections": { "main": [ { "connect": { "from": "+15551112222", "serial_parallel": [ [ { "to": "sip:alice@example.com", "username": "alice_user", "password": "alice_pw" }, { "to": "sip:bob@example.com", "username": "bob_user", "password": "bob_pw" } ], [ { "to": "sip:fallback@example.com", "username": "fb_user", "password": "fb_pw" } ] ] } } ] } } ``` --- ## **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** > **Status callbacks are advisory** > > Status callbacks are asynchronous, best-effort HTTP notifications: delivery can be delayed or fail silently — if your server is unreachable, the callback simply never arrives. Don't gate time-critical or business-critical actions solely on receiving one. Confirm state via the REST API before acting, or use a transport with visible failure modes — see [Status callback reliability](/docs/platform/webhooks#status-callback-reliability). 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 ```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. **`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 ```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. **`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 ```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 a Resource Address Connect to a [Resource](/docs/platform/resources) by using its [Address](/docs/platform/addresses) as the `to` value. #### 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 ``` #### 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" } } ] } } ``` ### Dial a single phone number #### YAML ```yaml version: 1.0.0 sections: main: - connect: from: "+15553214321" to: "+15551231234" ``` #### JSON ```json { "version": "1.0.0", "sections": { "main": [ { "connect": { "from": "+15553214321", "to": "+15551231234" } } ] } } ``` ### Dial numbers in parallel #### YAML ```yaml version: 1.0.0 sections: main: - connect: parallel: - to: "+15551231234" - to: "+15553214321" ``` #### JSON ```json { "version": "1.0.0", "sections": { "main": [ { "connect": { "parallel": [ { "to": "+15551231234" }, { "to": "+15553214321" } ] } } ] } } ``` ### Dial SIP serially with a timeout #### 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 ``` #### 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" } ] } } ] } } ``` ### 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). #### YAML ```yaml version: 1.0.0 sections: main: - connect: from: "+15551000001" from_name: "Support Team" serial: - to: "sip:agent1@pbx.example.com" - to: "sip:agent2@pbx.example.com" from_name: "Billing Dept" ``` #### JSON ```json { "version": "1.0.0", "sections": { "main": [ { "connect": { "from": "+15551000001", "from_name": "Support Team", "serial": [ { "to": "sip:agent1@pbx.example.com" }, { "to": "sip:agent2@pbx.example.com", "from_name": "Billing Dept" } ] } } ] } } ``` ### Connect to a queue #### YAML ```yaml version: 1.0.0 sections: main: - connect: to: "queue:support" execute_after_queue: "https://example.com/post-call-swml" ``` #### JSON ```json { "version": "1.0.0", "sections": { "main": [ { "connect": { "to": "queue:support", "execute_after_queue": "https://example.com/post-call-swml" } } ] } } ``` ### Connect to a WebSocket stream #### 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" ``` #### 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" } } ] } } ``` > Connect to a phone number, SIP URI, Resource Address, queue, or WebSocket stream.