Call

The following actions can be performed with the Call APIs:

  BaseURI: https://api.plivo.com/v1/Account/{auth_id}/Call

Make an Outbound Call

The following API enables you to make a single call or bulk outbound calls to real phone(s) or SIP endpoint(s).

  URI: https://api.plivo.com/v1/Account/{auth_id}/Call/
  Method: POST

Request

The following parameters are required to make an outbound call:

Required Parameters
Parameter Description
from The phone number to be used as the caller id (with the country code).For e.g, a USA caller id number could be, 15677654321, with '1' for the country code. Multiple numbers can be sent by using a delimiter. For e.g. 15677654321<12077657621<12047657621.
to The regular number(s) or sip endpoint(s) to call. Regular number must be prefixed with country code but without the ‘+’ sign). For e.g, to dial a number in the USA, the number could be, 15677654321, with '1' for the country code. Multiple numbers can be sent by using a delimiter. For e.g. 15677654321<12077657621<12047657621. Sip endpoints must be prefixed with 'sip:' E.g., sip:john1234@phone.plivo.com. To make bulk calls, the delimiter '<' is used. For eg. 15677654321<15673464321<sip:john1234@phone.plivo.com Yes, you can mix regular numbers and sip endpoints !
answer_url The URL invoked by Plivo when the outbound call is answered.

The following optional parameters can be specified when making an Outbound Call:

Optional Parameters
.
Parameter Description
answer_method The method used to call the answer_url. Defaults to POST.
ring_url The URL that is notified by Plivo when the call is ringing. Defaults not set.
ring_method The method used to call the ring_url. Defaults to POST.
hangup_url The URL that is notified by Plivo when the call hangs up. Defaults to answer_url.
hangup_method The method used to call the hangup_url. Defaults to POST.
fallback_answer_url Invoked by Plivo only if answer_url is unavailable or the XML response is invalid. Should contain a XML response.
fallback_method The method used to call the fallback_answer_url. Defaults to POST.
caller_name Caller name to use with the call.
send_digits Plivo plays DTMF tones when the call is answered. This is useful when dialing a phone number and an extension. Plivo will dial the number, and when the automated system picks up, sends the DTMF tones to connect to the extension. E.g. If you want to dial the 2410 extension after the call is connected, and you want to wait for a few seconds before sending the extension, add a few leading 'w' characters. Each 'w' character waits 0.5 second before sending a digit. Each 'W' character waits 1 second before sending a digit. You can also add the tone duration in ms by appending @duration after the string (default duration is 2000 ms). Eg. 1w2w3@1000 See the DTMF API for additional information.
send_on_preanswer If set to true and send_digits is also set, digits are sent when the call is in preanswer state. Defaults to false.
time_limit Schedules the call for hangup at a specified time after the call is answered. Value should be an integer > 0(in seconds).
hangup_on_ring Schedules the call for hangup at a specified time after the call starts ringing. Value should be an integer >= 0 (in seconds).
machine_detection Used to detect if the call has been answered by a machine. The valid values are true and hangup. Default time to analyze is 5000 milliseconds (or 5 seconds). You can change it with the machine_detection_time parameter. Note that no XML is processed during the analysis phase. If a machine is detected during the call and machine_detection is set to true, the Machine parameter will be set to true and will be sent to the answer_url, hangup_url, or any other URL that is invoked by the call. If a machine is detected during the call and machine_detection is set to hangup, the call hangs up immediately and a request is made to the hangup_url with the Machine parameter set to true
machine_detection_time Time allotted to analyze if the call has been answered by a machine. It should be an integer >= 2000 and <= 10000 and the unit is ms. The default value is 5000 ms.
sip_headers List of SIP headers in the form of 'key=value' pairs, separated by commas. E.g. head1=val1,head2=val2,head3=val3,...,headN=valN. The SIP headers are always prefixed with X-PH-. The SIP headers are present for every HTTP request made by the outbound call. Only [A-Z], [a-z] and [0-9] characters are allowed for the SIP headers key and value. Additionally, the '%' character is also allowed for the SIP headers value so that you can encode this value in the URL.
ring_timeout Determines the time in seconds the call should ring. If the call is not answered within the ring_timeout value or the default value of 120 s, it is canceled.

Response

HTTP Status: 200

JSON: 
{
  "message": "call fired",
  "request_uuid": "9834029e-58b6-11e1-b8b7-a5bd0e4e126f",
  "api_id": "97ceeb52-58b6-11e1-86da-77300b68f8bb"
}

Get All Call Details

The following API enables you to get information about all completed calls. The maximum number of results that can be fetched with a single API call is 20.

  URI: https://api.plivo.com/v1/Account/{auth_id}/Call/
  Method: GET

