Number masking

Number masking is a service designed to protect the privacy of individuals or businesses when communicating over phone calls. It works by assigning a temporary or virtual phone number to the user, which acts as a proxy or intermediary between the caller and the recipient. When calls are made using this number, the recipient sees only the masked number on their caller ID, rather than the user's actual phone number. This masking helps to maintain the privacy of the user's personal or business phone number, preventing it from being exposed to unknown or potentially untrusted parties. It's commonly used in scenarios such as ride sharing, online transactions, classified ads, customer service calls, or any situation where individuals or businesses want to communicate without revealing their personal contact information.

The Number Masking service enables two parties to engage in a conversation over the phone without exposing real phone numbers to one another. This service is ideal for businesses that want to avoid sharing end user information with third parties. It joins two calls using a Voice number instead of the end-user's real phone number.

The key features of Infobip's number masking product include customizable caller IDs, call recording, customizable announcements, and analytics to track communication activity.

For more information, see How Number Masking Provides Privacy and Anonymity (opens in a new tab).

High-level number masking flow

Number masking is a service on the Infobip platform that can be enabled for inbound calls.

When the Infobip platform receives an inbound call, it sends a callback request to your platform, which will respond with the action to be taken on that call:

• Playing an audio file: your number masking application logic may determine that this inbound call should not be connected to another participant and instead play an audio file to the caller after which the call will be hung up
• Dial an external number and bridge the calls once answered. This action may be combined with recording settings so the whole number masking session will be recorded.

When the number masking call is finalized, Infobip sends a status message to your platform with the session details. For example, whether the call was answered, the duration of the call, the phone number involved in that conversation, and so on.

Set up number masking

You can set up number masking using the web interface or API.

To start using number masking, you need the following:

• Acquire at least one Infobip Voice number
• Create a number masking configuration
• Assign the number masking configuration to your Infobip voice number
• Developed number masking mapping logic on your side

The following sections describe the how-to steps.

Number of DIDs needed

The number of phone numbers needed to support a number masking service depends on several factors, including the volume of calls, the geographic distribution of callers and recipients, and the specific requirements of the business implementing the service. Here's a step-by-step approach to defining the number of phone numbers required:

• Estimate Call Volume: Determine the expected volume of calls that will be masked using the service. This could be based on historical call data, projected business growth, or anticipated call traffic.
• Calculate Concurrent Calls: Determine the maximum number of simultaneous calls expected during peak times. This helps ensure that there are enough phone numbers to handle concurrent calls without experiencing call congestion or dropped calls.
• Consider Geographic Distribution: If your business serves customers or clients across multiple geographic regions, consider the distribution of callers and recipients. Depending on call patterns, it may be necessary to allocate phone numbers from different country or local area codes to ensure that callers perceive the numbers as familiar and trustworthy.
• Plan for Scalability: Account for future growth and scalability needs when determining the number of phone numbers to acquire. It's generally advisable to have some buffer capacity to accommodate unexpected spikes in call volume or business expansion.
• Review Regulatory Requirements: Depending on the jurisdiction and industry, there may be regulatory requirements or restrictions on the use of phone numbers for masking purposes. Ensure compliance with relevant regulations when acquiring phone numbers.
• Evaluate Budget and Cost: Consider the cost implications of acquiring and maintaining phone numbers for the number masking service. Balancing the desired level of service with budget constraints is important in determining the optimal number of phone numbers to procure.

All in all, a rough estimate of the number of DIDs needed to support your number masking implementation is the ratio between the expected concurrent calls and the concurrent calling capacity of a DID number. If you need to understand the concurrent calling capacity of DID numbers per country you need to operate in, please reach out to Infobip support.

Set up number masking using API

This section describes how to configure number masking using the API.

The following prerequisites for the setup:

• Infobip account. Log in If you don’t have an account, sign up (opens in a new tab).
• API key
• Base URL

See (opens in a new tab) for more information

If you need help creating your Infobip account, see Create Account (opens in a new tab).

This is a summary of how to set up number masking using the API.

1. Retrieve your Infobip DID number key
   Use the API to retrieve the list of your purchased numbers. From the list, identify the number you want to use for number masking and save its numberKey.

