Build and Test a Call Masking Flow Using 8x8's Number Masking API

The on-demand economy is growing. It began with delivery and ride sharing, and it is now expanding to marketplaces, healthcare, groceries, and much more. A key driver behind this success is the convenience of hiring those services right from one’s mobile phone, as well as the ability for businesses to directly reach customers through phone calls. However, data privacy is a key concern for both customers and businesses.

Call masking has become an important data privacy strategy, providing a security layer that protects the identities of both customers and service providers. Business continues as usual, while direct, anonymized communications happen between the customer and provider without exposing either party’s actual phone number.

In this article, we’ll show you how to create and test a call masking flow using a simplified example of a ride sharing app (let’s call it “Udrive”). Steps include:

1. Setting up the client-side environment
2. Configuring the necessary webhooks
3. Processing the webhooks
4. Testing the call masking setup

How call masking works between a passenger and driver in a ridesharing service.

Prerequisites

Before you get started, you’ll first need access to 8×8’s Call Masking service. Contact your account manager or email us at hello-cpaas@8×8.com for more information.

Next, you will need the following:

1. A new sub-account ID dedicated to 8×8’s Number Masking service
2. A Virtual Number, which is allocated to your sub-account
3. An endpoint where the call handles will be sent; in this article, we will be using Apiary

Apiary is a free tool that lets you design, prototype, and test APIs. It will simulate a client-side environment (in this example, the Udrive platform) to communicate with the 8×8 Number Masking AP—essentially where we will receive and make calls.

Setting up the client-side environment on Apiary

On Apiary, create a new API project and give it a name, e.g. “8×8 Voice Masking.”

Next, under “Inspector,” retrieve the webhook URL where Apiary will be listening.

Then, create and configure a new webhook to communicate with the 8×8 platform via the webhook management API. This will indicate to 8×8 where to post the call handle, call status, and session status.

To successfully create a new webhook, there are two key things to note:

1. Replace {subAccountId} with the one provided, which is dedicated to 8×8’s Number Masking service and retrievable on 8×8 Connect under “API keys”
2. API authentication is required, so insert the authentication token, which is available on 8×8 Connect under “API keys” (see documentation)

Configuring webhooks: call handle, call status, and session status

To create the call masking flow, there are three webhooks that you need to configure.

1. Call Handle

This webhook allows you to set up your handleURL. After this, all incoming calls from the Udrive passenger to the Virtual Number will be forwarded to this URL (see documentation).

Here’s a sample of the call handle webhook configuration via the webhook management API. There are three key steps here:

1. With the webhook URL from Apiary, add “/handle” to indicate that this webhook will be used for a call handleevent
2. Replace “url” with the webhook URL above
3. The field “type” refers to the type of webhook; replace it with “VCA” which indicates the Call Handle webhook

Now, to test that the webhook is configured correctly, imagine that you are a Udrive passenger and try calling the associated virtual number provided. A call handle will be posted to this webhook. Here’s an example.

💡 More about the fields

“sourceMsisdn”: the actual phone number of the passenger.

“targetMsisdn”: the virtual number dialed by the passenger

2. Call Status

This webhook allows you to receive the call status, which provides you details of ongoing calls. Upon receiving status updates, a JSON object will be posted to the statusURL, which is configured together with your sub-account (see documentation).

Here’s a sample of the Call Status webhook configuration via the webhook management API. There are three key steps here:

1. With the webhook URL from Apiary, add “/status” to indicate that this webhook will be used for the call status
2. Replace “url” with the webhook URL above
3. The field “type” refers to the type of webhook; replace it with “VCS” which indicates the Call Status webhook

When a passenger calls the associated virtual number, the call status will be posted to this webhook. You will be able to see real-time status updates of the ongoing call between the passenger and the driver. Here’s an example.

💡 Types of call statuses

You can expect 2 types of call statuses – “CONNECTED” and “NOT_CONNECTED”.

More on call statuses here.

3. Session Status

This webhook allows you to receive the session status, where you can review the call status and individual call legsafter a call has ended. Your aggregated call status will be configured together with your sub-account (see documentation).

Session Status can be used alongside, or to replace, Call Event to simplify your call monitoring process.

Here’s an example of the Session Status webhook configuration via the webhook management API. There are three key steps here:

1. With the webhook URL from Apiary, add “/summary” to indicate that this webhook will be used for the session status
2. Replace “url” with the webhook URL above
3. The field “type” refers to the type of webhook; replace it with “VSS” which indicates the Session Status webhook

At the end of a call between the passenger and driver, a session status will be posted to this webhook, providing an aggregated summary of the entire call.

• “callA”: the call made from the passenger to the 8×8 server
• “callB”: the call made from the 8×8 server to the driver

Here’s an example.

💡 Types of session statuses

In this example, depending on the statuses of “callA” and “callB”, you will observe different session statuses.

Here’s a list of the possible session statuses

Processing the webhooks via Apiary

As mentioned, Apiary simulates our fictional Udrive platform. To process the call handle request, you’ll input the client-side code under “Editor” in Apiary.

When a call handle request is posted to the webhook (i.e. an inbound call is made by the passenger), the client-side code on the Udrive platform will be executed and answered with a call action.

💡 There are multiple commands to a call action that can be used to process an inbound call (see documentation).

Here’s an example of client-side code on the Udrive platform, which will connect an inbound call from a passenger to a driver with a “makeCall” action being sent back.

Here’s a breakdown of the code above.

## Handle Collection [/handle] indicates how the call handle request sent by 8×8 will be executed when a passenger calls the associated virtual number. The call action “makeCall” is triggered, connecting the inbound call to the driver (see more on call actions).

A couple of things to note:

1. “source” is the caller ID, i.e. the phone number displayed to the driver. This should be the virtual number dialed by the passenger (“targetMsisdn” in the call handle received on the webhook).
2. “destination” is the phone number to connect the call to, i.e. the driver’s actual phone number.

## Call Status Collection [/status] indicates how the call status request sent by 8×8 will be processed during the call (see documentation).

## Session Status Collection [/summary] indicates how the session status request sent by 8×8 will be processed once the call is completed (see documentation).

Testing the call masking flow

Now, it’s time to test the entire call masking flow. First, retrieve the list of virtual numbers configured on your sub-account using 8×8’s Number Health service. Here’s an example of the API response you will see.

• “msisdn” are the virtual numbers you can dial, which in this example are “+6212345678” and “+6512345678”
• “status” provides information on the live virtual number status

Now, you are ready to make the call to any of the available and active virtual numbers. But, your test should not end there. Remember to check the logs for the call handle, call status, and session status that 8×8 posted on the webhooks. In Apiary, you can find this under “Inspector.”

Next steps

What’s left now is to simply implement call masking on your platform. The example demonstrated above is only one part of 8×8’s scalable Voice API solution. Create your unique call masking flow by including tailored voice messages using text-to-speech while waiting for a call to answer, or adding on app-to-app calling for a more integrated customer experience.

To learn more, contact us at hello-cpaas@8×8.com.