Calls - Plivo

A Call object is created when an outbound call is initiated or when an inbound call is received. Use the Call API to initiate outbound calls, retrieve call details, control ongoing calls, and build custom call flows.

The Call Object

Attributes

call_uuid

string

Unique identifier for the call.

from_number

string

Caller ID used to initiate the call.

to_number

string

Number to which the call was initiated.

call_direction

string

Direction of the call. Values: outbound, inbound.

answer_time

string

Timestamp when the call was answered. Format: yyyy-MM-dd HH:mm:ss

end_time

string

Timestamp when the call ended. Format: yyyy-MM-dd HH:mm:ss

initiation_time

string

Timestamp when the call was initiated. Format: yyyy-MM-dd HH:mm:ss

call_duration

integer

Duration of the call in seconds.

bill_duration

integer

The duration of the call in seconds.

billed_duration

integer

The billed duration of the call in seconds. May differ from bill_duration depending on the billing interval.

total_amount

string

Total amount charged for the call.

total_rate

string

Per-minute rate based on the destination number.

parent_call_uuid

string

UUID of the A-leg of the call.

hangup_cause_name

string

Reason the call was hung up. See hangup causes

hangup_cause_code

integer

Integer code for the hangup cause.

hangup_source

string

Entity that triggered the hangup. Values: Caller, Callee, Plivo, API Request, Answer XML, Error, Unknown.

stir_verification

string

STIR/SHAKEN attestation info. Values: Verified, Not Verified, Not Applicable. Read more

source_ip

string

IP address from which the call request originated.

resource_uri

string

URI of the requested resource.

Example Call Object

{
  "answer_time": "2022-06-28 19:39:05+05:30",
  "bill_duration": 11,
  "billed_duration": 60,
  "call_direction": "inbound",
  "call_duration": 11,
  "call_uuid": "57a1b60a-5c0b-11e7-9082-ef888d0400e9",
  "end_time": "2022-06-28 19:39:15+05:30",
  "from_number": "12025551111",
  "initiation_time": "2022-06-28 19:39:04+05:30",
  "parent_call_uuid": null,
  "resource_uri": "/v1/Account/MA2025RK4E639VJFZAGV/Call/57a1b60a-5c0b-11e7-9082-ef888d0400e9/",
  "to_number": "19172592277",
  "total_amount": "0.00850",
  "total_rate": "0.00850",
  "hangup_cause_name": "End Of XML Instructions",
  "hangup_cause_code": 4010,
  "hangup_source": "Plivo",
  "source_ip": "92.168.0.1"
}

Billing

Plivo bills for voice calls based on the answered call duration.

When Billing Starts

Scenario	Billing
Call answered	Billing starts when the call is answered. Minimum charge is 60 seconds (1-minute increment).
Call not answered	No charge. Unanswered calls (busy, no answer, rejected) are not billed.
Call failed	No charge. Failed calls due to network issues or invalid numbers are not billed.
Voicemail detected	Billed if the call is answered (even by voicemail). Use machine detection to hang up on voicemail.

Understanding CDR Fields

bill_duration: Actual call duration in seconds
billed_duration: Duration rounded to billing increment (typically 60 seconds)
total_amount: Charge for the call based on billed_duration × total_rate

Inbound calls to Plivo numbers are billed when answered. Outbound calls are billed when the destination answers. If a call is forwarded via <Dial>, both legs (A-leg and B-leg) are billed separately once each is answered.

See Voice Pricing for current per-minute rates.

Create a Call

Initiate an outbound call to a PSTN number or SIP endpoint. You can make simultaneous bulk calls by specifying multiple destinations.

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

Arguments

from

string

required

Caller ID phone number in E.164 format (e.g., 14157654321).

string

required

Destination number(s) or SIP URI(s). Use < to separate multiple destinations (max 1000).

answer_url

string

required

URL called when the call is answered. Must return valid Plivo XML.

answer_method

string

HTTP verb for answer_url. Default: POST.

ring_url

string

URL notified when the call starts ringing.

ring_method

string

HTTP verb for ring_url. Default: POST.

hangup_url

string

URL notified when the call is hung up.

hangup_method

string