2. Create the number masking configuration
   Use the Create number masking configuration method to declare the webhooks exposed by your application and that we will use to communicate with it on new incoming calls and when the calls are terminated. The response to this creation request will include a number masking configuration key. Save this key for the next step.

3. Assign the number masking configuration to your Infobip voice number
   With your numberKey and number masking configuration key at your disposal, use the Create voice setup on number method and use the action type VOICE_NUMBER_MASKING.

   You are ready to use the Infobip number masking service.

Set Up number masking using the web interface

This section describes how to set up number masking using the web interface.

The following prerequisites for the setup:

• Infobip account. Log in (opens in a new tab) If you don’t have an account, sign up (opens in a new tab). If you need help creating your Infobip account, visit Create Account.
• Acquire at least one Infobip Voice number
• Create a number masking configuration
• Assign the number masking configuration to your Infobip voice number
• Developed number masking mapping logic on your side

Follow these steps to set up number masking using the web interface.

1. Go to the Number Masking tab (opens in a new tab) under the Voice & WebRTC channel application. Click CREATE CONFIGURATION. Fill at minimum all the NAME (to name your configuration), and CALLBACK URL fields and click SAVE. Note that if you don't specify a STATUS URL, your application won't receive an event once the call is finished including a summary of that session.
2. To connect this setup to your number, follow the Numbers configuration steps in order to assign the Trigger Number Masking default inbound configuration to your number.

Now you are ready to use the number masking service.

Number masking mapping logic

Infobip's Number Masking API and webhook communications allow your application to determine how an inbound call should be handled. As you have read by now in this documentation, this means your application tells Infobip whether:

• to make an outbound call to an external fixed or mobile number with a specific caller ID and connect the inbound and outbound calls together
• to play an audio message to the calling party (such as: "you are not allowed to connect to this party at this time").

Why your application will tell the Infobip platform to perform one or the other action is defined by the number masking mapping logic you will implement in your backend application. While not being a strict guidance, here are a few hints and tips to help you get started thinking about what to consider in such implementation.

Number pools

Decide how many voice numbers you will require on the Infobip platform to serve your market. There is no simple formula to use, but bear in mind that the very same voice number could be used to handle multiple parallel calls that connect to different destination numbers. As an example, if 1(809)7712916 is the voice number associated to your number masking application, Bob might be calling it and be connected to Lisa while at the same time, John calls it and gets connected to Paul. Implementing proper session management will let your application deal with these associations.

Whatever the number of virtual phone numbers you decide to get started with, each and every one of them will have to be linked to the same number masking application, as you have learned how to do it in the previous sections. It might be a good idea to build your own number pool reference, basically a table keeping track of all numbers you have associated to your number masking application.

Do also consider the following elements when reserving voice numbers on the Infobip platform to be used for number masking:

• Geo coverage: do you have voice numbers that are covering all local markets you are serving? A UK customer will most likely not want to call a US number to communicate with his driver or delivery person
• Voice only or SMS as well: Infobip rents various type of (virtual) phone numbers. Some are limited to specific channels only (only SMS, or only voice) while others do support both voice and SMS. Although the Number Masking APIs and webhook actions support only voice, having numbers that also support SMS might be beneficial in some cases.

Session management

Let us suppose you are a ride sharing company willing to implement number masking so drivers and customers can communicate in full respect of their privacy. Typically, a session would be started on your side as soon as the end customer reserves a ride with one of your driver. Once that session is created you will associate one of your virtual phone numbers to each of the session's participants, ie one for the driver and one for the end customer. It's up to you to decide whether you want to include other parameters to that session or do some updates on your number pool table, such as:

• a "time to live" definition for the session : how long are each of these participants allowed to contact each other over these virtual numbers, if it makes sense for your use case
• a "number reservation" flag, which means flagging the number assigned to a participant in your number pool table if you want that number to be reserved for that session (meaning you won't assign it to other concurrent sessions). Again, if this makes sense for your use case.

Once numbers are associated to the active participants' session, you will most likely send an update to both driver's and end customer's application to reflect the number they can call to get in touch with the other session participant.

Now, let's suppose someone is calling one of the virtual phone numbers associated to your number masking application. Upon reception of this inbound call, your application will receive a message on its callBackUrl. Your application will extract both from and to numbers from the message and run through your list of currently active sessions.

• If it finds a match to an active session, your application will reply to the callBackUrl request with a Dial payload, so Infobip will call the real number of the other session participant and use the other participant's virtual phone number as caller ID. As you will search for active sessions considering both from (caller's number) and to (virtual phone number on Infobip), there is no risk that you route the call to an inadequate participant.
• If it finds a match to a session marked as closed (the end user has been driven to its destination and the ride is over), you would most likely not allow that person to get back in touch with the other participant from this terminated session, whether to respect and enforce privacy or to avoid off-platform transactions, but you could reply to the callBackUrl request with a Dial payload in order for this person to be connected to your call center - who knows, maybe the end user forgot something important or valuable in the rider's car.
• If it doesn't find a match, your application will reply to the callBackUrl request with a Play payload, so Infobip will play an audio message to the calling party such as "We are sorry, but you are not allowed to place this call at this moment".

When the ride sharing session is completed, your application would flag it as such but could keep the associated virtual phone number information, as it might prove useful if you are required at some point to understand how end user and riders have been able to contact each other. If your session came with a notion of number reservation, your application would remove that reservation flag from the virtual phone number if your number pool table.

Advanced features

Recording your number masking sessions

You may decide to record your number masking sessions. This can be enabled on a per session basis, and is defined in the callback response. If you decide to enable the recording of a session, you will need to define 2 elements in your callback response:

• the recording object in the response must be set to true
• the announcements to be played to both caller and callee

You may use the announcement feature without recording your sessions, but if enabling recording you have to define the announcements as announcements are required to make both caller and callee aware that the call will be recorded.

The flow will work as follow:

• The caller will be played the caller announcement file. If the caller does not wish to be recorded, he will hang up the call
• If the caller remains on the call, we will try to connect to the callee. During this connection time, we play a ringing tone to the caller
• When the callee answers the phone, we start the recording and play the callee announcement
• If the callee accepts to be recorded and thereby remains on the phone after the announcement playback is finished, we connect the caller and callee together. The recording continues until one the parties hangs up the call.

As the session concludes, Infobip will send a summary of that session in a message sent to your STATUS webhook. If recording was requested, the status message will include two new fields:

• recordingFileId, which reflected the ID of the recorded file
• recordingStatus, which take the value HOSTED (recording is on our cloud storage), SFTP (recording has been pushed to your SFTP server), or FAILED (the recording process failed).

Number masking recordings can be found on our portal under Channels and Numbers > Voice > Recordings > Dialogs. If you wish to list and download recordings via API, use the Download recording file method with the fileId you have received in the status message. In case you lost this fileId, you may use the Get dialog recordings method to list all your dialog recordings. The application name for these dialog recordings is NUMBER_MASKING.

Using your own session references in number masking sessions

Upon reception of an inbound call to a voice number configured for number masking, the callback message we send to your application includes a nmCorrelationId. This number masking session ID is generated by us and will be included in the status message your application receives at the end of a session, in order to let you relate these events together. Your number masking application logic may generate its own unique IDs for each session it manages and you may prefer our events to carry this reference instead. In this case, you only need to add the parameter clientReferenceId in the callback response. Setting this parameter will have the following effects:

• the status message sent to your application once a session is completed will also include this clientReferenceId
• if you are recording your number masking sessions and if you have configured SFTP to receive your recordings, the resulting recording file pushed to your SFTP server will be named by this clientReferenceId. Please ensure this Id to be unique otherwise the files pushed to your SFTP server might be overwritten.

Secure your API communications

This section covers the necessary steps you need to take to secure your API communications, both from Infobip to your application, and from your application to Infobip. Jump to one of the accompanied sections below to start the process of securing your API communications.

From Infobip to your application

By default, Infobip will post data to your application's CallbackURL and StatusURL without any specific security scheme other than using HTTPS communications, provided your exposed URLs support HTTPS. If you wish to enhance the security of these communications, you can request Infobip to include an Authorization header to every post made toward your CallbackURL and StatusURL.

Here are the steps you need to do to be able to use an Authorization header.

Step 1 Use method to create a new number masking credential

Use the POST/voice/masking/2/credentials method to create a new number masking credential

