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

# Session API

> Create and manage anonymous calling sessions between two parties using virtual phone numbers

Number masking sessions establish anonymous connections between two phone numbers. When a session is created, Plivo assigns a virtual number that either party can call to connect to the other without revealing their actual phone numbers.

**API Endpoint**

```
https://api.plivo.com/v1/Account/{auth_id}/Masking/Session
```

***

## The Session Object

### Attributes

**session\_uuid** `string`

Unique identifier for the session.

**first\_party** `string`

The actual phone number of the first participant.

**second\_party** `string`

The actual phone number of the second participant.

**virtual\_number** `string`

Plivo phone number to be dialed for connecting with the other participant.

**status** `string`

Current session status. Values: `active`, `in-progress`, or `expired`.

**session\_expiry** `integer`

Time in seconds after which the session mapping will expire. Calls made after this will not be forwarded.

**call\_time\_limit** `integer`

Time in seconds after which the call should be disconnected. Applies to all call legs.

**ring\_timeout** `integer`

Time in seconds after which the ring should be disconnected. Defaults to 120.

**initiate\_call\_to\_first\_party** `boolean`

If `true`, Plivo calls the first party immediately and bridges if answered. Defaults to `false`.

**record** `boolean`

Determines the recording status for a phone call. Defaults to `false`. If `true`, call recording starts only when both participants have answered.

**record\_file\_format** `string`

Audio format for the recording. Values: `mp3`, `wav`. Defaults to `mp3`.

**recording\_callback\_url** `string`

URL to which the call recording is sent.

**recording\_callback\_method** `string`

HTTP verb for invoking `recording_callback_url`. Values: `GET`, `POST`. Defaults to `POST`.

**callback\_url** `string`

URL on which to receive important session events and status updates.

**callback\_method** `string`

HTTP verb for invoking `callback_url`. Values: `GET`, `POST`. Defaults to `POST`.

**first\_party\_play\_url** `string`

URL returning MP3/WAV file to play to first party before connecting.

**second\_party\_play\_url** `string`

URL returning MP3/WAV file to play to second party before connecting.

**is\_pin\_authentication\_required** `boolean`

Specifies whether PIN authentication is necessary when the call originates from an unidentified caller.

**generate\_pin** `boolean`

Indicates if Plivo generates the PIN for the session.

**generate\_pin\_length** `integer`

Length of the PIN to be generated. Default: 4, Min: 4, Max: 15.

**first\_party\_pin** `string`

The PIN for the first party when using a secondary number.

**second\_party\_pin** `string`

The PIN for the second party when using a secondary number.

**created\_time** `timestamp`

UTC time when the session was created (yyyy-mm-dd, hh-mm-ss).

**modified\_time** `timestamp`

UTC time when the session was last modified (yyyy-mm-dd, hh-mm-ss).

**expiry\_time** `timestamp`

UTC time when the session will expire (yyyy-mm-dd, hh-mm-ss).

**last\_interaction\_time** `timestamp`

UTC time when the latest interaction ended (yyyy-mm-dd, hh-mm-ss).

**duration** `integer`

Duration of the session in seconds.

**amount** `string`

Total charge incurred for creating the session.

**total\_call\_count** `integer`

Total number of individual calls (call\_uuids) in the session.

**total\_call\_amount** `string`

Total billed amount for all calls within the session.

**total\_call\_billed\_duration** `integer`

Total rounded bill duration (seconds) for all calls.

**total\_session\_amount** `string`

Total charges for hosting the session, including call and session creation fees.

**interaction** `object`

Interaction object containing session interactions.

### Example Object

```json theme={null}
{
  "first_party": "919003459051",
  "second_party": "918197241073",
  "virtual_number": "912269947011",
  "status": "active",
  "initiate_call_to_first_party": false,
  "first_party_pin": "1234",
  "second_party_pin": "4321",
  "is_pin_authentication_required": true,
  "generate_pin": false,
  "generate_pin_length": 4,
  "session_uuid": "c28b77d4-21e7-43bd-9447-04bfee92e651",
  "callback_url": "",
  "callback_method": "POST",
  "created_time": "2024-02-01 06:28:15 +0000 UTC",
  "modified_time": "2024-02-01 06:28:37 +0000 UTC",
  "expiry_time": "2024-02-01 06:58:15 +0000 UTC",
  "duration": 1800,
  "amount": 0,
  "call_time_limit": 14400,
  "ring_timeout": 45,
  "record": true,
  "record_file_format": "mp3",
  "recording_callback_url": "",
  "recording_callback_method": "POST",
  "interaction": null,
  "total_call_amount": 0,
  "total_call_count": 0,
  "total_call_billed_duration": 0,
  "total_session_amount": 0,
  "last_interaction_time": ""
}
```

