connect
Dial a SIP URI or phone number.
Parameters
Name | Type | Description |
---|---|---|
from | string | Caller ID number. Optional. Default is calling party caller ID number. Can be overwritten on each destination. |
headers | object | Custom SIP headers to add to INVITE. Has no effect on calls to phone numbers. Optional. Default is not set. |
codecs | string | Comma-separated string of codecs to offer. Has no effect on calls to phone numbers. Optional. Default is set based on SignalWire settings. |
webrtc_media | boolean | If true, WebRTC media is offered to the SIP endpoint. Has no effect on calls to phone numbers. Optional. Default is false . |
session_timeout | integer | Time, in seconds, to set the SIP Session-Expires header in INVITE. Must be a positive, non-zero number. Has no effect on calls to phone numbers. Optional. Default is set based on SignalWire settings. |
ringback | string [] | Array of play URIs to play as ringback tone. Optional. Default will play audio from the provider. |
timeout | integer | Maximum time, in seconds, to wait for an answer. Optional. Default is 60. |
max_duration | integer | Maximum duration, in seconds, allowed for the call. Optional. Default is 14400 (4 hours). |
answer_on_bridge | boolean | Delay answer until the B-leg answers. Optional. Default is false. |
call_state_url | string | Webhook url to send call state change notifications to for all legs. Optional. Default is not set. Can be overwritten on each destination. |
call_state_events | string [] | An array of call state event names to be notified about. Allowed event names are created , ringing , answered , and ended . Optional. Default is ["ended"] . Can be overwritten on each destination. |
In addition, you are required to specify one and only one of the following dialing parameters:
Name | Type | Description |
---|---|---|
serial_parallel | object [][] | Array of arrays. Inner arrays contain destination objects to dial simultaneously. Outer array attempts each parallel group in order. |
serial | object [] | Array of destination objects to dial in order. |
parallel | object [] | Array of destination objects to dial simultaneously. |
to | string | Single destination to dial. Possible values are a phone number (i.e.: "+15552345678") or sip uri (i.e. "sip:alice@example.com"). |
Parameters for destination
Name | Type | Description |
---|---|---|
to | string | Phone number or SIP URI to dial. Required. |
from | string | Caller ID number. Optional. Default is calling party caller ID number. |
timeout | integer | Maximum time, in seconds, to wait for destination to answer. Optional. Default is 60. |
call_state_url | string | Webhook url to send call state change notifications to. Optional. Default is not set. |
call_state_events | string [] | An array of call state event names to be notified about. Allowed event names are created , ringing , answered , and ended . Optional. Default is ["ended"] . |
Variables
Set by the method:
- connect_result: (out)
connected
|failed
. - connect_failed_reason: (out) Detailed reason for failure.
- return_value: (out) Same value as
connect_result
.
Examples
Dial a single phone number
- YAML
- JSON
version: 1.0.0
sections:
main:
- connect:
from: "+15553214321"
to: "+15551231234"
{
"version": "1.0.0",
"sections": {
"main": [
{
"connect": {
"from": "+15553214321",
"to": "+15551231234"
}
}
]
}
}
Dial numbers in parallel
- YAML
- JSON
version: 1.0.0
sections:
main:
- connect:
parallel:
- to: "+15551231234"
- to: "+15553214321"
{
"version": "1.0.0",
"sections": {
"main": [
{
"connect": {
"parallel": [
{ "to": "+15551231234" },
{ "to": "+15553214321" }
]
}
}
]
}
}
Dial SIP serially with a timeout
- YAML
- 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
{
"version": "1.0.0",
"sections": {
"main": [
{
"connect": {
"timeout": 20,
"serial": [
{ "from": "sip:chris@example.com", "to": "sip:alice@example.com" },
{ "codecs": "PCMU", "to": "sip:bob@example.com" }
]
}
}
]
}
}