Number Masking

If the session is created with create_session_with_single_party set to true, the following flows are possible:

• If the session is created without PIN authentication (is_pin_authentication set to false), any party calling the virtual number will be connected directly to the first_party or second_party number.
• If the session is created with a single party number and PIN authentication is enabled (is_pin_authentication set to true), any party calling the virtual number will be connected to the first_party or second_party number after successful PIN authentication.
• If the missing party details are not updated and an interaction is initiated with the registered party in a session, any call made by the registered party (either the first or second party) to the virtual number will be routed based on the last interaction. For example, if only the customer number is used to create a session, an agent calling from number X to the virtual number will be directly connected with the customer (the registered party in the session). If the customer calls back to the virtual number, Plivo will route the call to the agent’s number X based on the last interaction.

The force_pin_authentication parameter is a subset of the is_authentication_required parameter. If force_pin_authentication is set to true, all calls to the virtual number will be authenticated with a PIN before connecting the call to the desired party, even when the call is initiated from the session's registered number.

The virtual number cool-off period is useful when you don’t want the number used in a session to be utilized for any other session for a specified time period after the session ends.

You can update the active session with either first_party or second_party numbers only when the session is created with create_session_with_single_party set to true.

You can create a number masking session with a single party by setting the create_session_with_single_party parameter to true. The default value is set to false. Additionally, a value for either first_party or second_party is required.

No, there are no charges involved in replacing a sub-optimal number with a fully functional one.

Your originally purchased number remains preserved within your account and will be automatically restored once the third-party outage is resolved.

Plivo collaborates with third-party providers to allocate virtual numbers and manage end-operator connectivity during number masking sessions. While Plivo guarantees higher SLAs and uptime for our services, potential problems with a third party may still impact your number masking sessions.

If there’s an issue, Plivo will promptly intervene to replace a sub-optimal virtual number with a fully functional one. We aim to ensure uninterrupted communication for our customers.

The SessionVirtualNumberReplaced event is triggered when the health of the number used in the session deteriorates. Plivo substitutes the sub-optimal number with a temporary one to maintain the session and prevent any call connectivity issues. The VirtualNumber field included in this event contains the fully functional number, serving to notify you to update the old number with the new virtual number in your application.

Currently, we don't provide a dedicated number pool specifically for number masking. However, you can allocate numbers to a subaccount and create sessions by specifying the subaccount auth details. This ensures that virtual number allocation is aligned with the subaccount used in the session. Plivo will exclusively access and use the numbers associated with the specified subaccount. 

cURL

curl -X POST "https://api.plivo.com/v1/Account/{Auth ID}/Masking/Session" \
-H "Content-Type: application/json" \
-d '{
  "first_party": "+919003459XXX",
  "second_party": "+919840037XXX",
  "is_pin_authentication_required": true,
  "first_party_pin": 1234,
  "second_party_pin": 4321,
  "pin_prompt_play": "https://play.s3.eu-north-1.amazonaws.com/pin_prompt.wav",
  "geomatch": true,
  "subaccount": "SAOWRKMGU3YZCTZJXXX",
  "incorrect_pin_play": "https://play.s3.eu-north-1.amazonaws.com/incorrect_pin.wav"
}

The above request will create a number masking session with the virtual number that belongs to the subaccount auth ’SAOWRKMGU3YZCTZJXXX’.

Number masking helps protect the privacy of communication by anonymizing the original phone numbers of the parties involved. It uses an intermediary virtual number that masks the actual numbers during the call. Plivo's Number Masking API is designed to seamlessly manage both the assignment of virtual numbers and the entire call flow process. To initiate a masked session, simply send an API request including the real phone numbers of the call participants. In response, Plivo allocates a virtual number from your account that facilitates the masked session.

For more information, please refer to our detailed documentation.

Integrating with Plivo's robust number masking solution can be accomplished through our packaged API or by utilizing our Software Development Kits (SDKs). Plivo offers SDKs in a wide range of programming languages, including Python, Ruby, Java, Node.js, .NET, PHP, and Go.

A number masking session is a unique instance facilitated by Plivo, initiated for every combination of first party and second party phone numbers. Within this session, multiple masked phone calls can be made by the parties involved. 

Each session is represented by a Session object, containing attributes such as a unique session identifier, the phone numbers of the parties involved, and a virtual number provided by Plivo to connect them.

As an example, consider a scenario within a ride-hailing app, where a driver and a rider need to connect to coordinate a ride. When the driver initiates contact with the rider, Plivo creates a unique number masking session for their interaction. Within this session, the driver and rider can make multiple calls to coordinate the ride without revealing their personal phone numbers to each other. Each call is part of the same session until it expires or is terminated.

For more information, please visit our number masking concepts section.

Plivo’s Number Masking solution facilitates private communications between two parties by concealing actual phone numbers. 