***

## The Interaction Object

The Interaction object is nested within a session. A masking session can contain multiple interactions. Each interaction within a session has a maximum of two communication legs, regardless of the direction of the call.

### Attributes

**first\_party\_resource\_url** `string`

URL of the call-leg resource created for the first party. This field is null if a call is exchanged between the Plivo virtual number and the second party but has not yet been initiated for the first party.

**second\_party\_resource\_url** `string`

URL of the call-leg resource created for the second party. This field is null if a call is exchanged between the Plivo virtual number and the first party but has not yet been initiated for the second party.

**recording\_resource\_url** `string`

URL of the recording resource for the interaction. This field will be null when one of the participants didn't pick up the call.

***

## Create a Session

Create a number masking session using the real phone numbers of two parties. Plivo returns a virtual number from your account that either party can call to connect anonymously.

```
POST https://api.plivo.com/v1/Account/{auth_id}/Masking/Session
```

### Arguments

**first\_party** `string` *required*

The actual phone number of the first party.

**second\_party** `string` *required*

The actual phone number of the second party.

**geomatch** `boolean`

Specifies if the country of the virtual number must match the first\_party number. Default: `true`.

**subaccount** `string`

Specifies the sub-account auth ID for which the session is created.

**session\_expiry** `integer`

Time in seconds after which session mapping ends. Default: 3600.

**call\_time\_limit** `integer`

Time in seconds after which the call disconnects. Default: 3600.

**ring\_timeout** `integer`

Time in seconds after which ringing stops. Default: 120.

**initiate\_call\_to\_first\_party** `boolean`

If `true`, Plivo calls first party immediately and bridges to second party. Default: `false`.

**callback\_url** `string`

URL to receive session events and status updates.

**callback\_method** `string`

HTTP method to invoke callback\_url. Values: `GET`, `POST`. Default: `POST`.

**record** `boolean`

Call recording status. Default: `false`. If `true`, recording starts after both parties answer.

**recording\_callback\_url** `string`

URL where call recordings are sent.

**record\_file\_format** `string`

Audio format for recording. Values: `mp3`, `wav`. Default: `mp3`.

**recording\_callback\_method** `string`

HTTP method to invoke recording\_callback\_url. Values: `GET`, `POST`. Default: `POST`.

**first\_party\_play\_url** `string`

URL to .mp3 or .wav file played to first party before connecting.

**second\_party\_play\_url** `string`

URL to .mp3 or .wav file played to second party before connecting.

**is\_pin\_authentication\_required** `boolean`

Specifies whether PIN authentication is necessary for unidentified callers. Default: `false`.

**generate\_pin** `boolean`

Indicates if Plivo generates the PIN. Only when is\_pin\_authentication\_required is `true`. Default: `false`.

**generate\_pin\_length** `integer`

Length of the PIN to be generated. Applicable when generate\_pin is `true`. Default: 4, Min: 4, Max: 15.

**first\_party\_pin** `string`

The PIN for the first party. Must differ from second\_party\_pin. Length: 4-15 digits.

**second\_party\_pin** `string`

The PIN for the second party. Must differ from first\_party\_pin. Length: 4-15 digits.

**pin\_prompt\_play** `string`

URL for playback prompting PIN entry. Required when PIN is activated. Must be .mp3 or .wav.

**pin\_retry** `integer`

Number of PIN retries allowed. Values: 0-5. Default: 1.

**pin\_retry\_wait** `integer`

Wait time in seconds before retrying PIN. Default: 5, Min: 5, Max: 10.

**incorrect\_pin\_play** `string`

URL for playback when incorrect PIN entered. Must be .mp3 or .wav.

**unknown\_caller\_play** `string`

URL for playback when unknown caller calls the virtual number. Must be .mp3 or .wav.

**force\_pin\_authentication** `boolean`

Requires PIN even for registered numbers. Only applies if PIN authentication is required. Default: `false`.

**create\_session\_with\_single\_party** `boolean`

