Latest Legacy

Create a number masking session

You create a number masking session using the real phone numbers of the two parties that need to be connected. Plivo returns a virtual number from your account in response to the API request.

  • If one party makes a call to the virtual number, the call is connected to the other party.
  • The caller ID of the outbound call to the second party is the Plivo virtual number.

This method creates a session to anonymously connect two participants.

POST https://api.plivo.com/v1/Account/{Auth ID}/Masking/Session

Attributes

first_party stringRequired

The actual phone number of the first party.
second_party stringRequired

The actual phone number of the second party.
geomatch BooleanOptional

Specifies if the country of the virtual number used for session allocation must match the first_party number.

When the geomatch parameter is enabled, Plivo searches for a virtual number that matches with the country code of the first_party number from the number pool.

Default: true

Possible values: true/false
is_pin_authentication_required boolean

Specifies whether PIN authentication is necessary when the call originates from an unidentified caller.

Default: false
generate_pin booleanConditional

Indicates if Plivo has to generate the PIN for the session.

Applicable only when is_pin_authentication_required is set to true

Default: false
generate_pin_length intConditional

Indicates the length of the PIN to be generated by plivo. Applicable when generate_pin is set to true.

Default: 4
Minimum value : 4
Maximum value : 15
first_party_pin string

The PIN is provided to the first party if they attempt to contact the virtual number using their secondary number.

The first_party_pin provided has to be different from second_party_pin

Allowed value: 0 to 9
Minimum length: 4
Maximum length: 15

Note: Required when is_pin_authentication_required is set to true
second_party_pin string

The PIN is provided to the second party if they attempt to contact the virtual number using their secondary number.

The second_party_pin provided has to be different from first_party_pin

Allowed values: 0 to 9
Minimum length: 4
Maximum length: 15

Note: Required when is_pin_authentication_required is set to true
subaccount StringOptional

Specifies the sub-account auth ID for which the session is created.

When this is provided Plivo will allocate a virtual number to be associated exclusively with the specified subaccount provided.
pin_prompt_play string

The URL for the playback file utilized as a greeting message to prompt the entry of a PIN when dialing the virtual number from a secondary number.
Relevant when a PIN is activated for the session.

Allowed format: .mp3 or .wav file only

Note: Required when is_pin_authentication_required is set to true
pin_retry integer

Indicates the number of retries if an incorrect PIN is provided by the caller.

Applicable when a PIN is enabled for the session.

Allowed values : 0 to 5
Default: 1
pin_retry_wait integer

Indicates the wait time in seconds before executing the pin_retry

Default: 5 secs
Min : 5 secs
Max: 10 secs
incorrect_pin_play string

The URL of the playback file utilized when an incorrect PIN is entered.
Relevant when a PIN is activated for the session.
Supported formats: only .mp3 or .wav files are allowed.

Note: Required when is_pin_authentication_required is set to true
unknown_caller_play string

The URL for the playback file used when an unknown caller makes a call to the virtual number.

Allowed formats: .mp3 or .wav file only
record boolean

Recording status for a phone call.
Defaults to false.
If set to true:

  • Call recording starts only when both parties have answered their calls.
  • Multiple calls within a session generate multiple recording files.
recording_callback_url string

URL to which the call recording is sent.
record_file_format string

Audio format for the recording.
Allowed values: mp3, wav Defaults to mp3.
recording_callback_method string

HTTP verb to invoke the URL configured as recording_callback_url.
Allowed values: GET, POST Defaults to POST.
session_expiry integer

Time in seconds after which the session mapping will end.
Calls made to the virtual phone number after the session ends are not forwarded to the other party; the default answer_url or application_url associated with the virtual number will be activated.
Defaults to 3,600.
call_time_limit integer

Time in seconds after which the call will be disconnected.
This applies to all call legs within a session.
Default: 3,600
initiate_call_to_first_party boolean

If set to true, Plivo will immediately make a call to the first party number. If the call is answered, it will be bridged with the second party.
Defaults to false.
callback_url string

URL to receive important session events and status updates.
callback_method string

HTTP verb to invoke the URL configured as callback_url.
Allowed values: GET, POST Defaults to POST.
ring_timeout integer

Time in seconds after which the ring should be disconnected.
Applies to both call legs.
Defaults to 120.
first_party_play_url string

URL that returns an .mp3 or .wav file to be played to the first party before connecting to the second party.
second_party_play_url string

URL that returns an MP3 or WAV file to be played to the second party before connecting to the first party.
create_session_with_single_partybooleanOptional

Indicates if a session needs to be created with a single party. Either first_party or second_party is mandatory.

Default: false
virtual_number_cooloff_periodintegerOptional

Indicates the cool-off period within which the number can be reallocated to a different session. The virtual_number_cooloff_period must be a positive integer.

The virtual number used in a session will not be reused for a different session during the specified cool-off period.

Default: 0
Max: 3600
force_pin_authenticationbooleanConditional

Indicates whether PIN authentication is required even when the call originates from the registered mobile number.

Applicable only when is_authentication_required is set to true.

Default: false

Response

