Making Calls

The /call/ function serves several purposes. In this section, we will cover the creating new calls utilizing POST variables.

API Token Notice

You will need both your API Token and your Call API SID (ACCOUNT_SID). Both are available in User Settings at the top right of the portal.

Section URI

https://v1.api19.com/call/2012-04-24/Accounts/ACCOUNT_SID/Calls.json

Supported Operations

HTTP GET Returns a list representation of all Call resources for this Account, including the properties above.

HTTP POST Makes a new Call and returns a representation of the Call resource, including the properties above

Request Parameters

Parameter	Description
From(Required)	The phone number to use as the caller id.
To (Required)	The phone number to call.
Url (Required)	The fully qualified URL that should be executed when the call connects.
Method	The HTTP method CallAPI should use when making its request to the above Url. Defaults to POST.
FallbackUrl	The URL that CallAPI will request if execution of Url fails for any reason.
FallbackMethod	The HTTP method that CallAPI should use to request the FallbackUrl. Must be either GET or POST. Defaults to POST.
StatusCallbackEvent	A comma separated list of events on which we are interested to get a callback on. Possible values are initiated, ringing, answered, completed. Defaults to none.
StatusCallback	URL to receive the callback events at. Defaults to none.
StatusCallbackMethod	Set to GET or POST. Defaults to POST.
Timeout	The number of seconds that CallAPI should allow the phone to ring before assuming there is no answer. Defaults to 60 seconds.

StatusCallbackEvent

When creating a Call using the Calls API, an outbound call is initiated. The call transitions from the initiated state to the ringing state when the phone starts ringing. It transitions to the answered state when the call is picked up, and finally to the completed state when the call is over. With StatusCallbackEvent, you can subscribe to receive webhooks for the different call progress events: initiated, ringing, answered, or completed for a given call.

The StatusCallbackEvent attribute allows you to specify which events CallAPI should webhook on. To specify multiple events separate them with a comma as follows: initiated,ringing,answered,completed. If a StatusCallback is provided and no status callback events are specified, the completed event will be sent by default..

initiated	The initiated event is fired when CallAPI starts dialing the call.
ringing	The ringing event is fired when the call starts ringing.
answered	The answered event is fired when the call is answered.
completed	The completed event is fired when the call is completed, regardless of the termination status: busy, canceled, completed, failed, or no-answer. If no StatusCallbackEvent is specified, completed will be fired by default.
VoicemailDetector	person_found or voicemail is sent if the original request had DetectVoicemail on it.

StatusCallback

The StatusCallback attribute allows you to specify a URL for CallAPI to send webhook requests to on each event specified in the StatusCallbackEvent attribute.

StatusCallbackMethod

The StatusCallbackMethod attribute allows you to specify which HTTP method CallAPI should use when requesting the URL in the StatusCallback attribute. The default is POST

Status Callback HTTP Parameters

The parameters CallAPI passes to your application in an asynchronous request to the StatusCallback URL include all parameters passed in a synchronous request to retrieve RCML when CallAPI receives a call to one of your CallAPI numbers. The full list of parameters and descriptions of each are in the RCML Voice Request documentation.

When the call progress events are fired, the Status Callback request also passes these additional parameters:

Parameter	Description
CallSid	A unique identifier for this call generated by CallAPI . You can use CallSid to modify the child call by POSTing to Calls/{CallSid} with a new RCML URL.
CallStatus	A descriptive status for the call. The value is one of queued, initiated, ringing, in-progress, busy, failed, or no-answer. See CallStatus for more details.
CallDuration	The duration of the just-completed call, in seconds. Only present in the completed event.
Timestamp	The timestamp when the event was fired, given as UTC in RFC 2822 format.
CallbackSource	A string that describes the source of the webhook. This is provided to help disambiguate why the webhook was made. On Status Callbacks, this value is always call-progress-events.
SequenceNumber	The order in which the events were fired, starting from 0. Although events are fired in order, they are made as separate HTTP requests and there is no guarantee they will arrive in the same order.

To redirect or terminate a live call, you make an HTTP POST request to an in¬-progress Call instance resource URI:

/call/2012-04-24/Accounts/{AccountSid}/Calls/{CallSid} 
or
/call/2012-04-24/Accounts/{AccountSid}/Calls.json/{CallSid}