Allows session creation with only one party. Default: `false`.

**virtual\_number\_cooloff\_period** `integer`

Cool-off period in seconds before the virtual number can be reused. Default: 0, Max: 3600.

> [!NOTE]
>
> The following parameters cannot be updated during an active session:
>
> * first\_party, second\_party
> * initiate\_call\_to\_first\_party
> * is\_pin\_authentication\_required
> * pin\_prompt\_play, pin\_retry, pin\_retry\_wait
> * incorrect\_pin\_play, unknown\_caller\_play
> * geomatch, subaccount

### Example

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

client = plivo.RestClient('<auth_id>', '<auth_token>')

response = client.masking_sessions.create_masking_session(
    first_party="+12025550000",
    second_party="+12025551111"
)
print(response)
```

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

const client = new plivo.Client('<auth_id>', '<auth_token>');

client.maskingSession.createMaskingSession(
    '+12025550000', '+12025551111',
    { callTimeLimit: 600 }
).then(response => console.log(response));
```

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

client = Plivo::RestClient.new('<auth_id>', '<auth_token>')

response = client.maskingsession.create(
    first_party: '+12025550000',
    second_party: '+12025551111'
)
puts response
```

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

$client = new RestClient('<auth_id>', '<auth_token>');

$response = $client->maskingSessions->createMaskingSession(
    '+12025550000',
    '+12025551111'
);
print_r($response);
```

```java Java theme={null}
import com.plivo.api.Plivo;
import com.plivo.api.models.maskingsession.MaskingSession;
import com.plivo.api.models.maskingsession.MaskingSessionCreateResponse;

Plivo.init("<auth_id>", "<auth_token>");

MaskingSessionCreateResponse response = MaskingSession
    .creator("+12025550000", "+12025551111")
    .create();
System.out.println(response);
```

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

var api = new PlivoApi("<auth_id>", "<auth_token>");

var response = api.MaskingSession.Create(
    firstParty: "+12025550000",
    secondParty: "+12025551111"
);
Console.WriteLine(response);
```

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

import (
    "fmt"
    "github.com/plivo/plivo-go/v7"
)

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

    response, _ := client.MaskingSession.CreateMaskingSession(
        plivo.CreateMaskingSessionParams{
            FirstParty:  "+12025550000",
            SecondParty: "+12025551111",
        },
    )
    fmt.Printf("Response: %#v\n", response)
}
```

```bash cURL theme={null}
curl -X POST "https://api.plivo.com/v1/Account/{auth_id}/Masking/Session" \
    -H "Content-Type: application/json" \
    -u '<auth_id>:<auth_token>' \
    -d '{
        "first_party": "+12025550000",
        "second_party": "+12025551111"
    }'
```

### Response

**api\_id** `string`

Unique identifier for the API request.

**session\_uuid** `string`

Unique identifier for the session.

**virtual\_number** `string`

Plivo phone number to be dialed for connecting with the other participant.

**message** `string`

Status of the request. Returns `Session created` on successful session creation.

**session** `object`