The method will reply with a 200 OK to confirm both apiID and key values in the response's payload.
A credential composes of two key parts the user generates (apiID and key), both being alphanumerical strings (80 characters max).
Once your credentials are confirmed, any data posted to your application's CallbackURL and StatusURL will have an Authorization header whose value is computed based on your keys.
Note that number masking credentials are not application-specific. If you have multiple number masking configurations, the same apiID and key are used to build the Authorization header's content.

Step 2 Understand the Authorization header's content

Authorization headers generated by Infobip and added to POST requests to your application's CallbackURL and StatusURL are built on the following logic:

 apiId:hashed(webhookUrl+requestBody+key)

Where:

• webhookURL is the URL of your Callback or Status webhook
• requestBody is the body of the message posted to your Callback or Status webhook
• apiKey is the first part of your number masking credentials
• key is the second part of your number masking credentials The hashing algorithm is SHA256.

This example uses the CallbackURL https://my.company.server/nmcallback and Infobip sends the following message towards that URL:

{
  "from": "40257076838",
  "to": "40257879513",
  "nmCorrelationId": "7cb72e4b-cf9f-40b6-9fc4-79588d18a666",
  "correlationId": "0f754338-1aff-4e09-a933-7d205ca7aed4"
}

This example uses the following number masking credentials:

{
"apiId": "55ddccad2df62a4b615b7e3c472b2ab6",
"key": "5da086b6a8e4424993646b8699c333ca"
}

Infobip then adds the Authorization header that is shown as:

55ddccad2df62a4b615b7e3c472b2ab6:hashed(https://my.company.server/nmcallback{"from":"40257076838","to":"40257879513","nmCorrelationId":"7cb72e4b-cf9f-40b6-9fc4-79588d18a666","correlationId":"0f754338-1aff-4e09-a933-7d205ca7aed4"}5da086b6a8e4424993646b8699c333ca)

The value of the header is:

Authorization 55ddccad2df62a4b615b7e3c472b2ab6:66c5985cf14f92e29c5647d4d9c4f12107a17507fe4ecfb3f5d4d2065e3dfab3

Step 3 Status callback particularities

When computing the Authorization header for messages sent to your Status URL, Infobip will purposely omit 3 key value pairs from the message body. The affected keys are:

• calculatedDuration
• currency
• pricePerSecond

If the body of the message received from the statusURL is:

{
  "action": "dial",
  "from": "41793026727",
  "to": "41793026731",
  "transferTo": "41793026785",
  "duration": "15",
  "status": "answered",
  "fileId": null,
  "fileUrl": null,
  "nmCorrelationId": "6ag710o6ihb23q06epc23n46ihd0nilcibb0nq9ccbq6mmsdgbp4nghefjs67vgo7200",
  "inboundDuration": 15,
  "calculatedDuration": 15,
  "pricePerSecond": 0.0,
  "currency": "EUR",
  "ringingTime": "2018-01-01 12:00:00",
  "answeredTime": "2018-01-01 12:00:10",
  "correlationId": "0f754338-1aff-4e09-a933-7d205ca7aed4",
  "inboundDuration": "30"
}

What this means is that the Authorization header takes only the following elements into account:

{
  "action": "dial",
  "from": "41793026727",
  "to": "41793026731",
  "transferTo": "41793026785",
  "duration": "15",
  "status": "answered",
  "fileId": null,
  "fileUrl": null,
  "nmCorrelationId": "6ag710o6ihb23q06epc23n46ihd0nilcibb0nq9ccbq6mmsdgbp4nghefjs67vgo7200",
  "inboundDuration":15,
  "ringingTime": "2018-01-01 12:00:00",
  "answeredTime": "2018-01-01 12:00:10",
  "correlationId": "0f754338-1aff-4e09-a933-7d205ca7aed4",
  "inboundDuration": "30"
}

Step 4 Validating incoming messages to your application's Callback and Status URLs

When you receive a message from Infobip to your Callback or StatusURLs, you need to apply the same logic as explained from Steps 2 and 3 to compute what should be the expected Authorization value and compare it to the one you will receive in the message. If the values match, you can be sure that this message was sent by Infobip and is safe.

From your application to Infobip

Although not a specific feature in number masking, if you wish to add an extra layer of security to HTTP requests your application sends to Infobip, you can generate a specific API Key that will be limited to predefined IP addresses. The IP address(es) are the fixed address(es) behind your application. On the API Key Management page of the Infobip web interface, you can easily create an API key and assign your IPs: