import plivo

client = plivo.RestClient(auth_id='<auth_id>', auth_token='<auth_token>')
response = client.masking_sessions.create_masking_session(
                                                      first_party="+12025550XXX",
                                                      second_party="+12025551XXX")
print(response)

{
  "api_id": "ae245217-f78e-4939-bc48-d4b8ef05cf66",
  "session_uuid": "4189591e-d004-4801-abdf-8893c15e5dcd",
  "virtual_number": "+912269947011",
  "message": "Session created",
  "session": {
    "first_party": "919003459XXX",
    "second_party": "919840037XXX",
    "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": "4189591e-d004-4801-abdf-8893c15e5dcd",
    "callback_url": "https://webhook.site/0ece3c18-f1e4-48a8-98fe-b8f651e53eef",
    "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,
    "first_party_play_url": "https://play.s3.eu-north-1.amazonaws.com/agent.wav",
    "second_party_play_url": "https://play.s3.eu-north-1.amazonaws.com/customer.wav",
    "record": false,
    "subaccount": "SAOWRKMGU3YZCTZJXXX",
    "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 parameters below cannot be updated during 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.create_masking_session(
                                                      first_party="+12025550XXX",
                                                      second_party="+12025551XXX")
print(response)

{
  "api_id": "ae245217-f78e-4939-bc48-d4b8ef05cf66",
  "session_uuid": "4189591e-d004-4801-abdf-8893c15e5dcd",
  "virtual_number": "+912269947011",
  "message": "Session created",
  "session": {
    "first_party": "919003459XXX",
    "second_party": "919840037XXX",
    "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": "4189591e-d004-4801-abdf-8893c15e5dcd",
    "callback_url": "https://webhook.site/0ece3c18-f1e4-48a8-98fe-b8f651e53eef",
    "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,
    "first_party_play_url": "https://play.s3.eu-north-1.amazonaws.com/agent.wav",
    "second_party_play_url": "https://play.s3.eu-north-1.amazonaws.com/customer.wav",
    "record": false,
    "subaccount": "SAOWRKMGU3YZCTZJXXX",
    "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": ""
  }
}