Skip to navigation
Compatibility REST APICalls

Create a Call

View as MarkdownOpen in Claude

Starts an outbound call whose behavior is supplied by a cXML URL or Application SID. Use this form-encoded route for integrations built around cXML call control and Call SIDs; use the Calling API for SWML-driven calls and command-based control.

Permissions

The API token used to authenticate must have the following scope(s) enabled to make a successful request: Voice.

Learn more about API scopes.

Authentication

AuthorizationBasic

SignalWire Basic Authentication using Project ID and API Token.

The client sends HTTP requests with the Authorization header containing the word Basic followed by a space and a base64-encoded string of project_id:token. The project ID will be used as the username and the API token as the password.

Example:

Authorization: Basic base64(project_id:token)

Path parameters

AccountSidstringRequiredformat: "uuid"
The Project ID that uniquely identifies the Account.

Request

This endpoint expects an object.
TostringRequired
The address that received the call. Can be a phone number in E.164 format, a SIP URI, or a client identifier.
FromstringRequired
The address that initiated the call. Must be a phone number in E.164 format for PSTN calls.
UrlstringOptionalformat: "uri"

The URL to handle the call. Required if ApplicationSid and Laml/Twiml are not used.

ApplicationSidstringOptionalformat: "uuid"

The unique identifier of the application used to handle the call. Required if Url and Laml/Twiml are not used.

MethodenumOptionalDefaults to POST

Whether the request to Url is a GET or a POST. Default is POST.

Allowed values:
FallbackUrlstringOptionalformat: "uri"

The URL SignalWire will request if errors occur when fetching the Url.

FallbackMethodenumOptionalDefaults to POST

Whether the request to FallbackUrl is a GET or a POST. Default is POST.

Allowed values:
StatusCallbackstringOptionalformat: "uri"

The URL SignalWire will send webhooks to on every requested StatusCallbackEvent event. See the Voice status callback webhook for the payload your URL will receive.

StatusCallbackMethodenumOptionalDefaults to POST

Whether the request to StatusCallback URL is a GET or a POST. Default is POST.

Allowed values:
StatusCallbackEventlist of stringsOptionalDefaults to ["completed"]

The status events that trigger a SignalWire webhook. Valid values: initiated, ringing, answered, completed, ringing_forwarded, ringing_queued. Defaults to completed. Subscribing to answered sends an answered callback followed by an in-progress callback, timestamped one second later; in-progress can’t be subscribed to separately. If StatusCallbackEvent includes completed, which it does by default, you also receive a callback with CallStatus set to failed when SignalWire stops the call before dialing it. The Voice status callback lists the reasons.

CallerIdstringOptional
The number, in E.164 format, or identifier of the caller. Used to override the From for caller ID purposes.
SendDigitsstringOptionalformat: "^[\d#*wW]{1,32}$"<=32 characters

The digits to press after a call is connected. Valid characters are 0-9, #, *, w (wait 0.5s), and W (wait 1s).

TimeoutintegerOptional1-600Defaults to 60

The time in seconds SignalWire will wait before assuming the call has no answer. Default is 60 seconds.

MachineDetectionenumOptionalDefaults to none

Whether a human or machine picked up the call. Default is none.

Allowed values:
MachineDetectionTimeoutintegerOptional1-120Defaults to 30

The time in seconds SignalWire will wait for machine detection before timing out. Default is 30 seconds.

MachineDetectionSpeechThresholdintegerOptional1000-6000Defaults to 2400

How many milliseconds of voice to decide it is a machine. Default is 2400 milliseconds.

MachineDetectionSpeechEndThresholdintegerOptional500-5000Defaults to 1200

Number of milliseconds to wait for voice to finish. Default is 1200 milliseconds.

MachineDetectionSilenceTimeoutintegerOptional2000-10000Defaults to 5000

Number of milliseconds to wait for initial voice before giving up. Default is 5000 milliseconds.

MachineWordsThresholdintegerOptional1-100Defaults to 6

How many words to count to decide it is a machine. Default is 6.

AsyncAmdbooleanOptionalDefaults to false

Whether or not to execute machine detection asynchronously. Default is false.

AsyncAmdStatusCallbackMethodenumOptionalDefaults to POST

Whether the request to AsyncAmdStatusCallback is a GET or a POST. Default is POST.

Allowed values:
AsyncAmdStatusCallbackstringOptionalformat: "uri"
The URL to request when the machine detection is completed.
AsyncAmdPartialResultsbooleanOptionalDefaults to false

Whether or not to report partial (interim) results to the callback url. Default is false.

RecordbooleanOptionalDefaults to false

Whether or not to record a call. Default is false.

RecordingChannelsenumOptionalDefaults to mono

The number of channels in the recording. Default is mono.

Allowed values:
RecordingTrackenumOptionalDefaults to both

Specifies whether to record the inbound, outbound, or both audio. Default is both.

Allowed values:
RecordingStatusCallbackstringOptionalformat: "uri"

The URL to request when recording is available. See the Recording status callback webhook for the payload your URL will receive.

RecordingStatusCallbackMethodenumOptionalDefaults to POST

