> ## Documentation Index
> Fetch the complete documentation index at: https://plivo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Calls

> Create, retrieve, and manage voice calls programmatically

> [!NOTE]
>
> Use the Call API to make outbound calls, retrieve call details, and control live calls — record, play audio, speak text, send DTMF, transfer, or hang up. On completed calls, use `hangup_cause_name` to determine the outcome.

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.

**from\_iso** `string`

ISO 3166-1 alpha-2 country code of the caller number. Example: `US`.

**to\_iso** `string`

ISO 3166-1 alpha-2 country code of the destination number. Example: `US`.

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

**ring\_duration** `integer`

Time the call spent ringing before being answered, 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.

**conference\_uuid** `string`

UUID of the conference this call was part of. `null` if the call did not join a conference.

**hangup\_cause\_name** `string`

Reason the call was hung up. [See hangup causes](https://plivo.com/docs/voice/troubleshooting/hangup-causes.md)

**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`.

**call\_state** `string`

Legacy field retained for backward compatibility. Values: `ANSWER`, `EARLY MEDIA`, `DELAYED NEGOTIATION`. Don't use this field in your application logic — use `hangup_cause_name` to determine the call outcome.

**stir\_verification** `string`

STIR/SHAKEN attestation info. Values: `Verified`, `Not Verified`, `Not Applicable`. [Read more](https://plivo.com/docs/voice/concepts/stir-shaken.md)

**stir\_attestation** `string`

STIR/SHAKEN attestation level assigned to the call. Values: `A`, `B`, `C`. [Read more](https://plivo.com/docs/voice/concepts/stir-shaken.md)

**source\_ip** `string`

IP address from which the call request originated.

**resource\_uri** `string`

URI of the requested resource.

### Example Call Object

```json theme={null}
{
  "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](https://plivo.com/docs/voice/concepts/machine-detection.md) 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`

> [!NOTE]
>
> 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](https://www.plivo.com/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.

```text theme={null}
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`).

**to** `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`.

**sip\_headers** `string`

Custom SIP headers in `key=value` format, separated by commas. Headers are prefixed with `X-PH-` on the outbound INVITE by default. When the originating leg uses SIP authentication, headers are forwarded bare (without the `X-PH-` prefix). Headers with reserved prefixes (`PH-`, `Plivo`, `FS-`, `SipAuth`, `ZT-`, `Twilio`) and the name `ClientRegion` are silently dropped. See [SIP Authentication](https://plivo.com/docs/voice/concepts/sip-authentication.md) for details.

**sip\_auth\_username** `string`

SIP digest authentication username. Used when calling a SIP URI that requires authentication (the remote provider responds with 401/407 challenge). Only accepted when `to` is a SIP URI. Must be provided together with `sip_auth_password`. See [SIP Authentication](https://plivo.com/docs/voice/concepts/sip-authentication.md).

**sip\_auth\_password** `string`

SIP digest authentication password. 8-128 characters, must include uppercase, lowercase, and digit. Required when `sip_auth_username` is provided. Credentials are never logged, never included in CDR data, and never sent to your callback URLs.

**Outbound auth outcomes:**

| HangupCauseName | Code | CallStatus | Meaning |
| - | - | - | - |
| `sip_auth_failed` | `4240` | `failed` | Remote provider rejected the credentials |
| `sip_auth_timeout` | `4250` | `timeout` | Remote provider did not respond to the auth challenge |

**ring\_timeout** `integer`

Maximum time in seconds to ring the destination before timing out.

**parent\_call\_uuid** `string`

UUID of the parent call, used for call routing and tracking.

**parent\_auth\_id** `string`

Auth ID of the parent account.

**error\_if\_parent\_not\_found** `boolean`

When `true`, returns an error if the parent call is not found. Default: `false`.

**call\_type** `string`

Type of call. Values: `voice`, `whatsapp_voice`. Default: `voice`. When set to `whatsapp_voice`, the call is placed as a WhatsApp voice call. See [WhatsApp Calling](https://plivo.com/docs/messaging/concepts/whatsapp/whatsapp-calling.md) for details.

**delimiter** `string`

Delimiter character for separating multiple destination numbers in bulk calls. Default: `<`.

#### Advanced Machine Detection Parameters

These parameters provide fine-grained control over answering machine detection behavior. They work in conjunction with the `machine_detection` parameter above.

**machine\_detection\_maximum\_speech\_length** `integer`

Maximum duration of speech in milliseconds to analyze before making a determination. Range: `1000`–`6000`.

**machine\_detection\_initial\_silence** `integer`

Duration of initial silence in milliseconds before the call is classified. Range: `2000`–`10000`.

**machine\_detection\_maximum\_words** `integer`

Maximum number of words to listen for before making a determination. Range: `2`–`10`.

**machine\_detection\_initial\_greeting** `integer`

Maximum duration of the initial greeting in milliseconds to analyze. Range: `1000`–`5000`.

**machine\_detection\_silence** `integer`

Duration of silence in milliseconds after speech that indicates end of greeting. Range: `500`–`5000`.

**machine\_detection\_answer\_time** `integer`

Total time in milliseconds allotted for machine detection analysis. Range: `100`–`45000`.

### Callbacks

> [accordion] 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. |

> [accordion] 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). |

> [accordion] 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. |
> | `CarrierFailoverTriggered` | `string` | Sent as `true` only when Plivo attempted an [automatic carrier failover](https://plivo.com/docs/voice/concepts/carrier-failover.md) on the call. Omitted otherwise — never sent as `false`. Appears only in this callback; the Call Details API doesn't return it. |

```python Python theme={null}
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)
```

```ruby Ruby theme={null}
require 'plivo'

api = Plivo::RestClient.new("<auth_id>","<auth_token>")
response = api.calls.create(
  '+12025550000',
  ['+12025551111'],
  'https://s3.amazonaws.com/static.plivo.com/answer.xml',
  { answer_method: "GET" }
)
puts response
```

```javascript Node theme={null}
const plivo = require('plivo');

const client = new plivo.Client("<auth_id>","<auth_token>");
client.calls.create(
    "+12025550000",
    "+12025551111",
    "https://s3.amazonaws.com/static.plivo.com/answer.xml",
    { answerMethod: "GET" }
).then(console.log);
```

```php PHP theme={null}
<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient("<auth_id>","<auth_token>");
$response = $client->calls->create(
    '+12025550000',
    ['+12025551111'],
    'https://s3.amazonaws.com/static.plivo.com/answer.xml',
    ['answer_method' => 'GET']
);
print_r($response);
```

```java Java theme={null}
import com.plivo.api.Plivo;
import com.plivo.api.models.call.Call;
import java.util.Collections;

Plivo.init("<auth_id>","<auth_token>");
CallCreateResponse response = Call.creator(
    "+12025550000",
    Collections.singletonList("+12025551111"),
    "https://s3.amazonaws.com/static.plivo.com/answer.xml")
    .answerMethod("GET")
    .create();
System.out.println(response);
```

```csharp .NET theme={null}
using Plivo;

var api = new PlivoApi("<auth_id>","<auth_token>");
var response = api.Call.Create(
    to: new List<String>{"+12025551111"},
    from: "+12025550000",
    answerMethod: "GET",
    answerUrl: "https://s3.amazonaws.com/static.plivo.com/answer.xml"
);
Console.WriteLine(response);
```

```go Go theme={null}
package main

import "github.com/plivo/plivo-go/v7"

func main() {
    client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})
    response, _ := client.Calls.Create(plivo.CallCreateParams{
        From:         "+12025550000",
        To:           "+12025551111",
        AnswerURL:    "https://s3.amazonaws.com/static.plivo.com/answer.xml",
        AnswerMethod: "GET",
    })
}
```

```bash cURL theme={null}
curl -i --user AUTH_ID:AUTH_TOKEN \
    -H "Content-Type: application/json" \
    -d '{"to": "+12025551111","from": "+12025550000", "answer_url": "https://s3.amazonaws.com/static.plivo.com/answer.xml", "answer_method": "GET"}' \
    https://api.plivo.com/v1/Account/{auth_id}/Call/
```

### Response

**message** `string`

Status of the request. Returns `call fired` on a successful call creation request.

**request\_uuid** `string`

Unique identifier for the request.

**api\_id** `string`

Unique identifier for the API request.

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

### India Compliance Errors

Calls from India numbers require the `from` number to be rented on your account and to have a compliance application in `accepted` status. Requests that don't meet these conditions return `400 bad request`:

| Condition | Error message |
| - | - |
| The `from` number is not rented on your account | `from parameter is invalid. +912212345678 is not associated with your account. Use a phone number rented on your account.` |
| The compliance application is not in `accepted` status — pending, submitted, rejected, expired, or none attached | `from number +912212345678 cannot place calls as its compliance application is not in 'accepted' status. Refer to https://www.plivo.com/docs/numbers/rent-india-numbers for next steps.` |
| The compliance application is suspended due to [UCC complaints](https://plivo.com/docs/voice/concepts/ucc-management.md) | `from number +912212345678 cannot place calls as its compliance application is 'suspended'. Refer to https://www.plivo.com/docs/voice/concepts/ucc-management for next steps.` |

See [India Number KYC](https://plivo.com/docs/numbers/rent-india-numbers.md#application-status) for how to resolve each application status.

***

## Retrieve a Call

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

```text theme={null}
GET https://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/
```

### Arguments

No arguments required.

```python Python theme={null}
import plivo

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

```ruby Ruby theme={null}
require 'plivo'

api = Plivo::RestClient.new("<auth_id>","<auth_token>")
response = api.calls.get('eba53b9e-8fbd-45c1-9444-696d2172fbc8')
puts response
```

```javascript Node theme={null}
const plivo = require('plivo');

const client = new plivo.Client("<auth_id>","<auth_token>");
client.calls.get("eba53b9e-8fbd-45c1-9444-696d2172fbc8")
    .then(console.log);
```

```php PHP theme={null}
<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient("<auth_id>","<auth_token>");
$response = $client->calls->get('eba53b9e-8fbd-45c1-9444-696d2172fbc8');
print_r($response);
```

```java Java theme={null}
import com.plivo.api.Plivo;
import com.plivo.api.models.call.Call;

Plivo.init("<auth_id>","<auth_token>");
Call response = Call.getter("eba53b9e-8fbd-45c1-9444-696d2172fbc8").get();
System.out.println(response);
```

```csharp .NET theme={null}
using Plivo;

var api = new PlivoApi("<auth_id>","<auth_token>");
var response = api.Call.Get(callUuid: "ffa23c86-87ed-4fd5-8310-59594df8ae11");
Console.WriteLine(response);
```

```go Go theme={null}
package main

import "github.com/plivo/plivo-go/v7"

func main() {
    client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})
    response, _ := client.Calls.Get("eba53b9e-8fbd-45c1-9444-696d2172fbc8")
}
```

```bash cURL theme={null}
curl -i --user AUTH_ID:AUTH_TOKEN \
    https://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/
```

### Response

**answer\_time** `string`

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

**api\_id** `string`

Unique identifier for the API request.

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

**call\_direction** `string`

Direction of the call. Values: `outbound`, `inbound`.

**call\_duration** `integer`

Duration of the call in seconds.

**call\_state** `string`

Legacy field retained for backward compatibility. Values: `ANSWER`, `EARLY MEDIA`, `DELAYED NEGOTIATION`. Don't use this field in your application logic — use `hangup_cause_name` to determine the call outcome.

**call\_uuid** `string`

Unique identifier for the call.

**from\_number** `string`

Caller ID used to initiate the call.

**hangup\_cause\_code** `integer`

Integer code for the hangup cause.

**hangup\_cause\_name** `string`

Reason the call was hung up. [See hangup causes](https://plivo.com/docs/voice/troubleshooting/hangup-causes.md)

**hangup\_source** `string`

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

**initiation\_time** `string`

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

**to\_number** `string`

Number to which the call was initiated.

**total\_amount** `string`

Total amount charged for the call.

**total\_rate** `string`

Per-minute rate based on the destination number.

**source\_ip** `string`

IP address from which the call request originated.

```json theme={null}
{
    "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:sam9461399937766203278@phone.plivo.com",
    "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.

```text theme={null}
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.

> [!NOTE]
>
> 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.

```python Python theme={null}
import plivo

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

```ruby Ruby theme={null}
require 'plivo'

api = Plivo::RestClient.new("<auth_id>","<auth_token>")
response = api.calls.list(limit: 5, offset: 0)
puts response
```

```javascript Node theme={null}
const plivo = require('plivo');

const client = new plivo.Client("<auth_id>","<auth_token>");
client.calls.list({ limit: 5, offset: 0 }).then(console.log);
```

```php PHP theme={null}
<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient("<auth_id>","<auth_token>");
$response = $client->calls->list(['limit' => 5, 'offset' => 2]);
print_r($response);
```

```java Java theme={null}
import com.plivo.api.Plivo;
import com.plivo.api.models.call.Call;

Plivo.init("<auth_id>","<auth_token>");
ListResponse<Call> response = Call.lister().limit(5).offset(0).list();
System.out.println(response);
```

```csharp .NET theme={null}
using Plivo;

var api = new PlivoApi("<auth_id>","<auth_token>");
var response = api.Call.List(limit: 5, offset: 0);
Console.WriteLine(response);
```

```go Go theme={null}
package main

import "github.com/plivo/plivo-go/v7"

func main() {
    client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})
    response, _ := client.Calls.List(plivo.CallListParams{Limit: 5, Offset: 0})
}
```

```bash cURL theme={null}
curl -i --user AUTH_ID:AUTH_TOKEN \
    https://api.plivo.com/v1/Account/{auth_id}/Call/
```

### Response

**api\_id** `string`

Unique identifier for the API request.

**meta** `object`

Pagination metadata: `limit` (results per page), `offset` (items skipped), `total_count` (total matching calls).

**objects** `array`

Array of call objects — see [The Call Object](#the-call-object).

```json theme={null}
{
  "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.

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

```python Python theme={null}
import plivo

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

```ruby Ruby theme={null}
require 'plivo'

api = Plivo::RestClient.new("<auth_id>","<auth_token>")
response = api.calls.get_live('eba53b9e-8fbd-45c1-9444-696d2172fbc8')
puts response
```

```javascript Node theme={null}
const plivo = require('plivo');

const client = new plivo.Client("<auth_id>","<auth_token>");
client.calls.getLiveCall("eba53b9e-8fbd-45c1-9444-696d2172fbc8")
    .then(console.log);
```

```php PHP theme={null}
<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient("<auth_id>","<auth_token>");
$response = $client->calls->getLive('eba53b9e-8fbd-45c1-9444-696d2172fbc8');
print_r($response);
```

```java Java theme={null}
import com.plivo.api.Plivo;
import com.plivo.api.models.call.LiveCall;

Plivo.init("<auth_id>","<auth_token>");
LiveCall response = LiveCall.getter("eba53b9e-8fbd-45c1-9444-696d2172fbc8").get();
System.out.println(response);
```

```csharp .NET theme={null}
using Plivo;

var api = new PlivoApi("<auth_id>","<auth_token>");
var response = api.Call.GetLive(liveCallUuid: "ffa23c86-87ed-4fd5-8310-59594df8ae11");
Console.WriteLine(response);
```

```go Go theme={null}
package main

import "github.com/plivo/plivo-go/v7"

func main() {
    client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})
    response, _ := client.LiveCalls.Get("eba53b9e-8fbd-45c1-9444-696d2172fbc8")
}
```

```bash cURL theme={null}
curl -i --user AUTH_ID:AUTH_TOKEN \
    https://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/?status=live
```

### Response

**direction** `string`

Direction of the call. Values: `outbound`, `inbound`.

**from** `string`

The from number used as the caller ID.

**call\_status** `string`

Status of the call (`in-progress`).

**api\_id** `string`

Unique identifier for the API request.

**to** `string`

The destination that's called.

**caller\_name** `string`

Name of the caller.

**call\_uuid** `string`

Unique identifier for the call.

**session\_start** `string`

Timestamp when early media started (UTC).

```json theme={null}
{
  "direction": "inbound",
  "from": "14151234567",
  "call_status": "in-progress",
  "api_id": "45223222-74f8-11e1-8ea7-12313806be9a",
  "to": "14154290945",
  "caller_name": "+14151234567",
  "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.

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

```python Python theme={null}
import plivo

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

```ruby Ruby theme={null}
require 'plivo'

api = Plivo::RestClient.new("<auth_id>","<auth_token>")
response = api.calls.list_live()
puts response
```

```javascript Node theme={null}
const plivo = require('plivo');

const client = new plivo.Client("<auth_id>","<auth_token>");
client.calls.listLiveCalls().then(console.log);
```

```php PHP theme={null}
<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient("<auth_id>","<auth_token>");
$response = $client->calls->listLive();
print_r($response);
```

```java Java theme={null}
import com.plivo.api.Plivo;
import com.plivo.api.models.call.LiveCall;

Plivo.init("<auth_id>","<auth_token>");
LiveCallListResponse response = LiveCall.listGetter().get();
System.out.println(response);
```

```csharp .NET theme={null}
using Plivo;

var api = new PlivoApi("<auth_id>","<auth_token>");
var response = api.Call.ListLive();
Console.WriteLine(response);
```

```go Go theme={null}
package main

import "github.com/plivo/plivo-go/v7"

func main() {
    client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})
    response, _ := client.LiveCalls.IDList()
}
```

```bash cURL theme={null}
curl -i --user AUTH_ID:AUTH_TOKEN \
    https://api.plivo.com/v1/Account/{auth_id}/Call/?status=live
```

### Response

**api\_id** `string`

Unique identifier for the API request.

**calls** `array`

Array of call UUIDs of all ongoing calls.

```json theme={null}
{
  "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.

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

```python Python theme={null}
import plivo

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

```ruby Ruby theme={null}
require 'plivo'

api = Plivo::RestClient.new("<auth_id>","<auth_token>")
response = api.calls.list_queued()
puts response
```

```javascript Node theme={null}
const plivo = require('plivo');

const client = new plivo.Client("<auth_id>","<auth_token>");
client.calls.listQueuedCalls().then(console.log);
```

```php PHP theme={null}
<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient("<auth_id>","<auth_token>");
$response = $client->calls->listQueued();
print_r($response);
```

```java Java theme={null}
import com.plivo.api.Plivo;
import com.plivo.api.models.call.QueuedCall;

Plivo.init("<auth_id>","<auth_token>");
QueuedCallListResponse response = QueuedCall.listGetter().get();
System.out.println(response);
```

```csharp .NET theme={null}
using Plivo;

var api = new PlivoApi("<auth_id>","<auth_token>");
var response = api.Call.ListQueued();
Console.WriteLine(response);
```

```go Go theme={null}
package main

import "github.com/plivo/plivo-go/v7"

func main() {
    client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})
    response, _ := client.QueuedCalls.IDList()
}
```

```bash cURL theme={null}
curl -i --user AUTH_ID:AUTH_TOKEN \
    https://api.plivo.com/v1/Account/{auth_id}/Call/?status=queued
```

### Response

**api\_id** `string`

Unique identifier for the API request.

**calls** `array`

Array of call UUIDs of all queued calls.

```json theme={null}
{
  "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.

```text theme={null}
DELETE https://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/
```

> [!NOTE]
>
> If `call_uuid` is not specified, all ongoing calls in the account will be disconnected.

```python Python theme={null}
import plivo

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

```ruby Ruby theme={null}
require 'plivo'

api = Plivo::RestClient.new("<auth_id>","<auth_token>")
response = api.calls.delete('eba53b9e-8fbd-45c1-9444-696d2172fbc8')
puts response
```

```javascript Node theme={null}
const plivo = require('plivo');

const client = new plivo.Client("<auth_id>","<auth_token>");
client.calls.hangup("eba53b9e-8fbd-45c1-9444-696d2172fbc8")
    .then(console.log);
```

```php PHP theme={null}
<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient("<auth_id>","<auth_token>");
$response = $client->calls->delete('eba53b9e-8fbd-45c1-9444-696d2172fbc8');
print_r($response);
```

```java Java theme={null}
import com.plivo.api.Plivo;
import com.plivo.api.models.call.Call;

Plivo.init("<auth_id>","<auth_token>");
Call.deleter("eba53b9e-8fbd-45c1-9444-696d2172fbc8").delete();
System.out.println("Deleted successfully.");
```

```csharp .NET theme={null}
using Plivo;

var api = new PlivoApi("<auth_id>","<auth_token>");
var response = api.Call.Delete(callUuid: "10c94053-73b4-46fe-b74a-12159d1d3d60");
Console.WriteLine(response);
```

```go Go theme={null}
package main

import "github.com/plivo/plivo-go/v7"

func main() {
    client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})
    client.Calls.Delete("eba53b9e-8fbd-45c1-9444-696d2172fbc8")
}
```

```bash cURL theme={null}
curl -i --user AUTH_ID:AUTH_TOKEN -X DELETE \
    https://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/
```

### Response

```text theme={null}
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.

```text theme={null}
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`.

```python Python theme={null}
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)
```

```ruby Ruby theme={null}
require 'plivo'

api = Plivo::RestClient.new("<auth_id>","<auth_token>")
response = api.calls.update(
    'eba53b9e-8fbd-45c1-9444-696d2172fbc8',
    legs: 'aleg',
    aleg_url: 'https://aleg.url'
)
puts response
```

```javascript Node theme={null}
const plivo = require('plivo');

const client = new plivo.Client("<auth_id>","<auth_token>");
client.calls.transfer(
    "eba53b9e-8fbd-45c1-9444-696d2172fbc8",
    { legs: "aleg", alegUrl: "https://aleg.url" }
).then(console.log);
```

```php PHP theme={null}
<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient("<auth_id>","<auth_token>");
$response = $client->calls->transfer(
    'eba53b9e-8fbd-45c1-9444-696d2172fbc8',
    ['legs' => 'aleg', 'aleg_url' => 'https://ALEG.URL']
);
print_r($response);
```

```java Java theme={null}
import com.plivo.api.Plivo;
import com.plivo.api.models.call.Call;
import com.plivo.api.models.call.LegSpecifier;

Plivo.init("<auth_id>","<auth_token>");
CallUpdateResponse response = Call.updater("eba53b9e-8fbd-45c1-9444-696d2172fbc8")
    .legs(LegSpecifier.ALEG)
    .alegUrl("https://aleg.url")
    .update();
System.out.println(response);
```

```csharp .NET theme={null}
using Plivo;

var api = new PlivoApi("<auth_id>","<auth_token>");
var response = api.Call.Transfer(
    alegUrl: "https://aleg.url",
    callUuid: "eba53b9e-8fbd-45c1-9444-696d2172fbc8",
    legs: "aleg"
);
Console.WriteLine(response);
```

```go Go theme={null}
package main

import "github.com/plivo/plivo-go/v7"

func main() {
    client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})
    response, _ := client.Calls.Update(
        "eba53b9e-8fbd-45c1-9444-696d2172fbc8",
        plivo.CallUpdateParams{Legs: "aleg", AlegURL: "https://aleg.url"},
    )
}
```

```bash cURL theme={null}
curl -i --user AUTH_ID:AUTH_TOKEN \
    -H "Content-Type: application/json" \
    -d '{"legs": "aleg", "aleg_url": "https://aleg.url"}' \
    https://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/
```

### Response

**message** `string`

Status of the request. Returns `call transferred` on a successful transfer.

**api\_id** `string`

Unique identifier for the API request.

```json theme={null}
{
  "message": "call transferred",
  "api_id": "08c94608-58bd-11e1-86da-adf28403fe48"
}
```

***

## Record a Call

> [tab] Start Recording
>
> Start recording an active call.
>
> ```text theme={null}
> 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`
>
> Transcription type. Values: `auto`, `hybrid`, `manual`. Default: `auto`.
>
> **transcription\_url** `string`
>
> URL to receive transcription results.
>
> **transcription\_report\_type** `string`
>
> Format of the transcription report. Values: `full`, `compact`. Default: `compact`.
>
> **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`.
>
> > [!NOTE]
> >
> > 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.
>
> > [accordion] 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). |
>
> ```python Python theme={null}
> import plivo
>
> client = plivo.RestClient('<auth_id>','<auth_token>')
> response = client.calls.record(call_uuid='3a2e4c90-dcee-4931-8a59-f123ab507e60')
> print(response)
> ```
>
> ```ruby Ruby theme={null}
> require 'plivo'
>
> api = Plivo::RestClient.new("<auth_id>","<auth_token>")
> response = api.calls.record('eba53b9e-8fbd-45c1-9444-696d2172fbc8')
> puts response
> ```
>
> ```javascript Node theme={null}
> const plivo = require('plivo');
>
> const client = new plivo.Client("<auth_id>","<auth_token>");
> client.calls.record("eba53b9e-8fbd-45c1-9444-696d2172fbc8")
>     .then(console.log);
> ```
>
> ```php PHP theme={null}
> <?php
> require 'vendor/autoload.php';
> use Plivo\RestClient;
>
> $client = new RestClient("<auth_id>","<auth_token>");
> $response = $client->calls->startRecording('eba53b9e-8fbd-45c1-9444-696d2172fbc8');
> print_r($response);
> ```
>
> ```java Java theme={null}
> import com.plivo.api.Plivo;
> import com.plivo.api.models.call.Call;
>
> Plivo.init("<auth_id>","<auth_token>");
> CallRecordCreateResponse response = Call.recorder("eba53b9e-8fbd-45c1-9444-696d2172fbc8").record();
> System.out.println(response);
> ```
>
> ```csharp .NET theme={null}
> using Plivo;
>
> var api = new PlivoApi("<auth_id>","<auth_token>");
> var response = api.Call.StartRecording(callUuid: "10c94053-73b4-46fe-b74a-12159d1d3d60");
> Console.WriteLine(response);
> ```
>
> ```go Go theme={null}
> package main
>
> import "github.com/plivo/plivo-go/v7"
>
> func main() {
>     client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})
>     response, _ := client.Calls.Record("eba53b9e-8fbd-45c1-9444-696d2172fbc8", plivo.CallRecordParams{})
> }
> ```
>
> ```bash cURL theme={null}
> curl -i --user AUTH_ID:AUTH_TOKEN \
>     -H "Content-Type: application/json" \
>     -d '{}' \
>     https://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/Record/
> ```
>
> #### Response
>
> **url** `string`
>
> URL where the recorded file can be accessed.
>
> **message** `string`
>
> Status of the request. Returns `call recording started` on a successful request.
>
> **recording\_id** `string`
>
> The recording ID.
>
> **api\_id** `string`
>
> Unique identifier for the API request.
>
> ```json theme={null}
> {
>   "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"
> }
> ```

> [tab] Stop Recording
>
> Stop active recordings on a call.
>
> ```text theme={null}
> 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.
>
> ```python Python theme={null}
> import plivo
>
> client = plivo.RestClient('<auth_id>','<auth_token>')
> response = client.calls.record_stop(call_uuid='3a2e4c90-dcee-4931-8a59-f123ab507e60')
> print(response)
> ```
>
> ```ruby Ruby theme={null}
> require 'plivo'
>
> api = Plivo::RestClient.new("<auth_id>","<auth_token>")
> response = api.calls.stop_record('eba53b9e-8fbd-45c1-9444-696d2172fbc8')
> puts response
> ```
>
> ```javascript Node theme={null}
> const plivo = require('plivo');
>
> const client = new plivo.Client("<auth_id>","<auth_token>");
> client.calls.stopRecording("eba53b9e-8fbd-45c1-9444-696d2172fbc8")
>     .then(console.log);
> ```
>
> ```php PHP theme={null}
> <?php
> require 'vendor/autoload.php';
> use Plivo\RestClient;
>
> $client = new RestClient("<auth_id>","<auth_token>");
> $response = $client->calls->stopRecording('eba53b9e-8fbd-45c1-9444-696d2172fbc8');
> print_r($response);
> ```
>
> ```java Java theme={null}
> import com.plivo.api.Plivo;
> import com.plivo.api.models.call.Call;
>
> Plivo.init("<auth_id>","<auth_token>");
> Call.recordStopper("eba53b9e-8fbd-45c1-9444-696d2172fbc8").recordStop();
> System.out.println("Deleted successfully.");
> ```
>
> ```csharp .NET theme={null}
> using Plivo;
>
> var api = new PlivoApi("<auth_id>","<auth_token>");
> var response = api.Call.StopRecording(callUuid: "93b35e56-5b28-47fc-95aa-8536625d3ac1");
> Console.WriteLine(response);
> ```
>
> ```go Go theme={null}
> package main
>
> import "github.com/plivo/plivo-go/v7"
>
> func main() {
>     client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})
>     client.Calls.StopRecording("eba53b9e-8fbd-45c1-9444-696d2172fbc8")
> }
> ```
>
> ```bash cURL theme={null}
> curl -X DELETE --user AUTH_ID:AUTH_TOKEN \
>     https://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/Record/
> ```
>
> #### Response
>
> ```text theme={null}
> HTTP Status Code: 204
> ```

***

## Play Audio

> [tab] Start Playing
>
> Play an audio file during an active call. Supports `.mp3` and `.wav` files.
>
> ```text theme={null}
> 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`.
>
> ```python Python theme={null}
> 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)
> ```
>
> ```ruby Ruby theme={null}
> require 'plivo'
>
> api = Plivo::RestClient.new("<auth_id>","<auth_token>")
> response = api.calls.play(
>     'eba53b9e-8fbd-45c1-9444-696d2172fbc8',
>     ['https://s3.amazonaws.com/plivocloud/Trumpet.mp3'],
>     loop: true
> )
> puts response
> ```
>
> ```javascript Node theme={null}
> const plivo = require('plivo');
>
> const client = new plivo.Client("<auth_id>","<auth_token>");
> client.calls.playMusic(
>     "eba53b9e-8fbd-45c1-9444-696d2172fbc8",
>     "https://s3.amazonaws.com/plivocloud/Trumpet.mp3"
> ).then(console.log);
> ```
>
> ```php PHP theme={null}
> <?php
> require 'vendor/autoload.php';
> use Plivo\RestClient;
>
> $client = new RestClient("<auth_id>","<auth_token>");
> $response = $client->calls->startPlaying(
>     'eba53b9e-8fbd-45c1-9444-696d2172fbc8',
>     ['https://s3.amazonaws.com/plivocloud/Trumpet.mp3']
> );
> print_r($response);
> ```
>
> ```java Java theme={null}
> import com.plivo.api.Plivo;
> import com.plivo.api.models.call.Call;
> import java.util.Collections;
>
> Plivo.init("<auth_id>","<auth_token>");
> CallPlayCreateResponse response = Call.player(
>     "eba53b9e-8fbd-45c1-9444-696d2172fbc8",
>     Collections.singletonList("https://s3.amazonaws.com/plivocloud/Trumpet.mp3")
> ).play();
> System.out.println(response);
> ```
>
> ```csharp .NET theme={null}
> using Plivo;
>
> var api = new PlivoApi("<auth_id>","<auth_token>");
> var response = api.Call.StartPlaying(
>     callUuid: "93b35e56-5b28-47fc-95aa-8536625d3ac1",
>     urls: new List<string>() {"https://s3.amazonaws.com/plivocloud/music.mp3"}
> );
> Console.WriteLine(response);
> ```
>
> ```go Go theme={null}
> package main
>
> import "github.com/plivo/plivo-go/v7"
>
> func main() {
>     client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})
>     response, _ := client.Calls.Play(
>         "eba53b9e-8fbd-45c1-9444-696d2172fbc8",
>         plivo.CallPlayParams{URLs: "https://s3.amazonaws.com/plivocloud/Trumpet.mp3"},
>     )
> }
> ```
>
> ```bash cURL theme={null}
> curl -i --user AUTH_ID:AUTH_TOKEN \
>     -H "Content-Type: application/json" \
>     -d '{"urls":"https://s3.amazonaws.com/plivocloud/Trumpet.mp3"}' \
>     https://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/Play/
> ```
>
> #### Response
>
> **message** `string`
>
> Status of the request. Returns `play started` on a successful request.
>
> **api\_id** `string`
>
> Unique identifier for the API request.
>
> ```json theme={null}
> {
>   "message": "play started",
>   "api_id": "07abfd94-58c0-11e1-86da-adf28403fe48"
> }
> ```

> [tab] Stop Playing
>
> Stop playing audio during an active call.
>
> ```text theme={null}
> DELETE https://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/Play/
> ```
>
> ```python Python theme={null}
> import plivo
>
> client = plivo.RestClient('<auth_id>','<auth_token>')
> response = client.calls.play_stop(call_uuid='bc480f62-6d99-469e-b80e-090e620de824')
> print(response)
> ```
>
> ```ruby Ruby theme={null}
> require 'plivo'
>
> api = Plivo::RestClient.new("<auth_id>","<auth_token>")
> response = api.calls.stop_play('eba53b9e-8fbd-45c1-9444-696d2172fbc8')
> puts response
> ```
>
> ```javascript Node theme={null}
> const plivo = require('plivo');
>
> const client = new plivo.Client("<auth_id>","<auth_token>");
> client.calls.stopPlayingMusic("eba53b9e-8fbd-45c1-9444-696d2172fbc8")
>     .then(console.log);
> ```
>
> ```php PHP theme={null}
> <?php
> require 'vendor/autoload.php';
> use Plivo\RestClient;
>
> $client = new RestClient("<auth_id>","<auth_token>");
> $response = $client->calls->stopPlaying('eba53b9e-8fbd-45c1-9444-696d2172fbc8');
> print_r($response);
> ```
>
> ```java Java theme={null}
> import com.plivo.api.Plivo;
> import com.plivo.api.models.call.Call;
>
> Plivo.init("<auth_id>","<auth_token>");
> Call.playStopper("eba53b9e-8fbd-45c1-9444-696d2172fbc8").playStop();
> System.out.println("Deleted successfully.");
> ```
>
> ```csharp .NET theme={null}
> using Plivo;
>
> var api = new PlivoApi("<auth_id>","<auth_token>");
> var response = api.Call.StopPlaying(callUuid: "10c94053-73b4-46fe-b74a-12159d1d3d60");
> Console.WriteLine(response);
> ```
>
> ```go Go theme={null}
> package main
>
> import "github.com/plivo/plivo-go/v7"
>
> func main() {
>     client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})
>     client.Calls.StopPlaying("eba53b9e-8fbd-45c1-9444-696d2172fbc8")
> }
> ```
>
> ```bash cURL theme={null}
> curl -X DELETE --user AUTH_ID:AUTH_TOKEN \
>     https://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/Play/
> ```
>
> #### Response
>
> ```text theme={null}
> HTTP Status Code: 204
> ```

***

## Speak Text

> [tab] Start Speaking
>
> Speak text during an active call using text-to-speech.
>
> ```text theme={null}
> 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`.
>
> > [accordion] 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` |
>
> ```python Python theme={null}
> 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)
> ```
>
> ```ruby Ruby theme={null}
> require 'plivo'
>
> api = Plivo::RestClient.new("<auth_id>","<auth_token>")
> response = api.calls.speak('eba53b9e-8fbd-45c1-9444-696d2172fbc8', 'Hello World')
> puts response
> ```
>
> ```javascript Node theme={null}
> const plivo = require('plivo');
>
> const client = new plivo.Client("<auth_id>","<auth_token>");
> client.calls.speakText("eba53b9e-8fbd-45c1-9444-696d2172fbc8", "Hello World")
>     .then(console.log);
> ```
>
> ```php PHP theme={null}
> <?php
> require 'vendor/autoload.php';
> use Plivo\RestClient;
>
> $client = new RestClient("<auth_id>","<auth_token>");
> $response = $client->calls->startSpeaking('eba53b9e-8fbd-45c1-9444-696d2172fbc8', 'Hello World');
> print_r($response);
> ```
>
> ```java Java theme={null}
> import com.plivo.api.Plivo;
> import com.plivo.api.models.call.Call;
>
> Plivo.init("<auth_id>","<auth_token>");
> CallSpeakCreateResponse response = Call.speaker("eba53b9e-8fbd-45c1-9444-696d2172fbc8", "Hello World").speak();
> System.out.println(response);
> ```
>
> ```csharp .NET theme={null}
> using Plivo;
>
> var api = new PlivoApi("<auth_id>","<auth_token>");
> var response = api.Call.StartSpeaking(
>     callUuid: "93b35e56-5b28-47fc-95aa-8536625d3ac1",
>     text: "Hello World"
> );
> Console.WriteLine(response);
> ```
>
> ```go Go theme={null}
> package main
>
> import "github.com/plivo/plivo-go/v7"
>
> func main() {
>     client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})
>     response, _ := client.Calls.Speak(
>         "eba53b9e-8fbd-45c1-9444-696d2172fbc8",
>         plivo.CallSpeakParams{Text: "Hello World"},
>     )
> }
> ```
>
> ```bash cURL theme={null}
> curl -i --user AUTH_ID:AUTH_TOKEN \
>     -H "Content-Type: application/json" \
>     -d '{"text":"Hello World"}' \
>     https://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/Speak/
> ```
>
> #### Response
>
> **message** `string`
>
> Status of the request. Returns `speak started` on a successful request.
>
> **api\_id** `string`
>
> Unique identifier for the API request.
>
> ```json theme={null}
> {
>   "message": "speak started",
>   "api_id": "07abfd94-58c0-11e1-86da-adf28403fe48"
> }
> ```

