import plivo

client = plivo.RestClient(auth_id='<auth_id>', auth_token='<auth_token>')
response = client.masking_sessions.update_masking_session(
                                                      session_uuid="session_uuid",
                                                      call_time_limit=3600,
                                                      record=true)
print(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,
    "first_party_pin": "1234",
    "second_party_pin": "4321",
    "is_pin_authentication_required": true,
    "generate_pin": false,
    "generate_pin_length": 4,
    "pin_ prompt_play": "https://play.s3.eu-north-1.amazonaws.com/pin_prompt.wav",
    "pin_retry": 1,
    "pin_retry_wait": "5",
    "incorrect_pin_play": "https://play.s3.eu-north-1.amazonaws.com/incorrect_pin.wav",
    "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,
    "first_party_play_url": "",
    "second_party_play_url": "",
    "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": ""
  }
}

​
Create a number masking session

You create a number masking session using the real phone numbers of the two parties that need to be connected. Plivo returns a virtual number from your account in response to the API request.

  • If one party makes a call to the virtual number, the call is connected to the other party.
  • The caller ID of the outbound call to the second party is the Plivo virtual number.

This method creates a session to anonymously connect two participants.

POST
https://api.plivo.com/v1/Account/{Auth ID}/Masking/Session

​
Attributes

NameTypeDescription
first_partystring (Required)The actual phone number of the first party.
second_partystring (Required)The actual phone number of the second party.
geomatchBoolean (Optional)Specifies if the country of the virtual number used for session allocation must match the first_party number.
Default: true.
is_pin_authentication_requiredbooleanSpecifies whether PIN authentication is necessary when the call originates from an unidentified caller.
Default: false.
generate_pinboolean (Conditional)Indicates if Plivo has to generate the PIN for the session.
Only when is_pin_authentication_required is true.
Default: false.
generate_pin_lengthint (Conditional)Length of the PIN to be generated by Plivo.
Applicable when generate_pin is true.
Default: 4, Min: 4, Max: 15.
first_party_pinstringThe PIN for the first party when using a secondary number.
Must differ from second_party_pin.
Length: 4-15 digits.
second_party_pinstringThe PIN for the second party when using a secondary number.
Must differ from first_party_pin.
Length: 4-15 digits.
subaccountString (Optional)Specifies the sub-account auth ID for which the session is created.
pin_prompt_playstringURL for playback prompting PIN entry.
Required when PIN is activated.
Must be .mp3 or .wav file.
pin_retryintegerNumber of PIN retries allowed.
Allowed: 0-5.
Default: 1.
pin_retry_waitintegerWait time in seconds before retrying PIN.
Default: 5, Min: 5, Max: 10.
incorrect_pin_playstringURL for playback when incorrect PIN entered.
Must be .mp3 or .wav file.
unknown_caller_playstringURL for playback when unknown caller calls the virtual number.
Must be .mp3 or .wav file.
recordbooleanCall recording status.
Default: false.
If true, recording starts after both parties answer.
recording_callback_urlstringURL where call recordings are sent.
record_file_formatstringAudio format for recording.
Allowed: mp3, wav.
Default: mp3.
recording_callback_methodstringHTTP method to invoke recording_callback_url.
Allowed: GET, POST.
Default: POST.
session_expiryintegerTime in seconds after which session mapping ends.
Default: 3600.
call_time_limitintegerTime in seconds after which the call disconnects.
Default: 3600.
initiate_call_to_first_partybooleanIf true, Plivo calls first party immediately and bridges to second party.
Default: false.
callback_urlstringURL to receive session events and status updates.
callback_methodstringHTTP method to invoke callback_url.
Allowed: GET, POST.
Default: POST.
ring_timeoutintegerTime in seconds after which ringing stops.
Default: 120.
first_party_play_urlstringURL to .mp3 or .wav file played to first party before connecting second party.
second_party_play_urlstringURL to .mp3 or .wav file played to second party before connecting first party.
create_session_with_single_partyboolean (Optional)Allows session creation with only one party.
Default: false.
virtual_number_cooloff_periodinteger (Optional)Cool-off period in seconds before the virtual number can be reused.
Default: 0, Max: 3600.
force_pin_authenticationboolean (Conditional)Requires PIN even for registered numbers.
Only applies if PIN authentication is required.
Default: false.

The below parameters cannot be updated for the 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
import plivo

client = plivo.RestClient(auth_id='<auth_id>', auth_token='<auth_token>')
response = client.masking_sessions.update_masking_session(
                                                      session_uuid="session_uuid",
                                                      call_time_limit=3600,
                                                      record=true)
print(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,
    "first_party_pin": "1234",
    "second_party_pin": "4321",
    "is_pin_authentication_required": true,
    "generate_pin": false,
    "generate_pin_length": 4,
    "pin_ prompt_play": "https://play.s3.eu-north-1.amazonaws.com/pin_prompt.wav",
    "pin_retry": 1,
    "pin_retry_wait": "5",
    "incorrect_pin_play": "https://play.s3.eu-north-1.amazonaws.com/incorrect_pin.wav",
    "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,
    "first_party_play_url": "",
    "second_party_play_url": "",
    "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": ""
  }
}