Call

The Call API is one of the core APIs of the Plivo platform which lets you initiate outbound calls. It also lets you view live calls, retrive call logs and transfer ongoing calls to a different flow.

The following actions can be performed with the Call API

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).

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

Arguments

.
Parameter Description
from (mandatory) 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.
to (mandatory) 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 (mandatory) The URL invoked by Plivo when the outbound call is answered.
answer_method (optional) The method used to call the answer_url. Defaults to POST.
ring_url (optional) The URL that is notified by Plivo when the call is ringing. Defaults not set.
ring_method (optional) The method used to call the ring_url. Defaults to POST.
hangup_url (optional) The URL that is notified by Plivo when the call hangs up. Defaults to answer_url.
hangup_method (optional) The method used to call the hangup_url. Defaults to POST.
fallback_url (optional) Invoked by Plivo only if answer_url is unavailable or the XML response is invalid. Should contain a XML response.
fallback_method (optional) The method used to call the fallback_url. Defaults to POST.
caller_name (optional) Caller name to use with the call.
send_digits (optional) 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 (optional) 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 (optional) 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 (optional) Schedules the call for hangup at a specified time after the call starts ringing. Value should be an integer >= 0 (in seconds).
machine_detection (optional) 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 (optional) 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.
machine_detection_url (optional) A URL where machine detection parameters will be sent by Plivo. This parameter should be used to make machine detection asynchronous
machine_detection_method (optional) The HTTP method which will be used by Plivo to request the machine_detection_url. Defaults to POST.
sip_headers (optional) 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 (optional) 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 Code: 200

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

Asynchronous Machine Detection

Asynchronous machine detection can be set by including the machine_detection_url along with other parameters while firing the outbound call API. Plivo would run the machine detection in the background and on a successful match, we would make an HTTP request to the machine_detection_url. On detecting a machine successfully, Plivo would send a parameter Machine with the value true to the machine_detection_url. You can now make a decision based on this parameter. Ideally you should then use the Transfer API to change the flow of the call.

The following parameters would be sent on the request.

From
string The From number which is used to make the call.
Machine
boolean This parameter will be true if a machine has been detected on the call.
To
string The number which is being called.
RequestUUID
string The request UUID of the call. You can uniquely identify the call using this ID.
ALegRequestUUID
string If the call has 2 legs, in the case where you call a number and then connect them to a different number or a SIP endpoint. The first call will be the A-Leg. This ID lets you identify the first call.
CallUUID
string The ID of the call.
IfMachine
string This parameter can either be continue or hangup depending on the machine_detection parameter set during the API call.
Direction
string The direction of the call. This parameter will always have the value outbound, since currently we support machine detection only on outbound calls.
ALegUUID
string The call UUID of the A-Leg.
Event
string The event of the notification. This parameter will always have the value MachineDetection.
CallStatus
string The status of the call. This will hold the value of in-progress.

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.

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

Arguments

Parameter Description
subaccount (optional) The id of the subaccount, if call details of the subaccount is needed.
call_direction (optional) Filter the results by call direction. The valid inputs are inbound and outbound.
from_number (optional) 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 (optional) 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 (optional) 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 (optional) 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 (optional) Used to display the number of results per page. The maximum number of results that can be fetched is 20.
offset (optional) 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 Code: 200

{
    "api_id": "f83e92c4-10d0-11e4-80aa-12313f048015",
    "meta": {
        "limit": 20,
        "next": "/v1/Account/MANWVLYTK4ZWU1YTY4ZT/Call/?limit=20&offset=20",
        "offset": 0,
        "previous": null,
        "total_count": 62
    },
    "objects": [
        {
            "bill_duration": 924,
            "billed_duration": 960,
            "call_direction": "inbound",
            "call_duration": 924,
            "call_uuid": "f86104c0-0e9c-11e4-90d1-2fd63e118d10",
            "end_time": "2014-07-18 22:45:36+05:30",
            "from_number": "14158572518",
            "parent_call_uuid": null,
            "resource_uri": "/v1/Account/MANWVLYTK4ZWU1YTY4ZT/Call/f86104c0-0e9c-11e4-90d1-2fd63e118d10/",
            "to_number": "14153268174",
            "total_amount": "0.13600",
            "total_rate": "0.00850"
        },
        {
            "bill_duration": 986,
            "billed_duration": 1020,
            "call_direction": "inbound",
            "call_duration": 986,
            "call_uuid": "d13c703c-0e9c-11e4-bc97-7163e387dbe8",
            "end_time": "2014-07-18 22:45:34+05:30",
            "from_number": "sip:bridge131106050456@phone.plivo.com",
            "parent_call_uuid": null,
            "resource_uri": "/v1/Account/MANWVLYTK4ZWU1YTY4ZT/Call/d13c703c-0e9c-11e4-bc97-7163e387dbe8/",
            "to_number": "sip:conference@phone.plivo.com",
            "total_amount": "0.05100",
            "total_rate": "0.00300"
        }
    ]
}

Get Call Detail Record Of a Call

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

Arguments

Parameter Description
subaccount (optional) The id of the subaccount, if Call details of the subaccount is needed.
limit (optional) limit is the number of values shown per page when the results are fetched.
offset (optional) 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 Code: 200

{
    "api_id": "723bbc28-10d1-11e4-bd8a-12313f016a39",
    "bill_duration": 924,
    "billed_duration": 960,
    "call_direction": "inbound",
    "call_duration": 924,
    "call_uuid": "f86104c0-0e9c-11e4-90d1-2fd63e118d10",
    "end_time": "2014-07-18 22:45:36+05:30",
    "from_number": "14158572518",
    "parent_call_uuid": null,
    "resource_uri": "/v1/Account/MANWVLYTK4ZWU1YTY4ZT/Call/f86104c0-0e9c-11e4-90d1-2fd63e118d10/",
    "to_number": "14153268174",
    "total_amount": "0.13600",
    "total_rate": "0.00850"
}

Get All Live Calls

Get all current active calls made from an account.

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

Arguments

None

Response

HTTP Status Code: 200

{
  "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.

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

Arguments

None

Response

HTTP Status Code: 200

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

Hangup A Specific Call

Hangup an incoming or outgoing call. If you are looking to hangup an incoming call without answering it, checkout the Hangup XML

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

Arguments

None

Response

HTTP Status Code: 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.

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

Arguments

Parameter Description
legs (optional) 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 (optional) URL to transfer for aleg, if legs is aleg or both, then aleg_url has to be specified.
aleg_method (optional) HTTP method to invoke aleg_url. Defaults to POST.
bleg_url (optional) URL to transfer for bridged leg, if legs is bleg or both, then bleg_url has to be specified.
bleg_method (optional) HTTP method to invoke bleg_url. Defaults to POST.

Response

HTTP Status Code: 202

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