HTTP verb for hangup_url. Default: POST.

fallback_url

string

Invoked if answer_url fails after 3 retries or 60s timeout.

fallback_method

string

HTTP verb for fallback_url. Default: POST.

caller_name

string

Sets caller name (up to 50 characters).

send_digits

string

Sends DTMF digits after call is connected. Use w (0.5s wait) or W (1s wait).

send_on_preanswer

boolean

If true, sends send_digits during pre-answer. Default: false.

time_limit

integer

Max duration of call in seconds. Default: 14400 (4 hours).

hangup_on_ring

integer

Max duration (in seconds) from start of ringing to hangup.

machine_detection

string

Detect machine on answer. Values: true, hangup.

machine_detection_time

integer

Time in ms to detect machine. Default: 5000. Range: 2000–10000.

machine_detection_url

string

Callback URL for asynchronous machine detection.

machine_detection_method

string

HTTP verb for machine_detection_url. Default: POST.

Callbacks

ring_url parameters

Parameter	Type	Description
`From`	`string`	The from number used as the caller ID.
`To`	`string`	The destination that’s called.
`RequestUUID`	`string`	Unique identifier for the request.
`CallUUID`	`string`	The identifier of the call.
`Direction`	`string`	The direction of the call (`outbound`).
`Event`	`string`	Event that triggered this notification (`Ring`).
`CallStatus`	`string`	Status of the call (`ringing`).
`SessionStart`	`string`	Timestamp when early media started (UTC).
`STIRAttestation`	`string`	Attestation assigned to the call by Plivo.

answer_url / fallback_url parameters

Parameter	Type	Description
`From`	`string`	The from number used as the caller ID.
`To`	`string`	The destination that’s called.
`CallerName`	`string`	Name of the caller (if SIP call).
`RequestUUID`	`string`	Unique identifier for the call.
`CallUUID`	`string`	The identifier of the call.
`Direction`	`string`	Direction of the call (`outbound`).
`Event`	`string`	Event that triggered this notification (`StartApp`).
`STIRVerification`	`string`	STIR/SHAKEN verification status.
`CallStatus`	`string`	Status of the call (`in-progress`).
`SessionStart`	`string`	Timestamp when early media started (UTC).

hangup_url parameters

Parameter	Type	Description
`From`	`string`	The from number used as the caller ID.
`To`	`string`	The destination that’s called.
`RequestUUID`	`string`	Unique identifier for the call.
`CallUUID`	`string`	The identifier of the call.
`Direction`	`string`	Direction of the call (`outbound`).
`Event`	`string`	Event that triggered this notification (`Hangup`).
`CallStatus`	`string`	Status of the call (`completed`).
`StartTime`	`string`	Timestamp when the call was initiated.
`AnswerTime`	`string`	Timestamp when the call was answered.
`EndTime`	`string`	Timestamp when the call ended.

import plivo

client = plivo.RestClient('<auth_id>','<auth_token>')
response = client.calls.create(
    from_='+12025550000',
    to_='+12025551111',
    answer_url='https://s3.amazonaws.com/static.plivo.com/answer.xml',
    answer_method='GET')
print(response)

Response

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

Retrieve a Call

Get the call detail record (CDR) of a specific call.

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

Arguments

No arguments required.

import plivo

client = plivo.RestClient('<auth_id>','<auth_token>')
response = client.calls.get(call_uuid='10f0cb68-7533-45ed-acb5-87ceac29ee48')
print(response)

Response

{
    "answer_time": "2022-10-12 21:57:47+05:30",
    "api_id": "52cd2e1d-2bfd-11ec-a7bd-0242ac110005",
    "bill_duration": 1,
    "billed_duration": 1,
    "call_direction": "outbound",
    "call_duration": 1,
    "call_state": "ANSWER",
    "call_uuid": "5607532d-5037-4066-befc-a8b40218dd4f",
    "from_number": "+12025551111",
    "hangup_cause_code": 8011,
    "hangup_cause_name": "Invalid Answer XML",
    "hangup_source": "Error",
    "initiation_time": "2022-10-12 21:57:40+05:30",
    "to_number": "sip:[email protected]",
    "total_amount": "0.01667",
    "total_rate": "1.00000",
    "source_ip": "92.168.0.1"
}

