REST Client MethodsCalls

Create

View as Markdown

Use this endpoint for the Calls method to create a new call.

Path parameters

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

Request

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](/docs/compatibility-api/rest/calls/webhooks/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 stringsOptional
The status events that trigger a SignalWire webhook. Valid values: initiated, ringing, answered, completed, ringing_forwarded, ringing_queued. Defaults to `completed`.
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](/docs/compatibility-api/rest/recordings/webhooks/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

sidstringRequiredformat: "uuid"
The unique identifier for the call.
account_sidstringRequiredformat: "uuid"
The unique identifier for the account that created this call.
date_createdstringRequired
The date, in RFC 2822 GMT format, this call was created.
date_updatedstringRequired
The date, in RFC 2822 GMT format, this call was updated.
parent_call_sidstring or nullRequiredformat: "uuid"
The unique identifier for the call that created this call.
tostringRequired
The address that received the call.
formatted_tostringRequired
The formatted number that received the call.
to_formattedstringRequired
The formatted number that received the call. Alias for formatted_to.
fromstringRequired
The address that initiated the call.
formatted_fromstringRequired
The formatted number that initiated the call.
from_formattedstringRequired
The formatted number that initiated the call. Alias for formatted_from.
phone_number_sidstring or nullRequiredformat: "uuid"
The unique identifier for the phone number.
statusenumRequired
The status of the call.
start_timestring or nullRequired
The time, in RFC 2822 GMT format, on which the call began.
end_timestring or nullRequired
The time, in RFC 2822 GMT format, on which the call was terminated.
durationintegerRequired
The duration, in seconds, of the call.
pricedouble or nullRequired
The charge for the call.
price_unitstringRequired
The currency, in ISO 4127 format, for the price of the call.
directionenumRequired
The direction of the call.
Allowed values:
answered_byenum or nullRequired
Who/what the call was answered by.
Allowed values:
api_versionstringRequired
The version of the SignalWire API.
forwarded_fromstring or nullRequired
The number this call was forwarded from. Always null.
caller_namestring or nullRequired
The caller name. Always null.
uristringRequired
The URI for the call.
subresource_urisobjectRequired
A Map of available sub-resources.
annotationstring or nullRequired
The annotation for the call. Always null.
group_sidstring or nullRequired
The group SID for the call. Always null.
audio_in_mosdouble or nullRequired
The Mean Opinion Score for audio quality (1.0-5.0).
sip_result_codestring or nullRequired
The SIP result code for the call.
audio_rtt_avginteger or nullRequired
The average round-trip time for audio in milliseconds.
audio_rtt_mininteger or nullRequired
The minimum round-trip time for audio in milliseconds.
audio_rtt_maxinteger or nullRequired
The maximum round-trip time for audio in milliseconds.
audio_out_jitter_mininteger or nullRequired
The minimum outbound audio jitter in milliseconds.
audio_out_jitter_maxinteger or nullRequired
The maximum outbound audio jitter in milliseconds.
audio_out_jitter_avginteger or nullRequired
The average outbound audio jitter in milliseconds.
audio_out_lostinteger or nullRequired
The number of outbound audio packets lost.

Request examples

1const { RestClient } = require('@signalwire/compatibility-api')
2const client = RestClient('YourProjectID', 'YourAuthToken', { signalwireSpaceUrl: 'example.signalwire.com' })
3
4client.calls
5      .create({
6         url: 'http://your-application.com/docs/voice.xml',
7         to: '+13105678901',
8         from: '+13103384645'
9       })
10      .then(call => console.log(call.sid))
11      .done();