Whether the request to RecordingStatusCallback URL is a GET or a POST. Default is POST.

Allowed values:
RecordingStatusCallbackEventstringOptionalDefaults to completed

The recording status events that trigger a webhook. Space-separated list. Valid values: completed, in-progress, absent. Default is completed.

TrimenumOptionalDefaults to trim-silence

Whether leading and trailing silence is trimmed from a recording. Default is trim-silence.

Allowed values:
SipAuthUsernamestringOptional
The username to authenticate the caller when making an outbound SIP call.
SipAuthPasswordstringOptional
The password to authenticate the caller when making an outbound SIP call.
MaxPricePerMinutestringOptionalformat: "^\d+\.?\d{0,4}$"

The maximum price in USD acceptable for the call to be created. Format: up to 4 decimal places.

Response

Response returned when a call is created.
sidstringformat: "uuid"
The unique identifier for the call.
account_sidstringformat: "uuid"
The unique identifier for the account that created this call.
date_createdstring
The date, in RFC 2822 GMT format, this call was created.
date_updatedstring
The date, in RFC 2822 GMT format, this call was updated.
parent_call_sidstring or nullformat: "uuid"
The unique identifier for the call that created this call.
tostring
The address that received the call.
formatted_tostring
The formatted number that received the call.
to_formattedstring

The formatted number that received the call. Alias for formatted_to.

fromstring
The address that initiated the call.
formatted_fromstring
The formatted number that initiated the call.
from_formattedstring

The formatted number that initiated the call. Alias for formatted_from.

phone_number_sidstring or nullformat: "uuid"
The unique identifier for the phone number.
statusenum
The status of the call.
start_timestring or null
The time, in RFC 2822 GMT format, the call started ringing. This is before the call was answered. Null until the call starts.
end_timestring or null
The time, in RFC 2822 GMT format, on which the call was terminated. Null until the call ends.
durationinteger

The duration, in seconds, of the call: end_time minus start_time, rounded up to the next whole second. It includes ringing time, so it’s longer than the time the call was connected and usually longer than a recording of the call. For a call still in progress, it’s the time elapsed so far; before the call starts, it’s 0.

pricefloat or null
The charge for the call.
price_unitstring
The currency, in ISO 4127 format, for the price of the call.
directionenum

The direction of the call.

  • inbound: inbound calls.
  • outbound-api: calls launched through the REST API.
  • outbound-dial: calls launched through the Dial verb.
Allowed values:
answered_byenum or null

Who/what the call was answered by.

Allowed values:
api_versionstring
The version of the SignalWire API.
forwarded_fromstring or null
The number this call was forwarded from. Always null.
caller_namestring or null
The caller name. Always null.
uristring
The URI for the call.
subresource_urisobject

A Map of available sub-resources.

annotationstring or null
The annotation for the call. Always null.
group_sidstring or null
The group SID for the call. Always null.
audio_in_mosstring or null

The estimated Mean Opinion Score (MOS) for inbound audio quality, based on the share of incoming audio packets that arrived without loss or delay. It ranges from about 1 to 4.5, the score for a call with no lost or late packets. Returned as a decimal string. Null if the call has no quality measurement.

sip_result_codestring or null
The SIP result code for the call.
audio_rtt_avgdouble or null

The average round-trip time for audio in milliseconds, in steps of 10.

audio_rtt_mindouble or null

The minimum round-trip time for audio in milliseconds, in steps of 10.

audio_rtt_maxdouble or null

The maximum round-trip time for audio in milliseconds, in steps of 10.

audio_in_jitter_mindouble or null
The smallest variance measured in the time between incoming audio packets, in milliseconds squared.
audio_in_jitter_maxdouble or null
The largest variance measured in the time between incoming audio packets, in milliseconds squared.
audio_out_jitter_mindouble or null
The minimum outbound audio jitter in milliseconds.
audio_out_jitter_maxdouble or null
The maximum outbound audio jitter in milliseconds.
audio_out_jitter_avgdouble or null
The average outbound audio jitter in milliseconds.
audio_in_media_packet_countinteger or null
The number of audio packets received in the inbound media stream.
audio_out_packet_countinteger or null

Not populated. Always null; use audio_out_media_packet_count for the number of audio packets sent.

audio_out_media_packet_countinteger or null
The number of audio packets sent in the outbound media stream.
audio_out_lostinteger or null
The number of outbound audio packets lost.
audio_in_mean_intervaldouble or null
The mean interval between inbound audio packets in milliseconds.
audio_in_dtmf_packet_countinteger or null
The number of DTMF packets in the inbound media stream.
audio_out_dtmf_packet_countinteger or null
The number of DTMF packets in the outbound media stream.
audio_in_skip_packet_countinteger or null
The number of inbound audio intervals filled with comfort noise because no audio packet was available. It grows with lost or late packets and during DTMF digits.
audio_in_flush_packet_countinteger or null
The number of queued inbound packets discarded when the media stream was flushed, for example when the call was bridged or unbridged.
audio_in_largest_jb_sizeinteger or null

Not populated. Always 0 when the call has quality statistics.

Errors

400
Bad Request Error
422
Unprocessable Entity Error