List All Calls

Retrieve details of all completed calls. Maximum 20 results per request.

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

Arguments

from_number

string

Filter by the number from which calls were made.

to_number

string

Filter by the destination number of the call.

call_direction

string

Filter by direction. Values: inbound, outbound.

bill_duration

integer

Filter by billed duration. Supports variants: bill_duration__gt, bill_duration__gte, bill_duration__lt, bill_duration__lte.

end_time

string

Filter by end time. Format: YYYY-MM-DD HH:MM[:ss[.uuuuuu]]. Supports variants: end_time__gt, end_time__gte, end_time__lt, end_time__lte.

hangup_cause_code

integer

Filter by hangup cause code.

hangup_source

string

Filter by hangup source. Values: customer, carrier, zentrunk.

stir_verification

string

Filter by STIR/SHAKEN status. Values: Verified, Not Verified, Not Applicable.

limit

integer

Number of results to return. Max: 20. Default: 20.

offset

integer

Number of items to skip for pagination.

Only calls from the last 90 days can be retrieved. If no end_time filter is specified, Plivo searches the last 7 days. The maximum search range is 30 days.

import plivo

client = plivo.RestClient('<auth_id>','<auth_token>')
response = client.calls.list(limit=5, offset=0)
print(response)

Response

{
  "api_id": "8299d094-dc72-11e5-b56c-22000ae90795",
  "meta": {
    "limit": 20,
    "next": null,
    "offset": 0,
    "previous": null,
    "total_count": 4
  },
  "objects": [
    {
      "call_uuid": "5607532d-5037-4066-befc-a8b40218dd4f",
      "call_direction": "outbound",
      "from_number": "+12025551111",
      "to_number": "+12025552222",
      "call_duration": 1,
      "total_amount": "0.01667"
    }
  ]
}

Retrieve a Live Call

Get details of a specific ongoing call.

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

import plivo

client = plivo.RestClient('<auth_id>','<auth_token>')
response = client.live_calls.get('10f0cb68-7533-45ed-acb5-87ceac29ee48')
print(response)

Response

{
  "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": "2021-03-23 14:49:39.722551"
}

List All Live Calls

Retrieve IDs of all ongoing calls.

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

import plivo

client = plivo.RestClient('<auth_id>','<auth_token>')
response = client.live_calls.list_ids()
print(response)

Response

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

List All Queued Calls

Retrieve IDs of all queued calls. Maximum 20 results per request.

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

import plivo

client = plivo.RestClient('<auth_id>','<auth_token>')
response = client.queued_calls.list_ids()
print(response)

Response

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

Hang Up a Call

Hang up an ongoing call or cancel a queued outbound call.

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

If call_uuid is not specified, all ongoing calls in the account will be disconnected.

import plivo

client = plivo.RestClient('<auth_id>','<auth_token>')
response = client.calls.delete(call_uuid='3a2e4c90-dcee-4931-8a59-f123ab507e60')
print(response)

Response

HTTP Status Code: 204

Transfer a Call

Transfer an in-progress call to fetch and execute XML from a different URL. This enables you to change call behavior asynchronously—for example, to play music while a call is on hold, queue calls, or transfer calls.

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

Arguments

legs

string

Which leg(s) to transfer. Values: aleg, bleg, both.

aleg_url

string

URL to fetch XML from for the A leg. Required if legs is aleg or both.

aleg_method

string

HTTP verb for aleg_url. Default: POST.

bleg_url

string

URL to fetch XML from for the B leg. Required if legs is bleg or both.

bleg_method

string

HTTP verb for bleg_url. Default: POST.

import plivo

client = plivo.RestClient('<auth_id>','<auth_token>')
response = client.calls.transfer(
    legs='aleg',
    aleg_url='https://aleg.url',
    call_uuid='1ed7fd89-df77-4ebf-8196-d5cf7222c918')
print(response)

Response

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

Record a Call

Start Recording
Stop Recording

Start recording an active call.

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

Arguments

time_limit

integer

Max recording duration in seconds. Default: 60.

file_format

string

