API Resource: /calls

Our /calls service will be available soon! Read about call features and functions below but please don't try them out just yet.

The Phone.com API’s /calls service extends our flexible telephony features, letting you make and receive phone calls, and manage a variety of call events, in your applications. This topic provides a detailed reference to the /calls service.

In This Topic:


What Can I Do with /calls?

You can use our /calls service to do any of the following:

  • Initiate or answer a call
  • Play a pre-recorded greeting or convert text, on the fly, to an audio message
  • Receive or send DTMF (key entries on a touch-tone phone)
  • Place a call on hold and release that hold
  • Hang up, ending the call

Use these actions to schedule appointment reminder calls to your clients, manage calls across distributed sales or service teams, or deliver audio messages to your organizations members.

Call Settings in the Telephony Toolkit

Phone calls can either be made manually from your phone, or triggered by actions or events in your applications. For this reason, there are few active call functions in your Phone.com API Developer account settings.

Be sure, though, to set up a phone number (with extensions), as well as with any greetings, menus, queues and routes you plan to use in your application.

Working with the /calls API Resource

The /calls service can be invoked either synchronously or asynchronously. In synchronous mode, your application will send commands to the Phone.com API and then wait for a response. The API will validate and execute your commands and then reply to your request once all commands have been completed.

In asynchronous mode, your application will send commands to our API and immediately receive a response, which will either be a validation error or a confirmation of the receipt of commands. Our API server will then process your commands and initiate an HTTP POST to your fallback URL with the results, as well as certain details of the call.

We generally recommend using asynchronous mode for call control, as it provides the following advantages:

  • It allows you to schedule calls for a time point in the future
  • For requests where commands would take more than 30 seconds to execute, asynchronous mode removes the need to maintain a long-running synchronous HTTP connection to the API.

The /calls service also offers call specificity by adding the resource ID (UUID) of the call to the URL. Where an HTTP GET request to /calls would return a detailed list of all of your calls, an HTTP GET request to /calls/UUID will return detailed information only about the specific call represented by the resource ID.

Important: While Phone.com API features and services are available free of charge during Beta development, note that making API requests to the /calls service will incur costs associated with placing and receiving phone calls once the Beta period has passed.

Working with Call Objects

The /calls service returns the representation of a phone call in a standard format, regardless of the HTTP method being used. The call object consists of detailed attributes, such as status, scheduling, duration and keep-state data.

Sample Call Object

Here is an example of a call object, with all possible elements populated.


{
    "resource_id": "55bb5e92-7436-11e3-b573-d5e99f999999",
    "application_id": "4556e204-05de-11e3-bf32-cdee47777777",
    "to": "+15555552345",
    "from": "+15555551234",
    "status": "hangup",
    "hangup_cause": "command",
    "duration": 230,
    "schedule_start": "2013-12-24T03:16:25",
    "schedule_start_epoch": 1387854985,
    "schedule_end": "2013-12-24T03:20:49",
    "schedule_end_epoch": 1387855249,
    "time_start": "2013-12-24T03:16:29",
    "time_start_epoch": 1387854989,
    "time_end": "2013-12-24T03:20:19",
    "time_end_epoch": 1387855219,
    "keep-state": "eyAibXkiOiJiYXNlIDY0IGVuY29kZWQgSlNPTiBvYmplY3QiIH0="
}

Field Descriptions

Parameter Type Description
resource_id UUID Resource ID of the call
applications_id UUID Phone.com API Application Key for the application sending or receiving the call. This is the hexadecimal key that is automatically generated when you configure your application in your account.
to String Phone number that was called (E.164 format)
from String Phone number that originated the call (E.164 format)
direction String Direction of the call, either:
    inbound - application received the call from a remote party
    outbound - application called the remote party
status String Current status of the call, one of the following:
    scheduled - Call is scheduled to start in the future
    ringing - Inbound call has not yet been answered
    executing - Commands are being executed on the call
    ready - Call is ready to accept new commands
    hold - Call is currently on hold
    bridged - Call is bridged to menu, queue or other call
    hangup - Call is no longer active
hangup_cause String Reason the call ended, one of the following:
    command - Application sent the hangup command to end the call
    disconnect - Remote party ended the call
    canceled - Call was canceled before it began
    busy - Busy signal was received when dialing
    rejected - Remote party rejected the call
    no_answer - Remote party did not answer prior to timeout period
    timeout - Call was disconnected because no new commands were received
