Get Started with Number Masking using PHP

    Overview

    Phone number masking is the process of establishing a call between two parties without revealing their contact information. Many businesses often require a technique to anonymize communication between two parties involved on the platform, for example, a customer and a delivery agent on a food delivery service platform. This technique involves an intermediate phone number that acts as a proxy between the two parties on the call. In this guide, we will walk you through the implementation of number masking with the help of a Plivo number which will act as the intermediate number to connect both the parties on a call anonymously.

    Outline

    Implementation

    In this example, we will build a number masking application for a food delivery service. Through this implementation, the company can connect the customers with the delivery agents and vice versa without revealing their actual phone numbers.

    Following are the steps involved in the implementation phase:

    1. Create a Customer<->Agent phone number mapping in your application backend
    2. Create the number masking application using the Plivo Voice platform.
    3. Assign the number masking app to a Plivo number.

    Set Up Your PHP Dev Environment

    Operating SystemInstructions
    OS XYou can install PHP using the official installer. You can also install it from here.
    LinuxTo install PHP on Linux you can find the instructions here.
    WindowsTo install PHP on Windows you can use the official installer.

    Install Composer

    Composer is a dependency manager for PHP that is used in all modern PHP frameworks, such as Symfony and Laravel. We highly recommend using Composer as the package manager for your web project.

    1. Download the latest version of Composer.
    2. Run the following command in Terminal in order to run the composer:

       $ php ~/Downloads/composer.phar --version
      

      Note: PHAR (PHP archive) is an archive format for PHP that can be run on the command line

    3. Run the following command to make it executable:

       $ cp ~/Downloads/composer.phar /usr/local/bin/composer
       $ sudo chmod +x /usr/local/bin/composer
       $ Make sure you move the file to bin directory.
      
    4. To check if the path has /usr/local/bin, use

       $ echo $PATH
      

      If the path is different, use the following command to update the $PATH:

       $ export PATH = $PATH:/usr/local/bin
       $ source ~/.bash_profile
      

      Note: If your PATH doesn’t include /usr/local/bin directory, we recommend adding it so that you can access it globally.

    5. You can also check the version of Composer by running the following command:

       $ composer --version.       
      

    1. Run the following command:

       $ curl -sS https://getcomposer.org/installer | php
      
    2. Run the following command to make the composer.phar file as executable:

       $ chmod +x composer.phar
      

      Note: PHAR (PHP archive) is an archive format for PHP that can be run on the command line

    3. Run the following command to make Composer globally available for all system users:

       $ mv composer.phar /usr/local/bin/composer
      

    1. Download and run the Windows Installer for Composer.

      Note: Make sure to allow Windows Installer for Composer to make changes to your php.ini file.

    2. If you have any terminal windows open, close all instances and open a fresh terminal instance.
    3. Run the Composer command.

       $ composer -V
      

    Install Laravel & Create a Laravel Project

    • Use the below command to install Laravel:

      $ composer require laravel/installer
      

    As we have Laravel and its dependencies installed, we can use them to create a new Laravel project. As the initial step, using Laravel we can auto-generate code in the Laravel folder structure.

    • Change the directory to our project directory in the command line:

      $ cd mylaravelapp
      
    • Use the below command to start your Laravel project:

      $ composer create-project laravel/laravel numbermasking --prefer-dist
      
    • To install the stable release, run the following command in the project directory:

      $ composer require plivo/plivo-php
      

    This will create a numbermasking directory with the necessary folders & files for development.

    Install Plivo

    • To install a specific release, run the following command in the project directory:

      $ composer require plivo/plivo-php:4.15.0
      
    • Alternatively, you can download this source and run

      $ composer install
      

    This generates the autoload files, which you can include using the following line in your PHP source code to start using the SDK.

    <?php
    require 'vendor/autoload.php'
    

    Create a 1:1 map with actual numbers

    • Whenever a customer places an order, the customer’s phone number is stored on your app’s database.
    • A delivery executive will be assigned for that order, and the agent’s number is also stored on your database and mapped with the customer’s number. For example,
        Customer's Number		<->		Agent's Number
        1-415-666-7777					1-415-666-7778
      
    • In this guide, we have created a sample mapping data in config/app.php file like below:
        'customer_agent_map' => [
            '14156667777' => '14156667778',
            '14156667779' => '14156667780',
            '14156667781' => '14156667782',
        ],
      

    Create a Laravel Controller for Number Masking

    Change the directory to our newly created project directory, i.e, numbermasking directory and run the below command to create a Laravel controller for inbound calls.

    $ php artisan make:controller MaskingController
    

    This will generate a controller named MaskingController in the app/http/controllers/ directory. Now, You have to open the app/http/controllers/MaskingController.php file and add the following code:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    
    <?php
    
    namespace App\Http\Controllers;
    require '../../vendor/autoload.php';
    use Plivo\RestClient;
    use Plivo\XML\Response;
    use Illuminate\Http\Request;
    use Illuminate\Support\Facades\Log;
    use Config;
    
    class MaskingController extends Controller
    {
        // Handle incoming calls to a Plivo number, connect agent with customer and vice versa without revealing their actual phone numbers. 
        public function numberMasking(Request $request)
        {
            $from_number = $_REQUEST['From'];
            $to_number = $_REQUEST['To'];
            $response = new Response();
            $customerPhoneMaping = Config::get('app.customer_agent_map');
            $customer_to_agent = array_key_exists($from_number, $customerPhoneMaping); // To check if the Customer's number is existing in the Customer-Agent mapping
            $agent_to_customer = array_key_exists($from_number, array_flip($customerPhoneMaping)); // To check if the Agent's number is existing in the Customer-Agent mapping
            if ($customer_to_agent == true){
                $number = $customerPhoneMaping[$from_number]; // This will assign the Value from the customer-agent array to $number variable
                $params = array(
                    'callerId' => $to_number, // Plivo number will be used as the caller ID for the call towards Agent
                );
                $dial = $response->addDial($params);
                $dial->addNumber($number);
            } elseif ($agent_to_customer == true){
                $number = array_search($from_number, $customerPhoneMaping); // This will assign the Key from the customer-agent array to $number variable
                $params = array(
                    'callerId' => $to_number, // Plivo number will be used as the caller ID for the call towards Customer
                );
                $dial = $response->addDial($params);
                $dial->addNumber($number);
            }
            $xml_response = $response->toXML(); 
            return response($xml_response, 200)->header('Content-Type', 'application/xml');
        }
    }
    

    Add a Route

    Now, you need to add a route for all the functions in the MaskingController class, open the routes/web.php file and add the below line at the end of the file:

    Route::match(['get', 'post'], '/numbermasking', 'App\Http\Controllers\MaskingController@numberMasking');
    
    Note: open the app/Http/Middleware/VerifyCsrfToken.php file and add the route of the app "/numbermasking" to the "except" array to disable CSRF verification.

    Now the MaskingController is ready to handle incoming calls to a Plivo number, connect agent with customer and vice versa without revealing their actual phone numbers. You can use the below command to start the Laravel server to forward incoming calls and to handle callbacks.

    $ php artisan serve
    

    Your local development server will be started and you can test the laravel app for outbound calls via the URL http://127.0.0.1:8000/numbermasking/.

    Exposing your local server to the internet

    To receive Incoming Calls and to handle callbacks, your local server should be able to connect with Plivo API service, Ngrok is a tunneling software used to expose a web server running on your local machine to the internet. Using Ngrok you can set webhooks which can talk to Plivo server.

    ngrok block diagram

    You can download and install ngrok from here. Follow the detailed configuration instructions to get started.

    Run ngrok on the port which currently hosts your application. For example, if your port number is 5000, run the following command:

    ./ngrok http 5000
    

    This will give you a UI with links that look like ngrok.io/* which you can use to access your local server using the public network.

    Sample ngrok CLI

    • If the incoming call to your Plivo number is from one of the phone numbers of the customer in the Customer <-> Agent Map, for example, if the caller number is “14156667777” then the XML response to process the incoming call will be as below, you can check the XML document in your browser.

      XML Document - Customer Calls Agent

    • If the incoming call to your Plivo number is from one of the phone numbers of the agent in the Customer <-> Agent Map, for example, if the caller number is “14156667778” then the XML response to process the incoming call will be as below, you can check the XML document in your browser.

      XML Document - Agent Calls Customer

    Create a Plivo Application

    1. Create an Application by visiting the Application Page and click on New Application or by using Plivo’s Application API.
    2. Give your application a name. Let’s call it Phone IVR. Enter your server URL (e.g., https://84b781ed8406.ngrok.io/numbermasking/) in the Answer URL field and set the method as GET. See our Application API docs to learn how to modify your application through our APIs.
    3. Click on Create to save your application.

      Create Application - Number Masking

    Assign a Plivo number to your app

    1. Navigate to the Numbers page and select the phone number you want to use for this app.
    2. Select Phone IVR (name of the app) from the Plivo App dropdown list.
    3. Click on ‘Update Number’ to save.

      Assign Application - Number Masking

    Test and validate

    To test how “Number Masking” works, you need two mobile numbers. You can set one of your mobile numbers as a customer and another one as an agent in the customer: agent mapping data in the config file and make a call to your Plivo phone number. If you call from “mobile number 1” to the Plivo number, you will see that the call is forwarded to your “mobile number2” with the Plivo number as the caller ID. The same setup will work for calls from “mobile number2” to “mobile number1” with the Plivo number as the caller ID.