Recording format. Values: mp3, wav. Default: mp3.

transcription_type

string

Set to auto for automated transcription.

transcription_url

string

URL to receive transcription results.

callback_url

string

URL invoked when recording ends.

callback_method

string

HTTP verb for callback_url. Default: POST.

record_channel_type

string

Recording channel. Values: mono, stereo. Default: mono.

Transcription is available only in English and limited to calls with duration greater than 500ms and less than 4 hours, with file size under 2GB.

Callback URL parameters

Parameter	Type	Description
`api_id`	`string`	The API ID returned by the Record API.
`record_url`	`string`	URL where the recorded file can be accessed.
`call_uuid`	`string`	The call UUID of the recorded call.
`recording_id`	`string`	The recording ID.
`recording_duration`	`integer`	Recording duration in seconds.
`recording_duration_ms`	`integer`	Recording duration in milliseconds.
`recording_start_ms`	`integer`	Start time of recording (epoch ms).
`recording_end_ms`	`integer`	End time of recording (epoch ms).

import plivo

client = plivo.RestClient('<auth_id>','<auth_token>')
response = client.calls.record(call_uuid='3a2e4c90-dcee-4931-8a59-f123ab507e60')
print(response)

Response

{
  "url": "http://s3.amazonaws.com/recordings_2013/48dfaf60-3b2a-11e3.mp3",
  "message": "call recording started",
  "recording_id": "48dfaf60-3b2a-11e3",
  "api_id": "c7b69074-58be-11e1-86da-adf28403fe48"
}

Stop active recordings on a call.

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

Arguments

URL

string

Specify a record URL to stop only one recording. By default, all recordings are stopped.

import plivo

client = plivo.RestClient('<auth_id>','<auth_token>')
response = client.calls.record_stop(call_uuid='3a2e4c90-dcee-4931-8a59-f123ab507e60')
print(response)

Response

HTTP Status Code: 204

Play Audio

Start Playing
Stop Playing

Play an audio file during an active call. Supports .mp3 and .wav files.

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

Arguments

urls

string

required

URL or comma-separated URLs to .mp3 or .wav files.

length

integer

Max playback length in seconds.

legs

string

Call leg to play audio. Values: aleg, bleg, both. Default: aleg.

loop

boolean

If true, audio plays indefinitely. Default: false.

mix

boolean

If true, call and audio are mixed. If false, participants can’t hear each other during playback. Default: true.

import plivo

client = plivo.RestClient('<auth_id>','<auth_token>')
response = client.calls.play(
    call_uuid='bc480f62-6d99-469e-b80e-090e620de824',
    urls='https://s3.amazonaws.com/plivocloud/music.mp3')
print(response)

Response

{
  "message": "play started",
  "api_id": "07abfd94-58c0-11e1-86da-adf28403fe48"
}

Stop playing audio during an active call.

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

import plivo

client = plivo.RestClient('<auth_id>','<auth_token>')
response = client.calls.play_stop(call_uuid='bc480f62-6d99-469e-b80e-090e620de824')
print(response)

Response

HTTP Status Code: 204

Speak Text

Start Speaking
Stop Speaking

Speak text during an active call using text-to-speech.

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

Arguments

text

string

required

Text to be spoken.

voice

string

Voice type. Values: MAN, WOMAN. Default: WOMAN.

language

string

Language code. Default: en-US.

legs

string

Call leg. Values: aleg, bleg, both. Default: aleg.

loop

boolean

If true, text repeats until stopped. Default: false.

mix

boolean

If true, call and speech are mixed. Default: true.

Supported Languages