The created session object — see [The Session Object](#the-session-object).

```json theme={null}
{
  "api_id": "ae245217-f78e-4939-bc48-d4b8ef05cf66",
  "session_uuid": "4189591e-d004-4801-abdf-8893c15e5dcd",
  "virtual_number": "+912269947011",
  "message": "Session created",
  "session": {
    "first_party": "12025550000",
    "second_party": "12025551111",
    "virtual_number": "912269947011",
    "status": "active",
    "initiate_call_to_first_party": false,
    "session_uuid": "4189591e-d004-4801-abdf-8893c15e5dcd",
    "callback_url": "",
    "callback_method": "POST",
    "created_time": "2024-01-03 13:35:51 +0000 UTC",
    "modified_time": "2024-01-03 13:35:51 +0000 UTC",
    "expiry_time": "2024-01-03 14:05:51 +0000 UTC",
    "duration": 1800,
    "amount": 0,
    "call_time_limit": 14400,
    "ring_timeout": 45,
    "record": false,
    "record_file_format": "mp3",
    "recording_callback_url": "",
    "recording_callback_method": "POST",
    "interaction": null,
    "total_call_amount": 0,
    "total_call_count": 0,
    "total_call_billed_duration": 0,
    "total_session_amount": 0,
    "last_interaction_time": ""
  }
}
```

***

## Retrieve a Session

Fetch details of an existing masking session.

```
GET https://api.plivo.com/v1/Account/{auth_id}/Masking/Session/{session_uuid}
```

### Example

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

client = plivo.RestClient('<auth_id>', '<auth_token>')

response = client.masking_sessions.get_masking_session('<session_uuid>')
print(response)
```

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

const client = new plivo.Client('<auth_id>', '<auth_token>');

client.maskingSession.getMaskingSession('<session_uuid>')
    .then(response => console.log(response));
```

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

client = Plivo::RestClient.new('<auth_id>', '<auth_token>')

response = client.maskingsession.get('<session_uuid>')
puts response
```

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

$client = new RestClient('<auth_id>', '<auth_token>');

$response = $client->maskingSessions->getMaskingSession('<session_uuid>');
print_r($response);
```

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

Plivo.init("<auth_id>", "<auth_token>");

MaskingSession response = MaskingSession.getter("<session_uuid>").get();
System.out.println(response);
```

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

var api = new PlivoApi("<auth_id>", "<auth_token>");

var response = api.MaskingSession.Get(sessionUuid: "<session_uuid>");
Console.WriteLine(response);
```

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

import (
    "fmt"
    "github.com/plivo/plivo-go/v7"
)

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

    response, _ := client.MaskingSession.GetMaskingSession("<session_uuid>")
    fmt.Printf("Response: %#v\n", response)
}
```

```bash cURL theme={null}
curl "https://api.plivo.com/v1/Account/{auth_id}/Masking/Session/{session_uuid}" \
    -u '<auth_id>:<auth_token>'
```

### Response

**api\_id** `string`

Unique identifier for the API request.

**response** `object`

The session object — see [The Session Object](#the-session-object).

```json theme={null}
{
  "api_id": "678c8b24-b703-43aa-8690-d28e7f163d18",
  "response": {
    "first_party": "919003459051",
    "second_party": "918197241073",
    "virtual_number": "912269947011",
    "status": "expired",
    "initiate_call_to_first_party": false,
    "session_uuid": "c28b77d4-21e7-43bd-9447-04bfee92e651",
    "callback_url": "",
    "callback_method": "POST",
    "created_time": "2024-02-01 06:28:15 +0000 UTC",
    "modified_time": "2024-02-01 06:28:37 +0000 UTC",
    "expiry_time": "2024-02-01 06:58:15 +0000 UTC",
    "duration": 1800,
    "amount": 0,
    "call_time_limit": 14400,
    "ring_timeout": 45,
    "record": true,
    "record_file_format": "mp3",
    "recording_callback_url": "",
    "recording_callback_method": "POST",
    "interaction": null,
    "total_call_amount": 0,
    "total_call_count": 0,
    "total_call_billed_duration": 0,
    "total_session_amount": 0,
    "last_interaction_time": ""
  }
}
```

***

## List All Sessions

Fetch details of all existing masking sessions.

```
GET https://api.plivo.com/v1/Account/{auth_id}/Masking/Session
```

### Arguments

**first\_party** `string`

Filter by first party phone number.

**second\_party** `string`

Filter by second party phone number.

**virtual\_number** `string`

Filter by virtual number assigned for the session.

**status** `string`

Filter by status. Values: `active`, `expired`, `all`. Default: `all`.

**created\_time** `string`

Filter sessions by creation time. Format: `YYYY-MM-DD HH:MM[:ss[.uuuuuu]]`. Supports variants: `created_time__gt`, `created_time__gte`, `created_time__lt`, `created_time__lte`. Default window: 7 days. Max: 30 days.

**expiry\_time** `string`

Filter sessions by expiry time. Format: `YYYY-MM-DD HH:MM[:ss[.uuuuuu]]`. Supports variants: `expiry_time__gt`, `expiry_time__gte`, `expiry_time__lt`, `expiry_time__lte`. Default window: 7 days. Max: 30 days.

**duration** `string`

Filter sessions by duration in seconds. Supports variants: `duration__gt`, `duration__gte`, `duration__lt`, `duration__lte`.

**limit** `integer`

Number of results per page. Min: 1, Max: 20. Default: 20.

**offset** `integer`

Number of results to skip. Used for pagination.

### Example

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

client = plivo.RestClient('<auth_id>', '<auth_token>')

response = client.masking_sessions.list_masking_session(status='active')
print(response)
```

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

