Number masking
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.
Number Masking can be used over API or web interface.
Also, Number Masking calls can be recorded. Learn more about Recording. To enable this add-on, contact your dedicated Account Manager.
COUNTRY REGULATIONS AND COMPLIANCE
Certain types of Voice and Video calls and call recordings might be subjected to specific country regulations. Before you set up and start using Voice and Video, make sure you have checked the country's telecom regulations.
Technical specifications
Number masking is a service on the Infobip platform that can be enabled for inbound calls. Check out the high-level overview and see how it works:
Once the Infobip platform receives an inbound call, it sends an HTTP request to your platform to which your application 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 hang 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 is recorded
When the Number Masking call is finalized, Infobip sends the statusURL with the call details. For example, whether the call was answered, the duration of the call, the phone number involved in that conversation, etc.
See the Number masking status API for more details about the statusURL request.
You can consider the Infobip platform as a bridge. Number Masking connects two parties while safeguarding their private information. In other words, it allows two-way communication between the likes of buyers and sellers, customers, and delivery service staff, without exposing personal phone numbers.
For more information, see How Number masking provides privacy and anonymity
Setup
You can set up Number Masking using either the API or the web interface.
To start using Number masking service, you need the following:
- 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 section describe the how-to steps.
Using API
Learn how to configure Number Masking via API.
Prerequisites
See How to get started with the Infobip API for more information.
If you need help creating your Infobip account, go to Create Account.
Here's how to set up Number masking using API.
-
Lease a Voice number using API.
To receive voice calls, you need a phone number with voice capabilities. To receive voice calls, you need a phone number with voice capabilities. To get the list of available Infobip numbers and their numberKeys, use the Get available numbers method.
If you already have a number leased, skip to step two.
The response will contain the list of first 50 phone numbers by default. However, you can get the rest by setting page or limit query parameters in the API request. Choose a phone number you want and keep its numberKey as a reference. Use the Purchase a number method using that numberKey to acquire this number. Make a note of the numberKey reference as you will use it later.
- 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.
-
Assign the number masking configuration to your Infobip voice number
With your numberKeys 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.
You are ready to use the Infobip Number masking service.
IMPORTANT
To match the caller with the phone number you want to forward the call to, you must develop the logic on your end. See Number Masking mapping logic.
Using web interface
Here's how to set up Number Masking using the web interface.
Prerequisites
- Infobip account. Log in If you don’t have an account, sign up. If you need help creating your Infobip account, go to Create Account.
- 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 via the web interface.
- Lease a Voice number. To receive voice calls, you need a phone number with voice capabilities. If you have already leased a number you can skip this step. Log in to the web interface, go to Channels and Numbers > Channels > Voice and WebRTC > BUY NUMBER. All numbers from that list have Voice capability and can be used for number masking. To refine the list, filter by country.
- Select your desired number and click BUY. Now you can proceed to configure your Voice number. See Voice Numbers for more details.
- Create a Voice setup on your leased Voice number. Go to Channels and Numbers > Channels > Voice and WebRTC > Number Masking. Click ADD NEW. Fill in the mandatory fields, NAME (to name your configuration), and CALLBACK URL. Click SAVE.
- To connect this setup to your number, go to Channels and Numbers > Channels > Voice and WebRTC > Numbers. Find the number you want to assign number masking. You'll see a Configuration dialog appear.
- Under TYPE, select Trigger Number masking. Under Number masking, select the Voice setup you have created. Click SAVE.
Now you are ready to use the Number Masking service.
IMPORTANT
To match the caller with the phone number you want to forward the call to, you must develop the logic on your end. See Number Masking mapping logic.
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 may have already concluded while reading this documentation, what the above means is that your application tells the Infobip platform 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 (for example, "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 guide, this section provides hints and tips to help you get started with what to consider in such an 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, however, the same voice number could be used to handle multiple parallel calls that connect to different destination numbers. As an example, if 1(809)7712916 if 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.
Also, consider the following elements when leasing voice numbers for Number Masking:
- Geo coverage: Do you have voice numbers covering all local markets you are serving?
A UK customer will most likely not want to call a US number to communicate with their driver or delivery person. - Voice only or SMS as well: Infobip rents various types of (virtual) phone numbers.
Some are limited to specific channels (only SMS, or only Voice) while others support both voice and SMS. While the Number Masking APIs and webhook actions do support voice only, having numbers that also support SMS might be beneficial in some cases.
Manage sessions
Let's 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 drivers. 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 say someone is calling one of the virtual phone numbers associated with 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 users 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 of 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 totrue
- 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 works as follows:
- 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, the recording starts, and the callee announcement plays
- 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 of 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 a recording was requested, the status message will include two new fields:
recordingFileId
, which reflected the ID of the recorded filerecordingStatus
, which takes 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 under Channels and Numbers > Channels > Voice and WebRTC > Recordings > Dialogs. If you wish to list and download recordings over 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.
Recordings and SFTP
To receive all your voice recordings on your SFTP server, go to the Settings section under the Recording tab of the Voice channel application.
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
.
Ensure that this Id is 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:
- 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 keyare
used to build the Authorization header's content. - 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.
Example:
This example uses the following CallbackURL is 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"
}
We will use the following Number masking credentials as an example:
{
"apiId": "55ddccad2df62a4b615b7e3c472b2ab6",
"key": "5da086b6a8e4424993646b8699c333ca"
}
Then, Infobip 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)
As such, the value of the header is:
Authorization 55ddccad2df62a4b615b7e3c472b2ab6:66c5985cf14f92e29c5647d4d9c4f12107a17507fe4ecfb3f5d4d2065e3dfab3
- Status callback important information
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 will only take 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"
}
- Validate 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 in 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.
NOTE
When concatenating your webhookURL, body and key and before hashing that concatenated string, make sure to strip off any potential new line characters from the body. New lines would not appear when string concatenation and hashing is performed by your application code, but can happen in debugging phase if you copy/paste the body content manually in text editors.
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:
For even stronger security, you can use the OAUTH2 authentication in your application as we have described this setup in our API Key Authentication documentation.