In scenarios requiring involvement of more than two parties in a single session, such as conference calls or group discussions, Plivo offers a separate solution known as the Multi-party solution. This solution is designed to facilitate multiparty calls and conferences, catering to scenarios where multiple participants need to interact simultaneously. However, this solution does not offer phone number masking. 

Number Masking and Multiparty Calls serve distinct purposes. Number Masking focuses on privacy by concealing phone numbers, while Multiparty Calls cater to situations requiring interactions among multiple participants in a conference setting.

To learn more about the Multiparty solutions, please refer to the API documentation

A number masking interaction refers to a specific call between two parties within a number masking session. In a session, there can be multiple interactions.

Each interaction is represented by a unique Interaction object, which is nested within the corresponding session. The Interaction object includes attributes related to a particular interaction, such as the URL of the call-leg resource created for both the first party and the second party involved in the conversation.

As an example, consider a scenario within a ride-hailing app, where a driver and a rider need to connect to coordinate a ride. During the session, each time the driver initiates a call to the rider or vice versa, a new interaction object is created. Multiple interactions can occur within the same session as the driver and rider communicate back and forth to finalize ride details. Each interaction represents a distinct call between the driver and rider within the overall ride-hailing session.

For more information, please visit our number masking concepts section.

Yes, you can end a number masking session at any time following the interaction by using the expire session API. Terminating a session means that the parties can no longer connect using the virtual number. 

For more details, refer to our expire session API.

By default, the session expiry time is set to 3600 seconds (1 hour). However, you can set session_expiry to a maximum of 24 hours, which is 86400 seconds.

Each interaction within a number masking session is tracked and associated with its respective session. By utilizing commands like get all session or get details of a single session, you can easily retrieve information about the various interactions that occurred within any given session.

Yes, Plivo supports PIN-based authentication to securely connect calls from unregistered numbers of designated users to their intended sessions. This feature is particularly beneficial when users make calls from unknown or secondary numbers that were not registered during the session creation. Callers are prompted to authenticate themselves by entering a unique PIN, effectively mapping unregistered numbers to sessions.

Plivo offers flexibility by allowing one retry for an incorrect PIN entry by default. Should your application require it, this retry limit can be increased up to five attempts.

We have detailed documentation on how virtual number allocation works. Please refer to the virtual number allocation logic.

Absolutely. Plivo allows for the customization of messages for callers dialing from unrecognized numbers, tailored to fit your specific business needs and scenarios. You can set up your preferred message in the unknown_caller_play parameter, in either .mp3 or .wav format. When a call from an unknown number reaches the virtual number and is_pin_authentication_required is set to false, Plivo will play the configured message.

Yes, you can configure a custom prompt for callers from unknown numbers to enter their PIN. This message should be set up in the pin_prompt_play parameter, in formats such as .mp3 or .wav. If a call from an unrecognized number is received and is_pin_authentication_required is set to true, Plivo plays this custom prompt, guiding the caller to authenticate themselves by entering the PIN.

Creating a number masking session with Plivo incurs no additional charges. The standard voice API inbound and outbound charges as well as the number rental charges will apply for the interactions taking place through the virtual number.

Yes, calls within a number masking session are automatically recorded. Recordings are available in .mp3 or .wav format and are securely stored on Plivo's infrastructure. You have the option to disable recording by setting the record attribute to false.

As an added benefit, Plivo offers complimentary storage for these recordings for up to 90 days. Should you require extended storage, it is available for a nominal fee of $0.0004 per minute per month, after the initial 90-day period.

In cases where a call to the virtual number is made from a phone number not recognized as part of the ongoing number masking session there are three options to handle this situation:

1. PIN-based authentication (recommended): Plivo ensures secure communication by requiring a PIN to enter the session. The caller receives a unique PIN and must enter it to connect. This maintains session integrity. Enable PIN-based authentication by setting is_pin_authentication to true during the session creation. (default is false).
2. Unknown caller prompt (optional): If PIN authentication is disabled, use the unknown_caller_play parameter (optional) to play a message instructing the caller to use their registered number. This parameter only accepts .mp3 or .wav files.
3. Call failure (default): If neither PIN authentication nor the unknown caller prompt is enabled, the call will fail.

Please review our quickstart guide and API reference to understand how PIN authentication works.

To avoid incurring charges for recording storage beyond 90 days, you will need to disable the ‘Recording Storage’ feature from the Plivo console. Navigate to the Plivo console → Voice → Other Settings → Recording Storage and set this option to Disabled.

Unfortunately, Plivo currently does not support the transcription of calls within number masking sessions. Transcription services are only available for standard voice calls.

The geomatch attribute plays a crucial role in the allocation of a virtual number at the beginning of a session. When geomatch is set to true, Plivo allocates a virtual number that matches the country code of the initiating caller's number (the first-party number).

No. Updating the geomatch parameter is not allowed for an existing active session.

If no matching country numbers are found, session creation will fail, returning the following response: