> ## 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

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

<ParamField body="call_uuid" type="string">
  Unique identifier for the call.
</ParamField>

<ParamField body="from_number" type="string">
  Caller ID used to initiate the call.
</ParamField>

<ParamField body="to_number" type="string">
  Number to which the call was initiated.
</ParamField>

<ParamField body="call_direction" type="string">
  Direction of the call. Values: `outbound`, `inbound`.
</ParamField>

<ParamField body="answer_time" type="string">
  Timestamp when the call was answered. Format: `yyyy-MM-dd HH:mm:ss`
</ParamField>

<ParamField body="end_time" type="string">
  Timestamp when the call ended. Format: `yyyy-MM-dd HH:mm:ss`
</ParamField>

<ParamField body="initiation_time" type="string">
  Timestamp when the call was initiated. Format: `yyyy-MM-dd HH:mm:ss`
</ParamField>

<ParamField body="call_duration" type="integer">
  Duration of the call in seconds.
</ParamField>

<ParamField body="bill_duration" type="integer">
  The duration of the call in seconds.
</ParamField>

<ParamField body="billed_duration" type="integer">
  The billed duration of the call in seconds. May differ from `bill_duration` depending on the billing interval.
</ParamField>

<ParamField body="total_amount" type="string">
  Total amount charged for the call.
</ParamField>

<ParamField body="total_rate" type="string">
  Per-minute rate based on the destination number.
</ParamField>

<ParamField body="parent_call_uuid" type="string">
  UUID of the A-leg of the call.
</ParamField>

<ParamField body="hangup_cause_name" type="string">
  Reason the call was hung up. [See hangup causes](/voice/troubleshooting/hangup-causes/)
</ParamField>

<ParamField body="hangup_cause_code" type="integer">
  Integer code for the hangup cause.
</ParamField>

<ParamField body="hangup_source" type="string">
  Entity that triggered the hangup. Values: `Caller`, `Callee`, `Plivo`, `API Request`, `Answer XML`, `Error`, `Unknown`.
</ParamField>

<ParamField body="stir_verification" type="string">
  STIR/SHAKEN attestation info. Values: `Verified`, `Not Verified`, `Not Applicable`. [Read more](/voice/concepts/stir-shaken/)
</ParamField>

<ParamField body="source_ip" type="string">
  IP address from which the call request originated.
</ParamField>

<ParamField body="resource_uri" type="string">
  URI of the requested resource.
</ParamField>

### 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](/voice/concepts/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`

<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.
</Note>

See [Voice Pricing](https://www.plivo.com/pricing/voice/) 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

<ParamField body="from" type="string" required>
  Caller ID phone number in E.164 format (e.g., `14157654321`).
</ParamField>

<ParamField body="to" type="string" required>
  Destination number(s) or SIP URI(s). Use `<` to separate multiple destinations (max 1000).
</ParamField>

<ParamField body="answer_url" type="string" required>
  URL called when the call is answered. Must return valid Plivo XML.
</ParamField>

<ParamField body="answer_method" type="string">
  HTTP verb for `answer_url`. Default: `POST`.
</ParamField>

<ParamField body="ring_url" type="string">
  URL notified when the call starts ringing.
</ParamField>

<ParamField body="ring_method" type="string">
  HTTP verb for `ring_url`. Default: `POST`.
</ParamField>

<ParamField body="hangup_url" type="string">
  URL notified when the call is hung up.
</ParamField>

<ParamField body="hangup_method" type="string">
  HTTP verb for `hangup_url`. Default: `POST`.
</ParamField>

<ParamField body="fallback_url" type="string">
  Invoked if `answer_url` fails after 3 retries or 60s timeout.
</ParamField>

<ParamField body="fallback_method" type="string">
  HTTP verb for `fallback_url`. Default: `POST`.
</ParamField>

<ParamField body="caller_name" type="string">
  Sets caller name (up to 50 characters).
</ParamField>

<ParamField body="send_digits" type="string">
  Sends DTMF digits after call is connected. Use `w` (0.5s wait) or `W` (1s wait).
</ParamField>

<ParamField body="send_on_preanswer" type="boolean">
  If `true`, sends `send_digits` during pre-answer. Default: `false`.
</ParamField>

<ParamField body="time_limit" type="integer">
  Max duration of call in seconds. Default: `14400` (4 hours).
</ParamField>

<ParamField body="hangup_on_ring" type="integer">
  Max duration (in seconds) from start of ringing to hangup.
</ParamField>

<ParamField body="machine_detection" type="string">
  Detect machine on answer. Values: `true`, `hangup`.
</ParamField>

<ParamField body="machine_detection_time" type="integer">
  Time in ms to detect machine. Default: `5000`. Range: `2000`–`10000`.
</ParamField>

<ParamField body="machine_detection_url" type="string">
  Callback URL for asynchronous machine detection.
</ParamField>

<ParamField body="machine_detection_method" type="string">
  HTTP verb for `machine_detection_url`. Default: `POST`.
</ParamField>

<ParamField body="sip_headers" type="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](/voice/concepts/sip-authentication/) for details.
</ParamField>

<ParamField body="sip_auth_username" type="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](/voice/concepts/sip-authentication/).
</ParamField>

<ParamField body="sip_auth_password" type="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.
</ParamField>

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

<ParamField body="ring_timeout" type="integer">
  Maximum time in seconds to ring the destination before timing out.
</ParamField>

<ParamField body="parent_call_uuid" type="string">
  UUID of the parent call, used for call routing and tracking.
</ParamField>

<ParamField body="parent_auth_id" type="string">
  Auth ID of the parent account.
</ParamField>

<ParamField body="error_if_parent_not_found" type="boolean">
  When `true`, returns an error if the parent call is not found. Default: `false`.
</ParamField>

<ParamField body="call_type" 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](/messaging/concepts/whatsapp/whatsapp-calling) for details.
</ParamField>