Parameters

There are no mandatory parameters specified for this API. The following optional parameters can be specified:

Optional Parameters
Parameter Description
subaccount The id of the subaccount, if call details of the subaccount is needed.
call_direction Filter the results by call direction. The valid inputs are inbound and outbound.
from_number Filter the results by the number from where the call originated. For example:
  • To filter out those numbers that contain a particular number sequence, use from_number={sequence}
  • To filter out a number that matches an exact number, use from_number={exact_number}
to_number Filter the results by the number to which the call was made. Tips to use this filter are:
  • To filter out those numbers that contain a particular number sequence, use to_number={sequence}
  • To filter out a number that matches an exact number, use to_number={exact_number}
bill_duration Filter the results according to billed duration. The value of billed duration is in seconds. The filter can be used in one of the following five forms:
  • bill_duration: Input the exact value. Eg:- to filter out calls that were exactly three minutes long, use bill_duration=180
  • bill_duration__gt: gt stands for greater than. Eg:- to filter out calls that were more than two hours in duration bill_duration__gt=7200
  • bill_duration__gte: gte stands for greater than or equal to. Eg:- to filter out calls that were two hours or more in duration bill_duration__gte=7200
  • bill_duration__lt: lt stands for lesser than. Eg:- to filter out calls that were less than seven minutes in duration bill_duration__lt=420
  • bill_duration__lte: lte stands for lesser than or equal to. Eg:- to filter out calls that were two hours or less in duration bill_duration__lte=7200
end_time Filter out calls according to the time of completion. The filter can be used in the following five forms:
  • end_time: The format expected is YYYY-MM-DD HH:MM[:ss[.uuuuuu]]. Eg:- To get all calls that ended at 2012-03-21 11:47[:30], use end_time=2012-03-21 11:47[:30]
  • end_time__gt: gt stands for greater than. The format expected is YYYY-MM-DD HH:MM[:ss[.uuuuuu]]. Eg:- To get all calls that ended after 2012-03-21 11:47, use end_time__gt=2012-03-21 11:47
  • end_time__gte: gte stands for greater than or equal. The format expected is YYYY-MM-DD HH:MM[:ss[.uuuuuu]]. Eg:- To get all calls that ended after or exactly at 2012-03-21 11:47[:30], use end_time__gte=2012-03-21 11:47[:30]
  • end_time__lt: lt stands for lesser than. The format expected is YYYY-MM-DD HH:MM[:ss[.uuuuuu]]. Eg:- To get all calls that ended before 2012-03-21 11:47, use end_time__lt=2012-03-21 11:47
  • end_time__gte: lte stands for lesser than or equal. The format expected is YYYY-MM-DD HH:MM[:ss[.uuuuuu]]. Eg:- To get all calls that ended before or exactly at 2012-03-21 11:47[:30], use end_time__lte=2012-03-21 11:47[:30]
Note: The above filters can be combined to get calls that ended in a particular time range. The timestamps need to be UTC timestamps.
limit Used to display the number of results per page. The maximum number of results that can be fetched is 20.
offset Denotes the number of value items by which the results should be offset. Eg:- If the result contains a 1000 values and limit is set to 10 and offset is set to 705, then values 706 through 715 are displayed in the results. This parameter is also used for pagination of the results.

Response

HTTP Status: 200

JSON: 
  {
    "call_duration": 3,
    "total_amount": "0.02000",
    "parent_call_uuid": null,
    "call_direction": "outbound",
    "to_number": "xxxxxxxxxx",
    "total_rate": "0.02000",
    "from_number": "xxxxxxxxx",
    "end_time": "2012-08-20T10:53:17",
    "call_uuid": "xxx-1111-xxxx-",
    "resource_uri": "/v1/Account/XXXXXXXXXXXXXXXX/Call/XXXX1/"
  },
  {
    "call_duration": 3,
    "total_amount": "0.02000",
    "parent_call_uuid": null,
    "call_direction": "inbound",
    "to_number": "xxxxxxxxx",
    "total_rate": "0.02000",
    "from_number": "xxxxxxxxx",
    "end_time": "2012-08-20T10:59:16",
    "call_uuid": "xxx-2222-xxxx-",
    "resource_uri": "/v1/Account/XXXXXXXXXXXXXXXX/Call/XXXX2/"
  },
  ...

Get Call Detail Record (CDR) Of a Call

  URI: https://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/
  Method: GET

Parameters

There are no mandatory parameters for this API. The following optional parameters can be specified:

Optional Parameters
Parameter Description
subaccount The id of the subaccount, if Call details of the subaccount is needed.
limit limit is the number of values shown per page when the results are fetched.
offset This parameter is also used for pagination of the results. offset is the number of pages by which the results should be offset. Eg:- If the result contains 1000 values and limit is set to 10 and offset is set to 7, then values 71 through 80 are displayed in the results.

Response

HTTP Status: 200

JSON: 
  For Inbound:
  {
    "call_duration": 4,
    "total_amount": "0.00400",
    "parent_call_uuid": null,
    "call_direction": "inbound",
    "to_number": "1xxxxxxxxx",
    "total_rate": "0.00400",
    "api_id": "xxxxxxxxxxxxxxxxxxxxxxxx",
    "from_number": "1xxxxxxxxx",
    "end_time": "2012-09-16T19:05:08",
    "call_uuid": "xxxxxx",
    "resource_uri": "/v1/Account/XXXXXXXXXXXXXXXX/Call/XXXX/"
  }

  For Outbound:
  {
    "call_duration": 3,
    "total_amount": "0.02000",
    "parent_call_uuid": null,
    "call_direction": "outbound",
    "to_number": "xxxxxxxxxx",
    "total_rate": "0.02000",
    "api_id": "xxxxxxxxxxxxxxxxxxxxxxxx",
    "from_number": "1xxxxxxxxx",
    "end_time": "2012-08-20T10:53:17",
    "call_uuid": "xxxxxx",
    "resource_uri": "/v1/Account/XXXXXXXXXXXXXXXX/Call/XXXX/"
  }

Get All Live Calls

Get all current active calls made from an account.

  URI: https://api.plivo.com/v1/Account/{auth_id}/Call/?status=live
  Method: GET
Parameters 
None

Response

HTTP Status: 200

JSON: 
{
  "api_id": "c9527676-5839-11e1-86da-6ff39efcb949",
  "calls": [
    "eac94337-b1cd-499b-82d1-b39bca50dc31",
    "0a70a7fb-168e-4944-a846-4f3f4d2f96f1"
  ]
}

Get Details Of a Live Call

Get information on an active call.

  URI: https://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/?status=live
  Method: GET
Parameters
None

Response

HTTP Status: 200

JSON: 
{
  direction: "inbound",
  from: "1212121212",
  call_status: "in-progress",
  api_id: "45223222-74f8-11e1-8ea7-12313806be9a",
  to: "121212121212",
  caller_name: "+19724390596",
  call_uuid: "6653422-91b6-4716-9fad-9463daaeeec2",
  session_start: "2012-03-23 14:49:39.722551"
}

Hangup A Specific Call

Hangup an incoming or outgoing call.

  URI: https://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/
  Method: DELETE
Parameters 
None

Response

HTTP Status: 204

Transfer a Call

This API enables an in-progress or active call to a different URL and fetch and execute XML from a new URL. If the call (the A leg) is in a Dial, you can also transfer the other party (the B leg) at the same time or only transfer the B leg to an URL. This is useful for many applications where you want to asynchronously change the behavior of a live call. For example, you can play music while the call is on hold, queue calls, transfer calls etc.

  URI: https://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/
  Method: POST

Parameters

There are no mandatory parameters for this API. The following optional parameters can be specified when you transfer a call:

Optional Parameters
Parameter Description
legs 'aleg', 'bleg' or 'both' Defaults to 'aleg' 'aleg' will transfer call_uuid 'bleg' will transfer the bridged leg (if found) of call_uuid 'both' will transfer call_uuid and bridged leg of call_uuid
aleg_url URL to transfer for 'aleg', if legs is 'aleg' or 'both', then aleg_url has to be specified.
aleg_method HTTP method to invoke aleg_url. Defaults to POST.
bleg_url URL to transfer for bridged leg, if legs is 'bleg' or 'both', then bleg_url has to be specified.
bleg_method HTTP method to invoke bleg_url. Defaults to POST.

Response

HTTP Status: 202

JSON: 
{
  "message": "call transfered",
  "api_id": "08c94608-58bd-11e1-86da-adf28403fe48"
}

Asynchronous Mode

All Plivo APIs can be invoked in asynchronous mode with the inclusion of the callback_url parameter. Note: In asynchronous mode, you will only get back a response with the api_id. The response is sent to the callback_url which is fired immediately after execution of the Plivo API. See API Request and API Response for more information.

Asynchronous Parameters
Parameter Description
callback_url The URL that is notified by the API when the response is available and to which the response is sent.
callback_method The method used to notify the callback_url URL. Defaults to POST.
Asynchronous Response

The Asynchronous Response is sent in json format in the response field.

See the API Response section for more information.

Developers

Navigation