const client = new plivo.Client('<auth_id>', '<auth_token>');

client.maskingSession.listMaskingSession({ limit: 10 })
    .then(response => console.log(response));
```

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

client = Plivo::RestClient.new('<auth_id>', '<auth_token>')

response = client.maskingsession.list()
puts response
```

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

$client = new RestClient('<auth_id>', '<auth_token>');

$response = $client->maskingSessions->listMaskingSession(['status' => 'active']);
print_r($response);
```

```java Java theme={null}
import com.plivo.api.Plivo;
import com.plivo.api.models.base.ListResponse;
import com.plivo.api.models.maskingsession.MaskingSession;

Plivo.init("<auth_id>", "<auth_token>");

ListResponse<MaskingSession> response = MaskingSession.lister().list();
System.out.println(response);
```

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

var api = new PlivoApi("<auth_id>", "<auth_token>");

var response = api.MaskingSession.List();
Console.WriteLine(response);
```

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

import (
    "fmt"
    "github.com/plivo/plivo-go/v7"
)

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

    response, _ := client.MaskingSession.ListMaskingSession(
        plivo.ListSessionFilterParams{Limit: 10},
    )
    fmt.Printf("Response: %#v\n", response)
}
```

```bash cURL theme={null}
curl "https://api.plivo.com/v1/Account/{auth_id}/Masking/Session/?status=active" \
    -u '<auth_id>:<auth_token>'
```

### Response

**api\_id** `string`

Unique identifier for the API request.

**response** `object`

Object containing pagination metadata (`meta`: `limit`, `offset`, `total_count`, and `next`/`previous` page URLs) and an `objects` array of session objects — see [The Session Object](#the-session-object).

```json theme={null}
{
  "api_id": "7d962130-8eb6-49f1-920b-ae4609bf6dfe",
  "response": {
    "meta": {
      "limit": 20,
      "next": null,
      "offset": 0,
      "previous": null,
      "total_count": 1
    },
    "objects": [
      {
        "amount": 0,
        "call_time_limit": 14400,
        "callback_method": "POST",
        "callback_url": "",
        "created_time": "2024-02-01 06:28:15 +0000 UTC",
        "duration": 1800,
        "expiry_time": "2024-02-01 06:58:15 +0000 UTC",
        "first_party": "919003459051",
        "initiate_call_to_first_party": false,
        "interaction": null,
        "last_interaction_time": "",
        "modified_time": "2024-02-01 06:28:37 +0000 UTC",
        "record": true,
        "record_file_format": "mp3",
        "recording_callback_method": "POST",
        "recording_callback_url": "",
        "resource_uri": "/v1/Account/MAOTQ3NGFLNZRMZME1MT/Masking/Session/c28b77d4-21e7-43bd-9447-04bfee92e651/",
        "ring_timeout": 45,
        "second_party": "918197241073",
        "session_uuid": "c28b77d4-21e7-43bd-9447-04bfee92e651",
        "status": "expired",
        "total_call_amount": 0,
        "total_call_billed_duration": 0,
        "total_call_count": 0,
        "total_session_amount": 0,
        "virtual_number": "912269947011"
      }
    ]
  }
}
```

***

## Update a Session

Update an existing masking session.

```
POST https://api.plivo.com/v1/Account/{auth_id}/Masking/Session/{session_uuid}
```

### Arguments

**session\_expiry** `integer`

Time in seconds after which the session mapping will end. Default: 3600.

**call\_time\_limit** `integer`

Time in seconds after which the call will be disconnected. Default: 3600.

**ring\_timeout** `integer`

Time in seconds after which the ring will be disconnected. Default: 120.

**callback\_url** `string`

URL to receive session events and status updates.

**callback\_method** `string`

HTTP verb to invoke callback\_url. Values: `GET`, `POST`. Default: `POST`.

**record** `boolean`

Recording status for phone calls. Default: `false`.

**recording\_callback\_url** `string`

URL to which the call recording is sent.

**record\_file\_format** `string`

Audio format for the recording. Values: `mp3`, `wav`. Default: `mp3`.

**recording\_callback\_method** `string`

HTTP verb to invoke recording\_callback\_url. Values: `GET`, `POST`. Default: `POST`.

**first\_party\_play\_url** `string`

URL that returns an .mp3 or .wav file to be played to the first party.

**second\_party\_play\_url** `string`

URL that returns an .mp3 or .wav file to be played to the second party.

**first\_party** `string`

The phone number of the first participant. Only applicable when session was created with `create_session_with_single_party` set to `true`.

**second\_party** `string`

The phone number of the second participant. Only applicable when session was created with `create_session_with_single_party` set to `true`.

### Example

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

client = plivo.RestClient('<auth_id>', '<auth_token>')

response = client.masking_sessions.update_masking_session(
    session_uuid='<session_uuid>',
    call_time_limit=3600,
    record=True
)
print(response)
```

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

