Session API

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

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

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

import plivo

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

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

Response

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

import plivo

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

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

Response

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

import plivo

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

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

Response

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

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)

Response

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

import plivo

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

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

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.

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.

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.

Concepts

API Reference

The Session Object

Attributes

Example Object

The Interaction Object

Attributes

Create a Session

Arguments

Example

Response

Retrieve a Session

Example

Response

List All Sessions

Arguments

Example

Response

Update a Session

Arguments

Example

Response

Expire a Session

Example

Session Callbacks

Session Status Callback

Events

Callback Attributes

Session Recording Callback

Events

Recording Callback Attributes

Concepts

API Reference

​The Session Object

​Attributes

​Example Object

​The Interaction Object

​Attributes

​Create a Session

​Arguments

​Example

​Response

​Retrieve a Session

​Example

​Response

​List All Sessions

​Arguments

​Example

​Response

​Update a Session

​Arguments

​Example

​Response

​Expire a Session

​Example

​Session Callbacks

​Session Status Callback

​Events

​Callback Attributes

​Session Recording Callback

​Events

​Recording Callback Attributes

The Session Object

Attributes

Example Object

The Interaction Object

Attributes

Create a Session

Arguments

Example

Response

Retrieve a Session

Example

Response

List All Sessions

Arguments

Example

Response

Update a Session

Arguments

Example

Response

Expire a Session

Example

Session Callbacks

Session Status Callback

Events

Callback Attributes

Session Recording Callback

Events

Recording Callback Attributes