> [tab] Stop Speaking
>
> Stop active text-to-speech during a call.
>
> ```text theme={null}
> DELETE https://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/Speak/
> ```
>
> ```python Python theme={null}
> import plivo
>
> client = plivo.RestClient('<auth_id>','<auth_token>')
> response = client.calls.speak_stop(call_uuid='3a2e4c90-dcee-4931-8a59-f123ab507e60')
> print(response)
> ```
>
> ```ruby Ruby theme={null}
> require 'plivo'
>
> api = Plivo::RestClient.new("<auth_id>","<auth_token>")
> response = api.calls.stop_speak('eba53b9e-8fbd-45c1-9444-696d2172fbc8')
> puts response
> ```
>
> ```javascript Node theme={null}
> const plivo = require('plivo');
>
> const client = new plivo.Client("<auth_id>","<auth_token>");
> client.calls.stopSpeakingText("eba53b9e-8fbd-45c1-9444-696d2172fbc8")
>     .then(console.log);
> ```
>
> ```php PHP theme={null}
> <?php
> require 'vendor/autoload.php';
> use Plivo\RestClient;
>
> $client = new RestClient("<auth_id>","<auth_token>");
> $response = $client->calls->stopSpeaking('eba53b9e-8fbd-45c1-9444-696d2172fbc8');
> print_r($response);
> ```
>
> ```java Java theme={null}
> import com.plivo.api.Plivo;
> import com.plivo.api.models.call.Call;
>
> Plivo.init("<auth_id>","<auth_token>");
> Call.speakStopper("eba53b9e-8fbd-45c1-9444-696d2172fbc8").speakStop();
> System.out.println("Deleted successfully.");
> ```
>
> ```csharp .NET theme={null}
> using Plivo;
>
> var api = new PlivoApi("<auth_id>","<auth_token>");
> var response = api.Call.StopSpeaking(callUuid: "10c94053-73b4-46fe-b74a-12159d1d3d60");
> Console.WriteLine(response);
> ```
>
> ```go Go theme={null}
> package main
>
> import "github.com/plivo/plivo-go/v7"
>
> func main() {
>     client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})
>     client.Calls.StopSpeaking("eba53b9e-8fbd-45c1-9444-696d2172fbc8")
> }
> ```
>
> ```bash cURL theme={null}
> curl -X DELETE --user AUTH_ID:AUTH_TOKEN \
>     https://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/Speak/
> ```
>
> #### Response
>
> **message** `string`
>
> Status of the request. Returns `speak stopped` on a successful request.
>
> **api\_id** `string`
>
> Unique identifier for the API request.
>
> ```json theme={null}
> {
>     "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.

```text theme={null}
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>`.

```python Python theme={null}
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)
```

```ruby Ruby theme={null}
require 'plivo'