<ParamField body="delimiter" type="string">
  Delimiter character for separating multiple destination numbers in bulk calls. Default: `<`.
</ParamField>

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

<ParamField body="machine_detection_maximum_speech_length" type="integer">
  Maximum duration of speech in milliseconds to analyze before making a determination. Range: `1000`–`6000`.
</ParamField>

<ParamField body="machine_detection_initial_silence" type="integer">
  Duration of initial silence in milliseconds before the call is classified. Range: `2000`–`10000`.
</ParamField>

<ParamField body="machine_detection_maximum_words" type="integer">
  Maximum number of words to listen for before making a determination. Range: `2`–`10`.
</ParamField>

<ParamField body="machine_detection_initial_greeting" type="integer">
  Maximum duration of the initial greeting in milliseconds to analyze. Range: `1000`–`5000`.
</ParamField>

<ParamField body="machine_detection_silence" type="integer">
  Duration of silence in milliseconds after speech that indicates end of greeting. Range: `500`–`5000`.
</ParamField>

<ParamField body="machine_detection_answer_time" type="integer">
  Total time in milliseconds allotted for machine detection analysis. Range: `100`–`45000`.
</ParamField>

### Callbacks

<Accordion title="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>

<Accordion title="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>

<Accordion title="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.                     |
</Accordion>

<CodeGroup>
  ```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/
  ```
</CodeGroup>

### Response

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

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

### Arguments

No arguments required.

<CodeGroup>
  ```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}/
  ```
</CodeGroup>

### Response

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

<ParamField query="from_number" type="string">
  Filter by the number from which calls were made.
</ParamField>

<ParamField query="to_number" type="string">
  Filter by the destination number of the call.
</ParamField>

<ParamField query="call_direction" type="string">
  Filter by direction. Values: `inbound`, `outbound`.
</ParamField>

<ParamField query="bill_duration" type="integer">
  Filter by billed duration. Supports variants: `bill_duration__gt`, `bill_duration__gte`, `bill_duration__lt`, `bill_duration__lte`.
</ParamField>

<ParamField query="end_time" type="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`.
</ParamField>

<ParamField query="hangup_cause_code" type="integer">
  Filter by hangup cause code.
</ParamField>

<ParamField query="hangup_source" type="string">
  Filter by hangup source. Values: `customer`, `carrier`, `zentrunk`.
</ParamField>

<ParamField query="stir_verification" type="string">
  Filter by STIR/SHAKEN status. Values: `Verified`, `Not Verified`, `Not Applicable`.
</ParamField>

<ParamField query="limit" type="integer">
  Number of results to return. Max: 20. Default: 20.
</ParamField>

<ParamField query="offset" type="integer">
  Number of items to skip for pagination.
</ParamField>

<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.
</Note>

<CodeGroup>
  ```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/
  ```
</CodeGroup>

### Response

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

<CodeGroup>
  ```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
  ```
</CodeGroup>

### Response

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

<CodeGroup>
  ```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
  ```
</CodeGroup>

### Response

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

<CodeGroup>
  ```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
  ```
</CodeGroup>

### Response

```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.
</Note>

<CodeGroup>
  ```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}/
  ```
</CodeGroup>

### 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

<ParamField body="legs" type="string">
  Which leg(s) to transfer. Values: `aleg`, `bleg`, `both`.
</ParamField>

<ParamField body="aleg_url" type="string">
  URL to fetch XML from for the A leg. Required if `legs` is `aleg` or `both`.
</ParamField>

<ParamField body="aleg_method" type="string">
  HTTP verb for `aleg_url`. Default: `POST`.
</ParamField>

<ParamField body="bleg_url" type="string">
  URL to fetch XML from for the B leg. Required if `legs` is `bleg` or `both`.
</ParamField>

<ParamField body="bleg_method" type="string">
  HTTP verb for `bleg_url`. Default: `POST`.
</ParamField>

<CodeGroup>
  ```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}/
  ```
</CodeGroup>

### Response

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

***

## Record a Call

<Tabs>
  <Tab title="Start Recording">
    Start recording an active call.

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

    ### Arguments

    <ParamField body="time_limit" type="integer">
      Max recording duration in seconds. Default: `60`.
    </ParamField>

    <ParamField body="file_format" type="string">
      Recording format. Values: `mp3`, `wav`. Default: `mp3`.
    </ParamField>

    <ParamField body="transcription_type" type="string">
      Transcription type. Values: `auto`, `hybrid`, `manual`. Default: `auto`.
    </ParamField>

    <ParamField body="transcription_url" type="string">
      URL to receive transcription results.
    </ParamField>

    <ParamField body="transcription_report_type" type="string">
      Format of the transcription report. Values: `full`, `compact`. Default: `compact`.
    </ParamField>

    <ParamField body="callback_url" type="string">
      URL invoked when recording ends.
    </ParamField>

    <ParamField body="callback_method" type="string">
      HTTP verb for `callback_url`. Default: `POST`.
    </ParamField>

    <ParamField body="record_channel_type" type="string">
      Recording channel. Values: `mono`, `stereo`. Default: `mono`.
    </ParamField>

    <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.
    </Note>

    <Accordion title="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).            |
    </Accordion>

    <CodeGroup>
      ```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/
      ```
    </CodeGroup>

    #### Response

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

  <Tab title="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

    <ParamField body="URL" type="string">
      Specify a record URL to stop only one recording. By default, all recordings are stopped.
    </ParamField>

    <CodeGroup>
      ```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/
      ```
    </CodeGroup>

    #### Response

    ```text theme={null}
    HTTP Status Code: 204
    ```
  </Tab>
</Tabs>

***

## Play Audio

<Tabs>
  <Tab title="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

    <ParamField body="urls" type="string" required>
      URL or comma-separated URLs to `.mp3` or `.wav` files.
    </ParamField>

    <ParamField body="length" type="integer">
      Max playback length in seconds.
    </ParamField>

    <ParamField body="legs" type="string">
      Call leg to play audio. Values: `aleg`, `bleg`, `both`. Default: `aleg`.
    </ParamField>

    <ParamField body="loop" type="boolean">
      If `true`, audio plays indefinitely. Default: `false`.
    </ParamField>

    <ParamField body="mix" type="boolean">
      If `true`, call and audio are mixed. If `false`, participants can't hear each other during playback. Default: `true`.
    </ParamField>

    <CodeGroup>
      ```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/
      ```
    </CodeGroup>

    #### Response

    ```json theme={null}
    {
      "message": "play started",
      "api_id": "07abfd94-58c0-11e1-86da-adf28403fe48"
    }
    ```
  </Tab>

  <Tab title="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/
    ```

    <CodeGroup>
      ```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/
      ```
    </CodeGroup>

    #### Response

    ```text theme={null}
    HTTP Status Code: 204
    ```
  </Tab>
</Tabs>

***

## Speak Text

<Tabs>
  <Tab title="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

    <ParamField body="text" type="string" required>
      Text to be spoken.
    </ParamField>

    <ParamField body="voice" type="string">
      Voice type. Values: `MAN`, `WOMAN`. Default: `WOMAN`.
    </ParamField>

    <ParamField body="language" type="string">
      Language code. Default: `en-US`.
    </ParamField>

    <ParamField body="legs" type="string">
      Call leg. Values: `aleg`, `bleg`, `both`. Default: `aleg`.
    </ParamField>

    <ParamField body="loop" type="boolean">
      If `true`, text repeats until stopped. Default: `false`.
    </ParamField>

    <ParamField body="mix" type="boolean">
      If `true`, call and speech are mixed. Default: `true`.
    </ParamField>

    <Accordion title="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`   |
    </Accordion>

    <CodeGroup>
      ```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/
      ```
    </CodeGroup>

    #### Response

    ```json theme={null}
    {
      "message": "speak started",
      "api_id": "07abfd94-58c0-11e1-86da-adf28403fe48"
    }
    ```
  </Tab>

  <Tab title="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/
    ```

    <CodeGroup>
      ```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/
      ```
    </CodeGroup>

    #### Response

    ```json theme={null}
    {
        "message": "speak stopped",
        "api_id": "cf2359c8-f4d6-11e6-b886-067c5485c240"
    }
    ```
  </Tab>
</Tabs>

***

## 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

<ParamField body="digits" type="string" required>
  Digits to send over the call.
</ParamField>

<ParamField body="leg" type="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>`.
</ParamField>

<CodeGroup>
  ```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/
  ```
</CodeGroup>

### Response

```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}/
```

<ParamField path="request_uuid" type="string" required>
  Unique identifier of the request to cancel.
</ParamField>

### 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

<ParamField body="timestamp" type="string">
  Timestamp of the conversion event.
</ParamField>

<ParamField body="status" type="string">
  Conversion status.
</ParamField>

***

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