duration Integer Number of seconds the call was connected
schedule_start String Date/time the call was scheduled to begin (ISO 8601 format)
schedule_start_epoch Integer Date/time the call was scheduled to begin (Unix time format)
schedule_end String Date/time the request to dial a call would expire if it could not be processed (ISO 8601 format)
schedule_end_epoch Integer Date/time the request to dial a call would expire if it could not be processed (Unix time format)
time_start String Date/time the call was connected (ISO 8601 format)
time_start_epoch Integer Date/time the call was connected (Unix time format)
time_end String Date/time the call was ended (ISO 8601 format)
time_end_epoch Integer Date/time the call was ended (Unix time format)
keep-state String Your application can store its own data (for example, your call identifier, customer ID, etc.) using the keep-state field in a POST or PUT request. Your keep-state data will be returned in all subsequent communications. The maximum length of this data field is 8000 bytes. It is required that you use Base64 encoding to encode the data sent in this field, and it will be returned to you in Base64-encoded format.

POST /calls

Use POST /calls to create a new outbound call.

Example

POST https://v1.api.phone.com/calls

Note that the dial command must be specified as the first command in an HTTP POST. Also, the to parameter for the dial command must contain an E.164 formatted phone number. The from parameter must contain an E.164-formatted phone number that belongs to your Phone.com account.

Authentication

This method requires authentication.

Parameters

Parameter Type Description
async (Optional) Boolean This URL argument signifies that the HTTP request should be handled asynchronously.

Request Body Fields and Example

Field Type Description
commands Array of objects The commands array holds the list of commands to be executed. See Using Call Commands for a full list of supported commands. Note that the dial command must be the first command.
keep-state (Optional) String Use this string to store your own data for the call, such as your call identifier, customer ID, etc. This data will be returned with all subsequent responses and call events for this call. Maximum length for this data string is 8000 bytes. Must be Base64 encoded.
fallback_url (Optional) String Only applicable to asynchronous requests. Use this field to override the fallback URL to be used for responses to this request.

Sample POST /calls Request (PHP)


  <?php
  $request = <<<__REQUEST
  {
      "keep-state": "eyAibXkiOiJiYXNlIDY0IGVuY29kZWQgSlNPTiBvYmplY3QiIH0=",
      "commands": [
          {
              "dial": {
                  "to": "+15555552345",
                  "from": "+15555551234",
                  "timeout": 20
              }
          },
          {
              "say": {
                  "text": "This is a text to speech message."
              }
          }
      ]
  }
  __REQUEST;


  $url = "https://v1.api.phone.com/calls";

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, "<username>:<password>");
  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
  curl_setopt($ch, CURLOPT_POSTFIELDS, $request);
  curl_setopt($ch, CURLOPT_HEADER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER,
         array('Content-Type:application/json',
             'Content-Length: ' . strlen($request))
         );
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);


  $result = curl_exec($ch);
  $info = curl_getinfo($ch);
  curl_close($ch);

  print "HTTP Code: ".$info['http_code']."\n";
  print "Response: ". $result;
  ?>


Success Response

HTTP Code: 200 OK


Error Response

  • HTTP Code: TBD
  • HTTP Code: TBD

Response Fields for an Asynchronous Request

Field Type Description
service String This will always be calls when using the calls service
call Call object The call object

Response Body Example for an Asynchronous Request


{
    "response": {
        "service": "calls",
        "call": {
            "resource_id": "55bb5e92-7436-11e3-b573-d5e99f999999",
            "application_id": "4556e204-05de-11e3-bf32-cdee47777777",
            "to": "+15555552345",
            "from": "+15555551234",
            "direction": "outbound",
            "schedule_start": "2014-01-03T05:17:27",
            "schedule_start_epoch": 1388726247,
            "schedule_expire": "2014-01-03T05:32:27",
            "schedule_expire_epoch": 1388727147,
            "status": "scheduled"
        }
    }
}


Response Fields for a Synchronous Request

Field Type Description
service String This will always be calls when using the calls service
call Call object Details of the call. Includes values like keep-state and other information elements, like the scheduled start time and end time (if any), duration, to and from, as well as the current status.
commands Array of command results The commands array holds the list of the commands that were requested and the result of each. Each command includes an HTTP status code (for example, 200 for success) and the result (either OK or a more specific output).

Response Body Example for a Synchronous Request