api = Plivo::RestClient.new("<auth_id>","<auth_token>")
response = api.calls.send_digits('eba53b9e-8fbd-45c1-9444-696d2172fbc8', '123', 'bleg')
puts response
```

```javascript Node theme={null}
const plivo = require('plivo');

const client = new plivo.Client("<auth_id>","<auth_token>");
client.calls.sendDigits("eba53b9e-8fbd-45c1-9444-696d2172fbc8", "123")
    .then(console.log);
```

```php PHP theme={null}
<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient("<auth_id>","<auth_token>");
$response = $client->calls->dtmf('eba53b9e-8fbd-45c1-9444-696d2172fbc8', '123', 'bleg');
print_r($response);
```

```java Java theme={null}
import com.plivo.api.Plivo;
import com.plivo.api.models.call.Call;

Plivo.init("<auth_id>","<auth_token>");
CallDtmfCreateResponse response = Call.digitSender("eba53b9e-8fbd-45c1-9444-696d2172fbc8", "123").sendDigits();
System.out.println(response);
```

```csharp .NET theme={null}
using Plivo;

var api = new PlivoApi("<auth_id>","<auth_token>");
var response = api.Call.SendDigits(
    callUuid: "10c94053-73b4-46fe-b74a-12159d1d3d60",
    digits: "123"
);
Console.WriteLine(response);
```

```go Go theme={null}
package main

