Overview

The Plivo Number Masking API facilitates masked communication between two parties in a voice call by sending calls through an intermediate phone number that acts as a proxy for each. Consider a consumer communicating with a ride-hailing service driver through an app: The customer (call them the first party) taps a button to call a proxy phone number, and the proxy instantly and automatically connects to the worker’s number (the second party). Neither party can see the other caller’s real phone number.

Session

For every first party / second party phone number combination you send, Plivo creates a unique session. The parties can make multiple (non-concurrent) masked phone calls within a session; for example, a ride-hailing driver might phone a rider multiple times.

Within Plivo, a session is represented by a Session object, which comprises attributes such as a unique session identifier, the phone numbers of the two parties, and a virtual number Plivo provides to connect them. Additional attributes determine the call recording status, settings for session expiry, and call time limits. There are options to initiate a call to the first party and play audio files to participants before connecting them. You can also track the charges incurred for hosting the session.

Interaction

Every conversation between the two parties in a session is represented by a unique Interaction object, which is a nested object within the session. A session can contain multiple interactions, each having a maximum of two communication legs, regardless of the call direction. The Interaction object includes the URL of the call-leg resource created for the first party and the second party.

An Interaction object’s attributes hold information and resources related to a particular interaction.

Call Flow

Conversations can be initiated in a couple of ways; in both, an application provides Plivo with both parties’ numbers, but what happens next depends on the context.

Click-to-call: In a click-to-call scenario, one of the two parties makes an inbound call by clicking on a button on a website or in a mobile app. Plivo then makes an outbound call from the virtual number to the second party via the virtual number assigned to the session.

Request-a-call: In a request-a-call scenario, someone clicks on a Call Me button on a web page or in a mobile app and provides their phone number. Plivo makes an outbound call to that person. When the first party answers, Plivo makes a second call to the second party and bridges the call. This is also an outbound call. Relevant call charges apply. Request-a-call can be useful in scenarios:

• When customers are roaming outside of their usual calling area and can’t call out.
• When businesses don’t want to promote outbound calling because of high call charges.