How it works

To see how number masking works, suppose you have a web or a mobile application with which you want to connect two participants in a voice call.

1. Your application collects the phone numbers of two participants in a call whose numbers you want to mask.
2. Your application makes a Number Masking API request to Plivo with the phone numbers.
3. Plivo creates a number masking session and assigns to it a virtual phone number from your Plivo account.
4. You display the virtual phone number to both participants. If either party calls the virtual phone number, they’re automatically connected to the other party. The caller ID of the call is set to the virtual phone number, masking the real phone numbers of both parties from each other.

Prerequisites

To get started, you need a Plivo account — sign up with your work email address if you don’t have one already. You must have a voice-enabled Plivo phone number to create number masking sessions; you can rent numbers from the Numbers page of the Plivo console, or by using the Numbers API.

Create a session

Here’s a sample cURL request to create a number masking session.

1
2
3
4
5
6
curl -X POST "https://api.plivo.com/v1/Account/{Plivo Auth ID}/Masking/Session" \
-H "Content-Type: application/json" \
-d '{
  "first_party": "<firstparty>",
  "second_party": "<secondparty>",
  }'

Replace the first and second party phone number placeholders with valid phone numbers in E.164 format.

Plivo will respond back with a virtual number from your account that your application can use for hosting the masked session. Whenever one of the parties calls the virtual number, Plivo will automatically connect the call to the other party. Here’s a sample of what such a response looks like.

{
"session_uuid": "abcd-1234-ab12-cd34",
"virtual_number": "+12205550020",
"status": "active",
"first_party": "+14155552345",
"second_party": "+12165554567",
"record": "false",
"recording_callback_url":"null",
"record_file_format": null, 
"session_expiry": "3600",
"call_time_limit": "3600",
"initiate_call_to_first_party": "false",
"callback_url": "null",
"ring_timeout": "120",
"first_party_play_url": "null",
"second_party_play_url": "null", 
"created_time": "2023-08-17 21:26:44",
"modified_time": "null",
"expiry_time": "null",
"last_interaction_time": "null",
"total_call_count": "0",
"total_call_amount": "0",
"total_call_billed_duration": "0",
"interaction": "{}"
}

Calling scenarios

Organizations can use number masking in two calling scenarios: click-to-call and request-a-call.

Click-to-call

Suppose you have a web or mobile app. When someone taps or clicks on a call button in the app, you can display a screen that shows them the virtual phone number. When the user taps or clicks on the virtual phone number, the app calls the virtual number to connect to the other party.

Test

To test the click-to call scenario, use the first party phone and dial the virtual number. The second party phone should start ringing, and the caller ID on that phone should show up as the virtual number. You can also try calling the first party from the second party phone. If any other phone number calls the virtual number, the call should not be connected.

Request-a-call

Some use cases need a call to be made to the caller and connected with the other party. This is also known as call-me functionality. A typical use case would involve clicking on a Call Me button on a web page or in a mobile app. Plivo’s Number Masking API provides the parameter initiate_call_to_first_party for this use case.

1
2
3
4
5
6
7
curl -X POST "https://api.plivo.com/v1/Account/{AuthID}/Masking/Session" \
-H "Content-Type: application/json" \
-d '{
  "first_party": "+14155552345",
  "second_party": "+12165554567",
  "initiate_call_to_first_party":true
  }'

Test

• To test the request-a-call scenario, click on the Call Me button for the app and provide a phone number. Plivo should make a call to that first party phone. The caller ID should display the virtual number.
• When the first party answers the call, the second party phone should start ringing. It should also display the virtual number as the caller ID.
• When the second party answers, the two parties can talk to each other.