{
    "response": {
        "service": "calls",
        "call": {
            "resource_id": "55bb5e92-7436-11e3-b573-d5e99f999999",
            "application_id": "4556e204-05de-11e3-bf32-cdee47777777",
            "to": "+15555552345",
            "from": "+15555551234",
            "duration": 9,
            "direction": "outbound",
            "schedule_start": "2014-01-03T05:17:27",
            "schedule_start_epoch": 1388726247,
            "schedule_expire": "2014-01-03T05:32:27",
            "schedule_expire_epoch": 1388727147,
            "time_start": "2014-01-03T05:17:29",
            "time_start_epoch": 1388726249,
            "status": "ready"
        },
        "commands": [
            {
                "command": "dial",
                "to": "+12345678900",
                "from": "+12345678901",
                "status": 200,
                "result": "ok"
            },
            {
                "command": "say",
                "text": "Some text to say",
                "status": 200,
                "result": "ok"
            }
        }
    ]
}


Back to Methods Available for /calls.


GET /calls

Use GET /calls to retrieve a list of calls in your account, both past and scheduled. Note that, by default, you can retrieve a maximum of 20 call objects per request. You can increase the number of returned objects to a maximum of up to 50 by setting the limit parameter, and you can set offset to page through all available objects.

Example

GET https://v1.api.phone.com/calls

Authentication

This method requires authentication.

Parameters

Parameter Type Description
status (Optional) String Retrieve calls matching a particular status
limit (Optional) Integer Limits the result set to the value provided, to a maximum of 50 call objects. If you do not specify a limit, GET requests have a default maximum of 20 objects returned.
offset (Optional) Integer Skips the specified number of call objects. Used to control paginated results. For example, GET /calls?offset=10 will skip over the first ten results returned from the command, and start with the 11th.
sort (Optional) String By default, call objects are listed starting with the most recent object. Specifying the sort order as asc switches that order to start with the oldest object first. Specify desc to switch the order back to the default behavior. Example: GET /calls?sort=asc.

Success Response

HTTP Code: 200 OK

Response Body Fields and Example

Field Type Description
service String This will always be calls when using the calls service
data String Array of call objects

Response Body Format Example

Example of the response body format for GET /calls.


{
    "response": {
        "service": "calls",
        "data": [
            {
                "resource_id": "55bb5e92-7436-11e3-b573-d5e99f999999",
                "application_id": "4556e204-05de-11e3-bf32-cdee47777777",
                "to": "+15555552345",
                "from": "+15555551234",
                "duration": 9,
                "direction": "outbound",
                "schedule_start": "2014-01-03T05:17:27",
                "schedule_start_epoch": 1388726247,
                "schedule_expire": "2014-01-03T05:32:27",
                "schedule_expire_epoch": 1388727147,
                "time_start": "2014-01-03T05:17:29",
                "time_start_epoch": 1388726249,
                "status": "ready"
            },
            {
                "resource_id": "55bb5e92-7436-11e3-b573-d5e99f999000",
                "application_id": "4556e204-05de-11e3-bf32-cdee47777777",
                "to": "+15555553456",
                "from": "+15555551234",
                "direction": "outbound",
                "schedule_start": "2014-01-03T05:17:29",
                "schedule_start_epoch": 1388726249,
                "schedule_expire": "2014-01-03T05:32:47",
                "schedule_expire_epoch": 1388727167,
                "status": "hangup",
                "hangup_cause": "canceled"
            },
        ]
    }
}

Error Response

HTTP Code: TBD

Sample GET /calls Request (PHP)

Note that using GET /calls will retrieve a list of past and scheduled call objects in your account.


<?php
$url = "https://v1.api.phone.com/calls";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "<username>:<password>");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$result = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);

print "HTTP Code: ".$info['http_code']."\n";
print "Response: ". $result;
?>

Back to Methods Available for /calls.


DELETE /calls

Use DELETE /calls to end all active calls and cancel all scheduled calls.

We strongly recommended that you avoid using DELETE /calls for day-to-day administration, as this method should only be used in scenarios where a large number of calls are submitted erroneously. Instead, to cancel specific calls, we suggest using individual DELETE /calls/UUID requests.

We also require that you include the delete_all argument with DELETE /calls to prevent you from deleting all of your calls by accident.

Example

DELETE https://v1.api.phone.com/calls?delete_all=1

Authentication

This method requires authentication.

Parameters

Parameter Type Description
delete_all (Required) Boolean Set to 1 to complete the operation

Success Response

HTTP Code: 200 OK

Error Response

  • HTTP Code: TBD

Sample DELETE /calls Request (PHP)

Note that you must supply the delete_all argument to prevent you from deleting all your scheduled call objects by accident.


<?php
$url = "https://v1.api.phone.com/calls?delete_all=1";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "<username>:<password>");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$result = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);

print "HTTP Code: ".$info['http_code']."\n";
?>

Back to Methods Available for /calls.


GET /calls/UUID

Use GET /calls/UUID to retrieve data about a specific call.

Example

GET https://v1.api.phone.com/calls/UUID

Authentication

This method requires authentication.

Success Response

HTTP Code: 200 OK

Response Body Fields and Example

Field Type Description
service String This will always be calls when using the calls service
data Call object The call object

Response Body Format Example


{
    "response": {
        "service": "calls",
        "data": {
            "resource_id": "55bb5e92-7436-11e3-b573-d5e99f999999",
            "application_id": "4556e204-05de-11e3-bf32-cdee47777777",
            "to": "+15555552345",
            "from": "+15555551234",
            "duration": 9,
            "direction": "outbound",
            "schedule_start": "2014-01-03T05:17:27",
            "schedule_start_epoch": 1388726247,
            "schedule_expire": "2014-01-03T05:32:27",
            "schedule_expire_epoch": 1388727147,
            "time_start": "2014-01-03T05:17:29",
            "time_start_epoch": 1388726249,
            "status": "ready"
        }
    }
}
            

Error Response

HTTP Code: TBD

Sample GET /calls/UUID Request (PHP)


<?php
$url = "https://v1.api.phone.com/calls/";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "<username>:<password>");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$result = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);

print "HTTP Code: ".$info['http_code']."\n";
print "Response: ". $result;
?>

Back to Methods Available for /calls.


PUT /calls/UUID

Use the PUT method to add executable commands to an active call.

Example

PUT https://v1.api.phone.com/calls/UUID

Authentication

This method requires authentication.

URL Parameters

Field Type Description
async (Optional) Boolean Signifies that the HTTP request should be handled asynchronously.

Request Body Fields

Field Type Description
commands Array of command objects Commands array holds the list of commands to be executed. For a full list of available commands, see Using Call Commands.
keep-state (Optional) String Use this string to store your own data for the call, such as your call identifier, customer ID, etc. This data will be returned with all subsequent responses and call events for this call. Maximum length for this data string is 8000 bytes. Must be Base64 encoded.
fallback_url (Optional) String This parameter only applies to asynchronous requests. Use it to override the fallback URL that will be used for responses to this request.

Success Response

HTTP Code: 200 OK


{
    "response": {
        "service": "calls",
        "call": {
                "resource_id": "55bb5e92-7436-11e3-b573-d5e99f999999",
                "application_id": "4556e204-05de-11e3-bf32-cdee47777777",
                "to": "+15555552345",
                "from": "+15555551234",
                "duration": 17,
                "direction": "outbound",
                "schedule_start": "2014-01-03T05:17:27",
                "schedule_start_epoch": 1388726247,
                "schedule_expire": "2014-01-03T05:32:27",
                "schedule_expire_epoch": 1388727147,
                "time_start": "2014-01-03T05:17:29",
                "time_start_epoch": 1388726249,
                "status": "ready"
        },
        "commands": [
            {
                "command": "play",
                "resource_id": "94f9e282-6e7b-409e-a7bf-875555555555",
                "status": 200,
                "result": "ok"
            }
        ]
    }
}

Error Response

  • HTTP Code: TBD

Sample PUT /calls/UUID Request (PHP)

The example below shows you how to use PUT /sms/UUID to update an SMS message scheduled to be delivered in the future.


<?php
$request = <<<__REQUEST
{
    "commands": [
        {
            "play": {
                "resource_id": "94f9e282-6e7b-409e-a7bf-875555555555"
            }
        }
    ]
}
__REQUEST;


$resource_id = "55bb5e92-7436-11e3-b573-d5e99f999999";

$url = "https://v1.api.phone.com/calls/".$resource_id;

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "<username>:<password>");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($ch, CURLOPT_POSTFIELDS, $request);
curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER,
       array('Content-Type:application/json',
           'Content-Length: ' . strlen($request))
       );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);


$result = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);

print "HTTP Code: ".$info['http_code']."\n";
print "Response: ". $result;

?>

Back to Methods Available for /calls.


DELETE /calls/UUID

Use DELETE /sms/UUID to to end an active call or cancel a scheduled call.

Example

DELETE https://v1.api.phone.com/calls/UUID

Authentication

This method requires authentication.

Success Response

HTTP Code: 200 OK

Error Response

  • HTTP Code: TBD

Sample DELETE /calls/UUID Request (PHP)


<?php
$resource_id = "80417048-ac3b-11e2-8b76-eea2f9d0a555";

$url = "https://v1.api.phone.com/calls/".$resource_id;

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "username:password");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$result = curl_exec($ch);
$info = curl_getinfo($ch);

curl_close($ch);

print "HTTP Code: ".$info['http_code']."\n";
print "Response: ". $result;
?>

Back to Methods Available for /calls.


Learn More: