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.
This method creates a session to anonymously connect two participants.
POST
https://api.plivo.com/v1/Account/{Auth ID}/Masking/Session
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 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 |
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 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 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. 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 |
pin_retry_wait integer |
Indicates the wait time in seconds before executing the pin_retry Default: 5 secs |
incorrect_pin_play string |
The URL of the playback file utilized when an incorrect PIN is entered. 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.
|
recording_callback_url string |
URL to which the call recording is sent. |
record_file_format string |
Audio format for the recording. |
recording_callback_method string |
HTTP verb to invoke the URL configured as recording_callback_url. |
session_expiry integer |
Time in seconds after which the session mapping will end. |
call_time_limit integer |
Time in seconds after which the call will be disconnected. |
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. |
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. |
ring_timeout integer |
Time in seconds after which the ring should be disconnected. |
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. |
{
"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": ""
}
}
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)
}