const client = new plivo.Client('<auth_id>', '<auth_token>');

client.maskingSession.updateMaskingSession('<session_uuid>', {
    sessionExpiry: 120
}).then(response => console.log(response));
```

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

client = Plivo::RestClient.new('<auth_id>', '<auth_token>')

response = client.maskingsession.update(
    '<session_uuid>',
    { call_time_limit: 1440, record: true }
)
puts response
```

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

$client = new RestClient('<auth_id>', '<auth_token>');

$response = $client->maskingSessions->updateMaskingSession(
    '<session_uuid>',
    ['call_time_limit' => 3600]
);
print_r($response);
```

```java Java theme={null}
import com.plivo.api.Plivo;
import com.plivo.api.models.maskingsession.MaskingSession;
import com.plivo.api.models.maskingsession.MaskingSessionUpdateResponse;

Plivo.init("<auth_id>", "<auth_token>");

MaskingSessionUpdateResponse response = MaskingSession.updater("<session_uuid>")
    .callTimeLimit(14400)
    .record(true)
    .update();
System.out.println(response);
```

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

var api = new PlivoApi("<auth_id>", "<auth_token>");

var response = api.MaskingSession.Update(
    sessionUuid: "<session_uuid>",
    sessionExpiry: 6000
);
Console.WriteLine(response);
```

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

import (
    "fmt"
    "github.com/plivo/plivo-go/v7"
)

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

    response, _ := client.MaskingSession.UpdateMaskingSession(
        plivo.UpdateMaskingSessionParams{SessionExpiry: 120},
        "<session_uuid>",
    )
    fmt.Printf("Response: %#v\n", response)
}
```

```bash cURL theme={null}
curl -X POST "https://api.plivo.com/v1/Account/{auth_id}/Masking/Session/{session_uuid}" \
    -H "Content-Type: application/json" \
    -u '<auth_id>:<auth_token>' \
    -d '{"record": true}'
```

### Response

**api\_id** `string`

Unique identifier for the API request.

**message** `string`

Status of the request. Returns `Session updated` on a successful update.

**session** `object`

The updated session object — see [The Session Object](#the-session-object).

```json theme={null}
{
  "api_id": "32d333cb-3709-4b9b-b27b-3296aca6e1cc",
  "message": "Session updated",
  "session": {
    "first_party": "919003459051",
    "second_party": "918197241073",
    "virtual_number": "912269947011",
    "status": "active",
    "initiate_call_to_first_party": false,
    "session_uuid": "c28b77d4-21e7-43bd-9447-04bfee92e651",
    "callback_url": "",
    "callback_method": "POST",
    "created_time": "2024-02-01 06:28:15 +0000 UTC",
    "modified_time": "2024-02-01 06:28:37 +0000 UTC",
    "expiry_time": "2024-02-01 06:58:15 +0000 UTC",
    "duration": 1800,
    "amount": 0,
    "call_time_limit": 14400,
    "ring_timeout": 45,
    "record": true,
    "record_file_format": "mp3",
    "recording_callback_url": "",
    "recording_callback_method": "POST",
    "interaction": null,
    "total_call_amount": 0,
    "total_call_count": 0,
    "total_call_billed_duration": 0,
    "total_session_amount": 0,
    "last_interaction_time": ""
  }
}
```

***

## Expire a Session

Terminate an ongoing session and mark it as expired.

```
DELETE https://api.plivo.com/v1/Account/{auth_id}/Masking/Session/{session_uuid}
```

### Example

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

client = plivo.RestClient('<auth_id>', '<auth_token>')

response = client.masking_sessions.delete_masking_session('<session_uuid>')
print(response)
```

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

const client = new plivo.Client('<auth_id>', '<auth_token>');

client.maskingSession.deleteMaskingSession('<session_uuid>')
    .then(response => console.log(response));