Language	Code	Available Voices
Arabic	`arb`	`WOMAN` only
Chinese Mandarin	`cmn-CN`	`WOMAN` only
Danish (Denmark)	`da-DK`	`WOMAN`, `MAN`
Dutch (Netherlands)	`nl-NL`	`WOMAN`, `MAN`
English (Australia)	`en-AU`	`WOMAN`, `MAN`
English (India)	`en-IN`	`WOMAN` only
English (UK)	`en-GB`	`WOMAN`, `MAN`
English (US)	`en-US`	`WOMAN`, `MAN`
French (Canada)	`fr-CA`	`WOMAN` only
French (France)	`fr-FR`	`WOMAN`, `MAN`
German (Germany)	`de-DE`	`WOMAN`, `MAN`
Hindi (India)	`hi-IN`	`WOMAN` only
Italian (Italy)	`it-IT`	`WOMAN`, `MAN`
Japanese (Japan)	`ja-JP`	`WOMAN`, `MAN`
Korean (South Korea)	`ko-KR`	`WOMAN` only
Portuguese (Brazil)	`pt-BR`	`WOMAN`, `MAN`
Portuguese (Portugal)	`pt-PT`	`WOMAN`, `MAN`
Russian (Russia)	`ru-RU`	`WOMAN`, `MAN`
Spanish (Mexico)	`es-MX`	`WOMAN` only
Spanish (Spain)	`es-ES`	`WOMAN`, `MAN`
Spanish (US)	`es-US`	`WOMAN`, `MAN`

import plivo

client = plivo.RestClient('<auth_id>','<auth_token>')
response = client.calls.speak(
    call_uuid='3a2e4c90-dcee-4931-8a59-f123ab507e60',
    text='Hello World')
print(response)

Response

{
  "message": "speak started",
  "api_id": "07abfd94-58c0-11e1-86da-adf28403fe48"
}

Stop active text-to-speech during a call.

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

import plivo

client = plivo.RestClient('<auth_id>','<auth_token>')
response = client.calls.speak_stop(call_uuid='3a2e4c90-dcee-4931-8a59-f123ab507e60')
print(response)

Response

{
    "message": "speak stopped",
    "api_id": "cf2359c8-f4d6-11e6-b886-067c5485c240"
}

Send DTMF

Send DTMF digits on an active call. Use this to programmatically navigate external IVR systems or interact with automated phone menus.

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

Common Use Cases

Navigate external IVRs: When your call connects to a bank, support line, or other automated system that prompts “Press 1 for sales, 2 for support…”
Enter PINs or account numbers: Automatically input credentials when connecting to voicemail or secure systems
Automated testing: Test your own IVR flows programmatically

Arguments

digits

string

required

Digits to send over the call.

leg

string

Call leg to send DTMF. Values: aleg, bleg. Default: aleg.

aleg: The first party (caller). Use when sending digits to an outbound call you initiated.
bleg: The second party (callee). Use when sending digits to a call connected via <Dial>.

import plivo

client = plivo.RestClient('<auth_id>','<auth_token>')
response = client.calls.send_digits(
    call_uuid='eba53b9e-8fbd-45c1-9444-696d2172fbc8',
    digits='123')
print(response)

Response

{
  "message": "digits sent",
  "api_id": "07abfd94-58c0-11e1-86da-adf28403fe48"
}

Getting Started

Concepts

API Reference

XML Reference

SDKs

Troubleshooting

Voice Tutorials

Migration Guides

​The Call Object

​Attributes

​Example Call Object

​Billing

​When Billing Starts

​Understanding CDR Fields

​Create a Call

​Arguments

​Callbacks

​Response

​Retrieve a Call

​Arguments

​Response

​List All Calls

​Arguments

​Response

​Retrieve a Live Call

​Response

​List All Live Calls

​Response

​List All Queued Calls

​Response

​Hang Up a Call

​Response

​Transfer a Call

​Arguments

​Response

​Record a Call

​Arguments

​Response

​Arguments

​Response

​Play Audio

​Arguments

​Response

​Response

​Speak Text

​Arguments

​Response

​Response

​Send DTMF

​Common Use Cases

​Arguments

​Response

The Call Object

Attributes

Example Call Object

Billing

When Billing Starts

Understanding CDR Fields

Create a Call

Arguments

Callbacks

Response

Retrieve a Call

Arguments

Response

List All Calls

Arguments

Response

Retrieve a Live Call

Response

List All Live Calls

Response

List All Queued Calls

Response

Hang Up a Call

Response

Transfer a Call

Arguments

Response

Record a Call

Arguments

Response

Arguments

Response

Play Audio

Arguments

Response

Response

Speak Text

Arguments

Response

Response

Send DTMF

Common Use Cases

Arguments

Response