Number Masking

Connect two parties over a voice call without exposing their real phone numbers.

The Number Masking service enables two parties to engage in a conversation over the phone without exposing their phone numbers to each other. This service is ideal for businesses that share customer information with third parties. Have in mind that the Number masking mapping has to be implemented on your side in order to define to which phone number the incoming call should be forwarded to. Number masking mapping depends on your business logic. 
 

PREREQUISITES

In order to use the Number Masking service the first step is to purchase a voice capable number (DID number) which will serve as the connection bridge between two parties. Number masking configuration needs to be prepared and then you have to link this setup configuration with a number. Now, you are ready to advertise Number masking to your customers.

Use our Numbers API or Customer portal to purchase a Voice enabled phone number.

Number masking configuration:

Audio file upload

In some situations, you may want to play an audio message to the caller instead of forwarding the call to a number from your mapping logic. The audio file should be prerecorded and uploaded to our platform in advance. Audio fileId will be returned in the response to the upload request and this fileId might be used in a response to the callback URL request (described in the following steps).

POST https://api.infobip.com/numbers/1/files HTTP/1.1	
  

Request Parameters

Property name Type Description
url string URL of your voice file location. Max size of the file is 4MB. The acceptable file format is mp3.
content string The byte array of the voice file can be included instead of the file location URL.

 

Response Parameters

Property name Type Description
field string Id of the uploaded audio file.

 

Request examples

Using URL to audio file.

POST /numbers/1/files HTTP/1.1
Host: api.infobip.com
Content-Type: application/json
Accept: application/json
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

{
	"url": "http://www.winhistory.de/more/winstart/mp3/winxp.mp3"
}	
  

 Using a byte array of the audio file.

POST /numbers/1/files HTTP/1.1
Host: api.infobip.com
Content-Type: application/json
Accept: application/json
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

{
   "content": "SUQzBAAAAAAAF1RTU0U................oBlRZUxIALUaldwrWAAIoVfL"
}	
  

CallBack URL Request

Upon receiving a call to the Number masking number, Infobip’s platform will generate a request to your callbackUrl configured on the Number masking configuration. This request contains the caller number and the Voice number being called. We are also providing correlationID to be used as an identifier for this call request. In a return, Infobip’s platform expects to receive the phone number to forward the call to and caller id which should be presented. Caller ID presentation depends on the capabilities of the voice connection on the particular market. Instead of the number, we could also receive a command audio in order to play an audio file that was previously uploaded to our platform (Audio file upload)

Request Parameters

Property name Type Description
from string Caller number
to string Called number
correlationId string Unique identifier of the call record, available for both Callback and Status requests.

Response Parameters

Property name Type Description
command string Command description. Values should be dial or audio.
phoneNumber string Destination phone number to call.
callerId string Caller id that should be displayed to called party.
fileId string Identification of the audio file to be played to the caller

Request example

{
	"from": "41793026727",
	"to": "41793026731",
    "correlationId": "0f754338-1aff-4e09-a933-7d205ca7aed4"
}	
  

Response examples

{
	"from": "41793026727",
	"to": "41793026731",
    "correlationId": "0f754338-1aff-4e09-a933-7d205ca7aed4"
}	
  

Depending on the use case, the response may contain the audio file id which will be played back to the caller. In that case, the response should look like this:

{
    "command": "audio",
    "fileId": "382a92df-1f6d-4d30-8274-cf508a0c7d62"
}	
  

Status URL Request

When a call is finished, Infobip’s platform will send a status report to your statusUrl that was provided during the Number masking configuration.

Request parameters

Request Parameters

Property name Type Description
action string Requested action (dial or audio).
from string Caller number.
to string Voice number.
transferTo string Called party (transfer) number.
duration int Duration of the call.
status string Status of the call. Could be answered, busy, no answer, failed or congestion.
fileID string The file that was played to the caller.
ringingTime string Date and time when ringing has started.
answeredTime string Date and time when the call was answered.
correlationId string Unique identifier of the call record, available for both Callback and Status requests.

Request example

{
  "action": "dial",
  "from": "41793026727",
  "to": "41793026731",
  "transferTo": "41793026785",
  "duration": "235",
  "status": "answered",
  "ringingTime": "2018-01-01 12:00:00", 
  "answeredTime": "2018-01-01 12:00:10",
  "correlationId": "0f754338-1aff-4e09-a933-7d205ca7aed4"
}	
  

A successful response is represented by an HTTP status code 200 OK from the Client’s platform.


Masking configuration

Masking configuration is used to create a number masking configuration.

Request Parameters

Property name Type Required Description
name string Yes Unique configuration name.
Alphanumeric, max length 100.
callbackUrl string Yes Client's URL that will be called on each inbound call to related Number masking Voice number in order to get instructions of how to handle incoming calls. Instructions are a result of mapping logic implemented on your side according to your business case.
statusUrl string No Client's URL for status report delivery after the call is finished.
backupCallbackUrl string No If callbackUrl is unavailable this one will be called instead.
backupStatusUrl string No If statusUrl is unavailable this one will be called instead.
description string No  

 

Response parameters

Same as request parameters and additionally:

 

Property name Type Description
key  

Use to connect masking configuration with Voice-enabled number. 

View Number API docs for more information.

 

Create masking configuration

POST /voice/masking/2/config HTTP/1.1	
  

Request example

POST /voice/masking/2/config HTTP/1.1
Host: api.infobip.com
Content-Type: application/json
Accept: application/json
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

{
 "name" : "UniqueConfigurationName",
 "callbackUrl" : "http://xyz.com/1/callback",
 "statusUrl" : "http://xyz.com/1/status"
}	
  

Response examples:


200 OK

{
    "key": "3FC0C9CB4AFAEAC67E8FC6BA3B1E044A",
    "name": "UniqueConfigurationName",
    "callbackUrl": "http://xyz.com/1/callback",
    "statusUrl": "http://xyz.com/1/status",
    "backupCallbackUrl": null,
    "backupStatusUrl": null,
    "description": null,
    "insertDateTime": "2019-08-16T09:11:36.573",
    "updateDateTime": "2019-08-16T09:11:36.573"
}	
  

400 Bad Request

{
    "requestError": {
        "serviceException": {
            "messageId": "1566539912166020135",
            "text": "callbackUrl is not valid http URL"
        }
    }
}	
  

400 Bad Request

{
    "requestError": {
        "serviceException": {
            "messageId": "1566539976409021135",
            "text": "Configuration name is required."
        }
    }
}	
  

Update masking configuration

PUT /voice/masking/2/config/{key} HTTP/1.1	
  

Request example

PUT /voice/masking/2/config/3FC0C9CB4AFAEAC67E8FC6BA3B1E044A HTTP/1.1
Host: api.infobip.com
Content-Type: application/json
Accept: application/json
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

{
 "name" : "UniqueConfigurationName",
 "callbackUrl" : "http://xyz.com/1/callback/updated",
 "statusUrl" : "http://xyz.com/1/status/updated"
}	
  

Response examples:


200 Ok

{
    "key": "3FC0C9CB4AFAEAC67E8FC6BA3B1E044A",
    "name": "UniqueConfigurationName",
    "callbackUrl": "http://xyz.com/1/callback/updated",
    "statusUrl": "http://xyz.com/1/status/updated",
    "backupCallbackUrl": null,
    "backupStatusUrl": null,
    "description": null,
    "insertDateTime": "2019-08-16T09:11:36.573",
    "updateDateTime": "2019-08-16T09:12:32.77"
}	
  

400 Bad Request

{
    "requestError": {
        "serviceException": {
            "messageId": "1566540067281023135",
            "text": "Configuration with given name already exist, please provide different name."
        }
    }
}	
  

Delete masking configuration

Configuration deletion is only possible if no connection with the DID number exists.

DELETE /voice/masking/2/config/{key} HTTP/1.1	
  

Request example

DELETE /voice/masking/2/config/90F1F45E73CA0BF9081EEF1672E720A1 HTTP/1.1
Host: api.infobip.com
Accept: application/json
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==	
  

Response examples:


200 Ok 

{}	
  

400 Bad Request

{
    "requestError": {
        "serviceException": {
            "messageId": "1566539599856012135",
            "text": "Configuration with given id dose't exist."
        }
    }
}	
  

400 Bad Request

{
    "requestError": {
        "serviceException": {
            "messageId": "1566539599856012135",
            "text": "Unable to delete configuration. Check if configuration has existing DID numbers connected. Please delete those connections first."
        }
    }
}	
  

Get masking configuration

GET /voice/masking/2/config/{key} HTTP/1.1	
  

Request example

GET /voice/masking/2/config/90F1F45E73CA0BF9081EEF1672E720A1 HTTP/1.1
Host: api.infobip.com
Accept: application/json
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==	
  

Response examples:

200 Ok

{
    "key": "90F1F45E73CA0BF9081EEF1672E720A1",
    "name": "UniqueConfigurationName",
    "callbackUrl": "http://xyz.com/1/callback/updated",
    "statusUrl": "http://xyz.com/1/status/updated",
    "backupCallbackUrl": null,
    "backupStatusUrl": null,
    "description": null,
    "insertDateTime": "2019-04-24T09:33:40.353",
    "updateDateTime": "2019-04-24T09:33:40.353"
}	
  

404 Not Found

{
    "requestError": {
        "serviceException": {
            "messageId": "1565944751369996022",
            "text": "Configuration not found."
        }
    }
}	
  

Get all masking configuration

GET /voice/masking/2/config HTTP/1.1	
  

Request example

GET /voice/masking/2/config HTTP/1.1
Host: api.infobip.com
Accept: application/json
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==	
  

Response example:

200 Ok

[
    {
    "key": "90F1F45E73CA0BF9081EEF1672E720A1",
    "name": "UniqueConfigurationName",
    "callbackUrl": "http://client.com/1/callback",
    "statusUrl": "http://client.com/1/status",
    "backupCallbackUrl": null,
    "backupStatusUrl": null,
    "description": null,
    "insertDateTime": "2019-04-24T09:33:40.353",
    "updateDateTime": "2019-04-24T09:33:40.353"
    },
    {
    "key": "70F1F45E73CA0BF90816EF1672E720A5",
    "name": "UniqueConfigurationName2",
    "callbackUrl": "http://xyz.com/1/callback",
    "statusUrl": "http://xyz.com/1/status",
    "backupCallbackUrl": "http://xyz.com/1/backup_callback",
    "backupStatusUrl": "http://xyz.com/1/backup_status",
    "description": null,
    "insertDateTime": "2019-05-01T09:33:40.353",
    "updateDateTime": "2019-05-01T09:33:40.353"
    }
]