```

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

client = Plivo::RestClient.new('<auth_id>', '<auth_token>')

response = client.maskingsession.delete('<session_uuid>')
puts response
```

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

$client = new RestClient('<auth_id>', '<auth_token>');

$response = $client->maskingSessions->deleteMaskingSession('<session_uuid>');
print_r($response);
```

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

Plivo.init("<auth_id>", "<auth_token>");

MaskingSession.deleter("<session_uuid>").delete();
```

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

var api = new PlivoApi("<auth_id>", "<auth_token>");

var response = api.MaskingSession.Delete(sessionUuid: "<session_uuid>");
Console.WriteLine(response);
```

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

import (
    "fmt"
    "github.com/plivo/plivo-go/v7"
)

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

    response, _ := client.MaskingSession.DeleteMaskingSession("<session_uuid>")
    fmt.Printf("Response: %#v\n", response)
}
```

```bash cURL theme={null}
curl -X DELETE "https://api.plivo.com/v1/Account/{auth_id}/Masking/Session/{session_uuid}" \
    -u '<auth_id>:<auth_token>'
```

***

## Session Callbacks

### Session Status Callback

Configure the `callback_url` to receive important session events and status updates.

#### Events

**SessionFirstPartyAnswer** `event`

Triggered when the first party answers the call.

**SessionSecondPartyRing** `event`

Triggered when the second party's phone starts ringing.

**SessionSecondPartyAnswer** `event`

Triggered when the second party answers the call.

**SessionSecondPartyHangup** `event`

Triggered when the second party disconnects the call.

**SessionFirstPartyHangup** `event`

Triggered when the first party disconnects the call.

**SessionPinAuthenticationStatus** `event`

Triggered when the PIN authentication status is success, failed, or if the call is from an authorized caller.

**SessionTimeout** `event`

Triggered when the session expires.

**SessionPartiesHangup** `event`

Triggered when the session call is done.

#### Callback Attributes

**EventName** `string`

Event that triggered this callback.

**EventTimestamp** `string`

Timestamp in UTC at which the event occurred.

**SessionUUID** `string`

Unique ID of the masking session.

**From** `string`

Actual from number used to interact with the virtual number.

**To** `string`

Actual to number dialing out from the virtual number.

**VirtualNumber** `string`

The virtual number used in the session.

**PinAuthenticationStatus** `string`

Status of the PIN authentication. Values: `success`, `failed`, `AuthorizedCaller`.

**PinRetryCounter** `integer`

Indicates the PIN retry counter due to incorrect PIN input.

**Amount** `string`

Total amount incurred for the call.

**BilledDuration** `string`

Duration in seconds for which the call was billed.

**Duration** `string`

Actual duration of the call in seconds.

**PlivoHangupCause** `string`

Reason for the call termination.

**PlivoHangupCauseCode** `integer`

A unique integer code for the termination cause.

**SequenceNumber** `string`

Indicates the sequence of the callback. Helpful for sorting events.

***

### Session Recording Callback

Configure the `recording_callback_url` to receive recording-related callback events.

#### Events

**SessionRecordingInitiated** `event`

Triggered when the first party and the second party are connected via the virtual phone number and the recording begins.

**SessionRecordingCompleted** `event`

Triggered when one of the parties disconnects the call.

**SessionRecordingFailed** `event`

Triggered when the record attribute is set to true but the recording could not be started.

#### Recording Callback Attributes

**EventName** `string`

Event that triggered this callback.

**EventTimestamp** `string`

Timestamp at which the event occurred.

**SessionUUID** `string`

Unique ID of the masking session.

**From** `string`

Actual from number used to interact with the virtual number.

**To** `string`

Actual to number dialing out from the virtual number.

**VirtualNumber** `string`

The virtual number used in the session.

**RecordingUUID** `string`

Unique identifier of the recording file.

**RecordingURL** `string`

Actual media URL path of the recording.

**RecordingResourceURL** `string`

Complete URL path to the recording resource URL.

**RecordingDuration** `string`

Duration of recording in seconds.

**RecordingStartTime** `string`

UTC Timestamp at which the recording started.

**RecordingEndTime** `string`

UTC Timestamp at which the recording ended.

**RecordingFormat** `string`

Format of the recording. Values: `.mp3`, `.wav`.

**SequenceNumber** `string`

Indicates the sequence of the callback.