{
  "api_id": "ae245217-f78e-4939-bc48-d4b8ef05cf66",
  "session_uuid": "4189591e-d004-4801-abdf-8893c15e5dcd",
  "virtual_number": "+912269947011",
  "message": "Session created",
  "session": {
    "first_party": "919003459XXX",
    "second_party": "919840037XXX",
    "virtual_number": "912269947011",
    "status": "active",
    "initiate_call_to_first_party": false,
    "first_party_pin": "1234",
    "second_party_pin": "4321",
    "is_pin_authentication_required": true,
    "generate_pin": false,
    "generate_pin_length": 4,
    "pin_ prompt_play": "https://play.s3.eu-north-1.amazonaws.com/pin_prompt.wav",
    "pin_retry": 1,
    "pin_retry_wait": "5",
    "incorrect_pin_play": "https://play.s3.eu-north-1.amazonaws.com/incorrect_pin.wav",
    "session_uuid": "4189591e-d004-4801-abdf-8893c15e5dcd",
    "callback_url": "https://webhook.site/0ece3c18-f1e4-48a8-98fe-b8f651e53eef",
    "callback_method": "POST",
    "created_time": "2024-01-03 13:35:51 +0000 UTC",
    "modified_time": "2024-01-03 13:35:51 +0000 UTC",
    "expiry_time": "2024-01-03 14:05:51 +0000 UTC",
    "duration": 1800,
    "amount": 0,
    "call_time_limit": 14400,
    "ring_timeout": 45,
    "first_party_play_url": "https://play.s3.eu-north-1.amazonaws.com/agent.wav",
    "second_party_play_url": "https://play.s3.eu-north-1.amazonaws.com/customer.wav",
    "record": false,
    "subaccount": "SAOWRKMGU3YZCTZJXXX",
    "record_file_format": "mp3",
    "recording_callback_url": "",
    "recording_callback_method": "POST",
    "interaction": null,
    "total_call_amount": 0,
    "total_call_count": 0,
    "total_call_billed_duration": 0,
    "total_session_amount": 0,
    "last_interaction_time": ""
  }
}

Example Request 

1
2
3
4
5
6
7

import plivo

client = plivo.RestClient(auth_id='<auth_id>', auth_token='<auth_token>')
response = client.masking_sessions.create_masking_session(
                                                      first_party="+12025550XXX",
                                                      second_party="+12025551XXX")
print(response)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

require 'rubygems'
require "plivo"

include Plivo
include Plivo::Exceptions

api = RestClient.new("<auth_id>", "<auth_token>")

begin
  response = api.maskingsession.create(
    first_party:+12025550XXX,
    second_party:'+12025551XXX,
  )
  puts response
rescue PlivoRESTError => e
  puts 'Exception: ' + e.message
end

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

var plivo = require('plivo');

(function main() {
    'use strict';

    var client = new plivo.Client("<auth_id>", "<auth_token>");
    client.maskingSession.createMaskingSession(
        "+12025550XXX", "+12025551XXX",
        {
            callTimeLimit:600
        }
    ).then(function (response) {
        console.log(response);
    }, function (err) {
        console.error(err);
    });
})();

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

<?php
/**
 * Example for Create Session
 */
require 'vendor/autoload.php';
use Plivo\RestClient;
use Plivo\Exceptions\PlivoRestException;
$client = new RestClient("<auth_id>", "<auth_token>");
try {
    $response = $client->maskingSessions->createMaskingSession(
        '+12025550XXX',
        '12025551XXX')
    );

    print_r($response);
}
catch (PlivoRestException $ex) {
    print_r($ex);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

package com.plivo.examples;

import com.plivo.api.Plivo;
import com.plivo.api.exceptions.PlivoRestException;
import com.plivo.api.models.maskingsession.MaskingSession;
import com.plivo.api.models.maskingsession.MaskingSessionCreateResponse;

import java.io.IOException;

class CreateSession {
  public static void main(String [] args) {
    Plivo.init("<auth_id>","<auth_token>");
    try {
      MaskingSessionCreateResponse response = MaskingSession.creator("12025550XXX", "12025551XXX")
        .create();
      System.out.println(response);
    } catch (PlivoRestException | IOException e) {
      System.out.println(e);
      e.printStackTrace();
    }
  }
}

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

using System;
using Plivo;
using Plivo.Exception;

namespace PlivoExamples
{
    class Program
    {
        static void Main(string[] args)
        {
            var api = new PlivoApi("<auth_id>","<auth_token>");
            try
            {
                var response = api.MaskingSession.Create(
                    firstParty: "12025550000",
                    secondParty: "12025551111"
                );
                Console.WriteLine(response);
            }
            catch (PlivoRestException e)
            {
                Console.WriteLine("Exception: " + e.Message);
            }
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

curl -X POST "https://api.plivo.com/v1/Account/{Auth ID}/Masking/Session" \
-H "Content-Type: application/json" \
-d '{
  "first_party": "+919003459XXX",
  "second_party": "+919840037XXX",
  "is_pin_authentication_required": true,
  "first_party_pin": 1234,
  "second_party_pin": 4321,
  "pin_prompt_play": "https://play.s3.eu-north-1.amazonaws.com/pin_prompt.wav",
  "geomatch": true,
  "subaccount": "SAOWRKMGU3YZCTZJXXX",
  "incorrect_pin_play": "https://play.s3.eu-north-1.amazonaws.com/incorrect_pin.wav"
}
'

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

package main

import (
       "fmt"

       "github.com/plivo/plivo-go/v7"
)

func main() {
       client, err := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})
       if err != nil {
               fmt.Print("Error", err.Error())
               return
       }
       response, err := client.MaskingSession.CreateMaskingSession(
               plivo.CreateMaskingSessionParams{
  "FirstParty": "+919003459XXX",
  "SecondParty": "+919840037XXX",
  "IsPinAuthenticationRequired": true,
  "FirstPartyPin": 1234,
  "SecondPartyPin": 4321,
  "PinPromptPlay": "https://play.s3.eu-north-1.amazonaws.com/pin_prompt.wav",
  "IncorrectPinPlay": "https://play.s3.eu-north-1.amazonaws.com/incorrect_pin.wav"
}

,
       )
       if err != nil {
               fmt.Print("Error", err.Error())
               return
       }
       fmt.Printf("Response: %#v\n", response)
}