Calls

Create a Call

Create a call.

Permissions

The API token must include the following scopes: Voice.

post/Accounts/{AccountSid}/Calls

Path parameters

AccountSidstring uuid required

The Project ID that uniquely identifies the Account.

Request body

Urlstring

The URL to handle the call. Required if ApplicationSid is not used.

ApplicationSidstring uuid

The unique identifier of the application used to handle the call. Required if Url is not used.

Fromstring required

The address that initiated the call.

Tostring required

The address that received the call.

CallerIdstring

The number, in E.164 format, or identifier of the caller.

FallbackMethod'GET' | 'POST'

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

FallbackUrlstring

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

MachineDetection'Enable' | 'DetectMessageEnd' | 'none'

Whether a human or machine picked up the call.

AsyncAmdboolean

Whether or not to execute machine detection asynchronously.

AsyncAmdStatusCallbackstring

The URL to request when the machine detection is completed.

AsyncAmdStatusCallbackMethod'GET' | 'POST'

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

AsyncAmdPartialResultsboolean

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

MachineDetectionSilenceTimeoutinteger

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

MachineDetectionSpeechThresholdinteger

How many milliseconds of voice to decide it is a machine. Must be at least 1000 to a maximum of 6000. Default is 2400 milliseconds.

MachineDetectionSpeechEndThresholdinteger

Number of milliseconds to wait for voice to finish. Must be at least 500 to a maximum of 5000. Default is 1200 milliseconds.

MachineDetectionTimeoutinteger

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

MachineWordsThresholdinteger

How many words to count to decide it is a machine. Must be at least one to a maximum of 100. Default is 6.

MaxPricePerMinutenumber float

The maximum price in USD acceptable for the call to be created.

Method'GET' | 'POST'

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

Recordboolean

Whether or not to record a call.

RecordingChannels'mono' | 'dual'

The number of channels in the recording.

RecordingStatusCallbackstring

The URL to request when recording is available.

RecordingStatusCallbackMethod'GET' | 'POST'

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

RecordingTrack'inbound' | 'outbound' | 'both'

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

SipAuthUsernamestring

The username to authenticate the caller when making an outbound SIP call.

SipAuthPasswordstring

The password to authenticate the caller when making an outbound SIP call.

SendDigitsstring

The digits to press after a call is connected.

StatusCallbackstring

The URL SignalWire will send webhooks to on every requested StatusCallbackEvent event.

StatusCallbackEventstring[]

The status events that trigger a SignalWire webhook. Defaults to completed.

StatusCallbackMethod'GET' | 'POST'

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

Timeoutstring

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

Trim'trim-silence' | 'do-not-trim'

Whether leading and trailing silence is trimmed from a recording. Possible values are trim-silence or do-not-trim. Default is trim-silence.

Example request

{
  "Url": "http://your-application.com/docs/voice.xml",
  "ApplicationSid": "b3877c40-da60-4998-90ad-b792e98472ap",
  "From": "+13103384645",
  "To": "+13105678901",
  "CallerId": "+13102259067",
  "FallbackMethod": "GET",
  "FallbackUrl": "https://your-api-endpoint.com/path",
  "MachineDetection": "Enable",
  "AsyncAmdStatusCallback": "https://your-api-endpoint.com/path",
  "AsyncAmdStatusCallbackMethod": "GET",
  "MachineDetectionSilenceTimeout": 5000,
  "MachineDetectionSpeechThreshold": 2400,
  "MachineDetectionSpeechEndThreshold": 1200,
  "MachineDetectionTimeout": 30,
  "MachineWordsThreshold": 6,
  "MaxPricePerMinute": 0.0075,
  "Method": "POST",
  "RecordingChannels": "mono",
  "RecordingStatusCallback": "https://your-api-endpoint.com/path",
  "RecordingStatusCallbackMethod": "POST",
  "RecordingTrack": "both",
  "SipAuthUsername": "sipuser",
  "SipAuthPassword": "sippassword",
  "SendDigits": "w",
  "StatusCallback": "https://your-api-endpoint.com/path",
  "StatusCallbackEvent": [
    "completed"
  ],
  "StatusCallbackMethod": "GET",
  "Timeout": "60",
  "Trim": "trim-silence"
}

Response

The request has succeeded.

account_sidstring uuid

The unique identifier for the account that created this call.

annotationstring

The annotation for the call.

answered_by'human' | 'machine'

Who/what answered the call.

api_versionstring

The version of the SignalWire API.

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.

direction'inbound' | 'outbound'

Call direction.

durationinteger

The duration, in seconds, of the call.

end_timestring

The time, in RFC 2822 GMT format, on which the call was terminated.

forwarded_fromstring

The number this call was forwarded from.

fromstring

The address that initiated the call.

formatted_fromstring

The formatted number that initiated the call.

parent_call_sidstring uuid

The unique identifier for the call that created this call.

phone_number_sidstring uuid

The unique identifier for the phone number.

pricenumber float

The charge for the call.

price_unitstring

The currency, in ISO 4127 format, for the price of the call.

sidstring uuid

The unique identifier for the call.

start_timestring

The time, in RFC 2822 GMT format, on which the call began.

Call status.

tostring

The address that received the call.

formatted_tostring

The formatted number that received the call.

uristring

The URI for the call.

Example response

{
  "account_sid": "b3877c40-da60-4998-90ad-b792e98472af",
  "annotation": "Call annotation text",
  "api_version": "2010-04-01",
  "date_created": "Wed, 19 Sept 2018 20:00:00 +0000",
  "date_updated": "Wed, 19 Sept 2018 21:00:00 +0000",
  "duration": 20,
  "end_time": "Fri, 21 Sept 2018 10:00:00 +0000",
  "forwarded_from": "+13102259067",
  "from": "+13103384645",
  "formatted_from": "+13102259067",
  "parent_call_sid": "b3877c40-da60-4998-90ad-b792e98472af",
  "phone_number_sid": "b3877c40-da60-4998-90ad-b792e98472pn",
  "price": 0.003,
  "price_unit": "USD",
  "sid": "b3877c40-da60-4998-90ad-b792e98472ca",
  "start_time": "Wed, 19 Sept 2018 20:00:01 +0000",
  "subresource_uris": {
    "notifications": "/api/laml/2010-04-01/Accounts/b3877c40-da60-4998-90ad-b792e98472af/Calls/b3877c40-da60-4998-90ad-b792e98472ca/Notifications.json",
    "recordings": "/api/laml/2010-04-01/Accounts/b3877c40-da60-4998-90ad-b792e98472af/Calls/b3877c40-da60-4998-90ad-b792e98472ca/Recordings.json"
  },
  "to": "+13105678901",
  "formatted_to": "(310) 567-8901",
  "uri": "/api/laml/2010-04-01/Accounts/b3877c40-da60-4998-90ad-b792e98472af/Calls/b3877c40-da60-4998-90ad-b792e98472ca.json"
}