import "github.com/plivo/plivo-go/v7"

func main() {
    client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})
    response, _ := client.Calls.SendDigits(
        "eba53b9e-8fbd-45c1-9444-696d2172fbc8",
        plivo.CallDTMFParams{Digits: "123"},
    )
}
```

```bash cURL theme={null}
curl -i --user AUTH_ID:AUTH_TOKEN \
    -H "Content-Type: application/json" \
    -d '{"digits":"8743#"}' \
    https://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/DTMF/
```

### Response

**message** `string`

Status of the request. Returns `digits sent` on a successful request.

**api\_id** `string`

Unique identifier for the API request.

```json theme={null}
{
  "message": "digits sent",
  "api_id": "07abfd94-58c0-11e1-86da-adf28403fe48"
}
```

***

## Cancel a Request

Cancel a pending or in-progress API request by its UUID.

```bash theme={null}
DELETE https://api.plivo.com/v1/Account/{auth_id}/Request/{request_uuid}/
```

**request\_uuid** `string` *required*

Unique identifier of the request to cancel.

### Response

```text theme={null}
HTTP Status Code: 204
```

***

## Call Conversion

Post conversion or feedback data for a call.

```bash theme={null}
POST https://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/Conversion/
```

### Arguments

**timestamp** `string`

Timestamp of the conversion event.

**status** `string`

Conversion status.

***

## List Live Calls (V2)

Retrieve a list of live calls with enhanced response format.

```bash theme={null}
GET https://api.plivo.com/v2/Account/{auth_id}/Call/
```

Returns a list of active calls with additional metadata compared to the [V1 live calls filter](#list-all-calls).