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

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. Maintain 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, Contact Infobip support.

Set up number masking using API

The following prerequisites for the setup:

• Infobip account. Log in If you don't have an account, sign up.
• API key
• Base URL

See How to get started with the Infobip API for more information.

If you need help creating your Infobip account, see Create Account.

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 Infobip uses 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

The following prerequisites for the setup:

• Infobip account. Log in If you don't have an account, sign up. 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 under the Voice & WebRTC channel application. Select CREATE CONFIGURATION. Fill at minimum all the NAME (to name your configuration), and CALLBACK URL fields and select 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 [#number-masking-mapping-logic-set-up-number-masking]

The Infobip 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. You can 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 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.