Get Started with Number Masking Using PHP

    Overview

    Phone number masking hides the phone numbers of parties in a call from each other. Many businesses find it advantageous to anonymize communication between two parties — for example, between a customer and a delivery agent on a food delivery service platform or a driver and a rider using a ride-hailing application. Businesses can implement phone number masking by sending calls through an intermediate phone number that acts as a proxy between the two parties. A Plivo number can serve as the intermediate number to connect the two parties while keeping their contact information private.

    How it works

    Implementation

    As an example, we’ll build a number-masking application for a food delivery service that lets the company connect customers with delivery agents and vice versa without revealing any actual phone numbers. To do this, you

    1. Create a customer-to-agent phone number mapping in your application’s back end.
    2. Create the number masking application using Plivo.
    3. Assign the number masking application to a Plivo number.

    Set up your PHP dev environment

    Install PHP using the official macOS installer or Windows installer or your favorite Linux package manager.

    You should also install Composer, a dependency manager for PHP that’s used in all modern PHP frameworks, such as Symfony and Laravel. We recommend using Composer as the package manager for your web project.

    1. Download the latest version of Composer.
    2. Run Composer with the command:

       $ 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 these commands to make it executable:

       $ cp ~/Downloads/composer.phar /usr/local/bin/composer
       $ sudo chmod +x /usr/local/bin/composer
      
    4. If your PATH doesn’t include /usr/local/bin directory, we recommend adding it so that you can access it globally. To check whether the PATH environment variable includes /usr/local/bin, type

       $ echo $PATH
      

      If it doesn’t include the directory, update the $PATH by running the commands

       $ export PATH = $PATH:/usr/local/bin
       $ source ~/.bash_profile
      
    5. You can also check the version of Composer by running the command

       $ composer --version       
      

    1. Install Composer with the command

       $ curl -sS https://getcomposer.org/installer | php
      
    2. Make the composer.phar file executable with the command

       $ chmod +x composer.phar
      

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

    3. Make Composer globally available for all system users by running

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

    1. Download and run the Windows installer for Composer. Make sure you allow the installer 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 and create a Laravel project

    Install Laravel with the command

    $ composer require laravel/installer
    

    Then auto-generate code in the Laravel folder structure. Change to the project directory (cd mylaravelapp), then create a new Laravel project:

    $ composer create-project laravel/laravel numbermasking --prefer-dist
    

    This command creates a numbermasking directory with the necessary folders and files for development.

    Install the Plivo PHP SDK

    • To install the stable release of the Plivo SDK, run this command in the project directory:

      $ composer require plivo/plivo-php
      
    • To install a specific release, use this syntax:

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

      $ composer install
      

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

    <?php
    require 'vendor/autoload.php'
    

    Create a 1:1 map with actual numbers

    Now create customer-to-agent phone number mapping for the application. Whenever a customer places an order, their phone number should be stored in a database for your application to access. A delivery agent will be assigned for the order, and the agent’s number will also be stored in your database, and will be mapped to the customer’s number:

    Customer’s Number		<->		Agent’s Number
      1-415-666-7777					1-415-666-7778
    

    We created sample mapping data in a config/app.php file: php 'customer_agent_map' => [ '14156667777' => '14156667778', '14156667779' => '14156667780', '14156667781' => '14156667782', ],

    Create a Laravel controller for number masking

    Change to the newly created numbermasking project directory if you’re not there already and run this command to create a Laravel controller for inbound calls.

    $ php artisan make:controller MaskingController
    

    This command generates a controller named MaskingController in the app/http/controllers/ directory. Edit the app/http/controllers/MaskingController.php file and add this 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

    To add a route for all the functions in the MaskingController class, edit the routes/web.php file and add this line at the end of the file:

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

    Now MaskingController is ready to handle incoming calls to a Plivo number. Run this command to start the Laravel server to forward incoming calls.

    $ php artisan serve
    

    You should see the Laravel app in action on http://localhost:8000/numbermasking/

    Expose your local server to the internet

    To receive incoming calls, your local server should be able to connect with Plivo API services. For that, we recommend using ngrok, which exposes local servers behind NATs and firewalls to the public internet over secure tunnels.

    ngrok block diagram

    Install ngrok and run it on the command line, specifying the port that hosts the application on which you want to receive messages (5000 in this case):

    ./ngrok http 5000
    

    Ngrok will display a forwarding link that you can use as a webhook to access your local server over the public network.

    Sample ngrok CLI

    Now people can call your Plivo number. If an incoming call to your Plivo number is from one of the customer phone numbers in the Customer <-> Agent Map — for example, if the caller number is 14156667777 — then Plivo will send the XML response to process the incoming call as below, and 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 agent phone numbers in the Customer <-> Agent Map — for example, if the caller number is 14156667778 — then Plivo will send the XML response to process the incoming call as below, and you can check the XML document in your browser.

    XML Document - Agent Calls Customer

    Create a Plivo application

    1. Create a Plivo application by visiting the Voice > Applications > XML page of the console and clicking on Add New Application, or by using Plivo’s Application API.

    2. Give your application a name — we used Number Masking. Enter your server URL (for example, https://61d8fb8f250c.ngrok.io/handleincoming/) in the Primary 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 Application to save your application.

    Create Application - Number Masking

    Assign a Plivo number to your application

    1. Navigate to the Numbers page and select the phone number you want to use for the application.
    2. Select XML Application from the Application Type drop-down list, and Number Masking (the name of the application) from the Plivo Application drop-down list.
    3. Click on Update Number to save the number assignment.

      Assign Application - Number Masking

    Test and validate

    To test the application, you need two Plivo mobile numbers. Set up one of your mobile numbers as a customer and another as an agent in the customer-to-agent mapping data in the config file. Make a call from each of your mobile numbers to the Plivo number you mapped to the application. You should see that the call is forwarded to the other number, and the incoming call has the Plivo number as the caller ID.