Number masking, also known as call masking, allows businesses to facilitate communication while safeguarding customers’ privacy. It uses an intermediate virtual phone number to connect a caller with a call recipient. The real phone numbers of the two parties are kept hidden from each other.
Plivo’s Number Masking APIs let you create sessions to anonymously connect two phone numbers, manage these sessions, and capture the details of all interactions within a session. The APIs need at least one Plivo virtual phone number in your account to work.
All requests to Plivo APIs are authenticated with BasicAuth using the values of Auth ID and Auth Token that appear on the Overview page of the console.
Plivo only accepts input of the type application/json.
All POST requests arguments must be passed as text in JSON format with the Content-Type set as application/json.
All GET and DELETE request arguments must be passed in the query string.
Plivo’s server SDKs let you specify timeouts and proxy settings to be used when making API requests. Select the programming language of your choice and view the latest version to see how to specify these settings.
Plivo uses offset-based pagination to list resources.
For instance, if your search request has a result of 100 objects with limit = 10 and offset = 5, then objects with indices 51 through 60 are returned.
limit integer |
A limit on the number of results to be returned. limit can range between 1 and 20, and the default is 20. |
offset integer |
A pagination cursor that denotes the number of objects by which the results should be offset. |
All list responses are returned from the most recent to the oldest date. The data covers the last 90 days. If search boundaries are not provided, the default search window is 7 days.
The session API endpoints return responses in JSON format. Plivo sets an api_id in each response to uniquely identify the request. Each API call returns one of these HTTP status codes depending on whether the call succeeds or fails:
200 |
Request has been executed |
201 |
Resource created |
202 |
Resource changed |
204 |
Resource deleted |
400 |
A parameter is missing or is invalid |
401 |
Authentication failed |
404 |
Resource cannot be found |
405 |
HTTP method not allowed |
429 |
Too many requests, rate limited |
500 |
Server error |
Sessions establish anonymous connections between two phone numbers.
session_uuid string |
Unique identifier for the session. |
first_party string |
The actual phone number of the first participant. |
second_party string |
The actual phone number of the second participant. |
virtual_number string |
Plivo phone number to be dialed for connecting with the other participant. |
record boolean |
Determines the 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 that should be used to invoke the URL configured as recording_callback_url. |
session_expiry integer |
Time in seconds after which the session mapping will expire. |
call_time_limit integer |
Time in seconds after which the call should be disconnected. |
status string |
Current status of the session. |
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 on which 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. |
created_time timestamp |
UTC time when the session was created (yyyy-mm-dd, hh-mm-ss). |
modified_time timestamp |
UTC time when the session was last modified (yyyy-mm-dd, hh-mm-ss). |
expiry_time timestamp |
UTC time when the session will expire (yyyy-mm-dd, hh-mm-ss). |
last_interaction_time timestamp |
UTC time when the latest interaction ended within the session (yyyy-mm-dd, hh-mm-ss). |
total_call_count integer |
Total count of all calls (individual call_uuids) made within the session. |
total_call_amount string |
Total billed amount for all calls within the session. |
total_call_billed_duration integer |
Total rounded bill duration for all calls within the session. |
interaction string |
Interaction object that contains all the interactions within the session. See the Interaction Object section below for details. |
duration integer |
Duration of the session in seconds. |
amount string |
Total charge incurred for creating the session. |
total_session_amount string |
Total charges incurred for hosting the session. This includes all call-related charges and session creation charges. |
All list responses are returned from the most recent to the oldest date. The data covers the last 90 days. If search boundaries are not provided, the default search window is 7 days.
The Interaction object is a nested object within the session. A masking session can contain multiple interactions. Each interaction within a session has a maximum of two communication legs, regardless of the direction of the call.
first_party_resource_url string |
URL of the call-leg resource created for the first party. |
second_party_resource_url string |
URL of the call-leg resource created for the second party. |
recording_resource_url string |
URL of the recording resource for the interaction. |
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_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 |
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. |
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 |
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 |
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)
Was this code helpful
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
Was this code helpful
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);
});
})();
Was this code helpful
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);
}
Was this code helpful
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();
}
}
}
Was this code helpful
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);
}
}
}
}
Was this code helpful
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"
}
'
Was this code helpful
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)
}
Was this code helpful
{
"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": ""
}
}
The following resource allows you to update the session.
POST
https://api.plivo.com/v1/Account/{Auth ID}/Masking/Session/{session_uuid}
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. |
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 will 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. |
first_partystring |
The actual phone number of the first participant. This update is applicable only when the session is created with create_session_with_single_party set to true. |
second_partystring |
The actual phone number of the second participant. An update is applicable only when the session is created with create_session_with_single_party as true. |
1
2
3
4
5
6
7
8
import plivo
client = plivo.RestClient(auth_id='<auth_id>', auth_token='<auth_token>')
response = client.masking_sessions.update_masking_session(
session_uuid="session_uuid",
call_time_limit=3600,
record=true)
print(response)
Was this code helpful
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
require 'rubygems'
require "/root/plivo-ruby/lib/plivo.rb"
include Plivo
include Plivo::Exceptions
api = RestClient.new("<auth_id>", "<auth_token>")
begin
response = api.maskingsession.update(
"<session_uuid>",
{
call_time_limit=1440,
record:true
}
)
puts response
rescue PlivoRESTError => e
puts 'Exception: ' + e.message
end
Was this code helpful
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
var plivo = require('plivo');
(function main() {
'use strict';
var client = new plivo.Client("<auth_id>", "<auth_token>");
client.maskingSession.updateMaskingSession("SessionUUID",
{
sessionExpiry:120
}
).then(function (response) {
console.log(response);
}, function (err) {
console.error(err);
});
})();
Was this code helpful
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
<?php
/**
* Example for Update Session
*/
require 'vendor/autoload.php';
use Plivo\RestClient;
use Plivo\Exceptions\PlivoRestException;
$client = new RestClient("<auth_id>", "<auth_token>");
try {
$response = $client->maskingSessions->updateMaskingSession(
'SessionUUID',
array('call_time_limit'=>3600,
)
);
print_r($response);
}
catch (PlivoRestException $ex) {
print_r($ex);
}
Was this code helpful
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
package com.plivo.examples;
import com.plivo.api.Plivo;
import com.plivo.api.exceptions.PlivoRestException;
import com.plivo.api.exceptions.PlivoValidationException;
import com.plivo.api.models.maskingsession.MaskingSession;
import com.plivo.api.models.maskingsession.MaskingSessionUpdateResponse;
import java.io.IOException;
class UpdateSession {
public static void main(String [] args) {
Plivo.init("<auth_id>","<auth_token>");
try {
MaskingSessionUpdateResponse response = MaskingSession.updater("<session_uuid>")
.callTimeLimit(14400)
.record(true)
.update();
System.out.println(response);
} catch (PlivoRestException | IOException e) {
System.out.println(e);
e.printStackTrace();
} catch (PlivoValidationException e) {
throw new RuntimeException(e);
}
}
}
Was this code helpful
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
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.Update(sessionUuid: "<session_uuid>",
session_expiry: 6000);
Console.WriteLine(response);
}
catch (PlivoRestException e)
{
Console.WriteLine("Exception: " + e.Message);
}
}
}
}
Was this code helpful
1
2
3
4
5
6
curl -X POST "https://api.plivo.com/v1/Account/{Auth ID}/Masking/Session/abcd-1234-ab12-cd34" \
-H "Content-Type: application/json" \
-d '{
"record": "true",
"recording_callback_url": "https://www.example.com/recording",
}'
Was this code helpful
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
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.UpdateMaskingSession(
plivo.UpdateMaskingSessionParams{
SessionExpiry: 120},
"SessionUUID", )
if err != nil {
fmt.Print("Error", err.Error())
return
}
fmt.Printf("Response: %#v\n", response)
}
Was this code helpful
{
"api_id": "32d333cb-3709-4b9b-b27b-3296aca6e1cc",
"message": "Session updated",
"session": {
"first_party": "919003459051",
"second_party": "918197241073",
"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": "c28b77d4-21e7-43bd-9447-04bfee92e651",
"callback_url": "",
"callback_method": "POST",
"created_time": "2024-02-01 06:28:15 +0000 UTC",
"modified_time": "2024-02-01 06:28:37 +0000 UTC",
"expiry_time": "2024-02-01 06:58:15 +0000 UTC",
"duration": 1800,
"amount": 0,
"call_time_limit": 14400,
"ring_timeout": 45,
"first_party_play_url": "",
"second_party_play_url": "",
"record": true,
"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": ""
}
}
This method fetches details of an existing masking session.
GET
https://api.plivo.com/v1/Account/{Auth ID}/Masking/Session/{session_uuid}
1
2
3
4
5
import plivo
client = plivo.RestClient(auth_id='<auth_id>', auth_token='<auth_token>')
response = client.masking_sessions.get_masking_session("session_uuid")
print(response)
Was this code helpful
1
2
3
4
5
6
7
8
9
10
11
12
13
14
require 'rubygems'
require "/root/plivo-ruby/lib/plivo.rb"
include Plivo
include Plivo::Exceptions
api = RestClient.new("<auth_id>", "<auth_token>")
begin
response = api.maskingsession.get('<session_uuid>')
puts response
rescue PlivoRESTError => e
puts 'Exception: ' + e.message
end
Was this code helpful
1
2
3
4
5
6
7
8
9
10
11
12
13
var plivo = require('plivo');
(function main() {
'use strict';
var client = new plivo.Client("<auth_id>", "<auth_token>");
client.maskingSession.getMaskingSession("SessionUUID"
).then(function (response) {
console.log(response);
}, function (err) {
console.error(err);
});
})();
Was this code helpful
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<?php
/**
* Example for Get Session
*/
require 'vendor/autoload.php';
use Plivo\RestClient;
use Plivo\Exceptions\PlivoRestException;
$client = new RestClient("<auth_id>", "<auth_token>");
try {
$response = $client->maskingSessions->getMaskingSession(
'SessionUUID'
);
print_r($response);
}
catch (PlivoRestException $ex) {
print_r($ex);
}
Was this code helpful
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
package com.plivo.examples;
import com.plivo.api.Plivo;
import com.plivo.api.exceptions.PlivoRestException;
import com.plivo.api.exceptions.PlivoValidationException;
import com.plivo.api.models.maskingsession.MaskingSession;
import java.io.IOException;
class getSession {
public static void main(String [] args) {
Plivo.init("<auth_id>","<auth_token>");
try {
MaskingSession response = MaskingSession.getter("<session_uuid>").get();
System.out.println(response);
} catch (PlivoRestException | IOException e) {
System.out.println(e);
e.printStackTrace();
} catch (PlivoValidationException e) {
throw new RuntimeException(e);
}
}
}
Was this code helpful
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
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.Get(sessionUuid: "<session_uuid>");
Console.WriteLine(response);
}
catch (PlivoRestException e)
{
Console.WriteLine("Exception: " + e.Message);
}
}
}
}
Was this code helpful
1
2
curl -X GET "https://api.plivo.com/v1/Account/{Auth ID}/Masking/Session/{session_uuid}" \
-H "Content-Type: application/json" \
Was this code helpful
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
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.GetMaskingSession("Session UUID")
)
if err != nil {
fmt.Print("Error", err.Error())
return
}
fmt.Printf("Response: %#v\n", response)
}
Was this code helpful
{
"api_id": "678c8b24-b703-43aa-8690-d28e7f163d18",
"response": {
"first_party": "919003459051",
"second_party": "918197241073",
"virtual_number": "912269947011",
"status": "expired",
"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": "c28b77d4-21e7-43bd-9447-04bfee92e651",
"callback_url": "",
"callback_method": "POST",
"created_time": "2024-02-01 06:28:15 +0000 UTC",
"modified_time": "2024-02-01 06:28:37 +0000 UTC",
"expiry_time": "2024-02-01 06:58:15 +0000 UTC",
"duration": 1800,
"amount": 0,
"call_time_limit": 14400,
"ring_timeout": 45,
"first_party_play_url": "",
"second_party_play_url": "",
"record": true,
"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": ""
}
}
This method fetches details of all existing masking sessions.
GET
https://api.plivo.com/v1/Account/{Auth_ID}/Masking/Session
first_party string |
The actual phone number of the first party. |
second_party string |
The actual phone number of the second party. |
virtual_number string |
Virtual number assigned for the session. |
status string |
Allowed values: active, expired, all |
created_time string |
Filters sessions based on their created time. The time format expected is YYYY-MM-DD HH:MM[:ss[.uuuuuu]]. You can use variants of this attribute:
The default search window is seven days, and the maximum search window is 30 days. |
expiry_time string |
Filters sessions based on their expiry time. The time format expected is YYYY-MM-DD HH:MM[:ss[.uuuuuu]]. You can use variants of this attribute:
The default search window is seven days, and the maximum search window is 30 days. |
duration string |
Filters sessions based on duration in seconds. You can use variants of this attribute:
The default search window is seven days and the maximum search window is 30 days. |
limit integer |
Limits the number of results retrieved. |
offset integer |
Denotes the number of value items by which the results should be offset. For example, if the results contain 100 values and limit is set to 10 and offset is set to five, then values 51 through 60 are displayed in the results. This parameter is also used for the pagination of the results. |
1
2
3
4
5
import plivo
client = plivo.RestClient(auth_id='<auth_id>', auth_token='<auth_token>')
response = client.masking_sessions.list_masking_session(status='active')
print(response)
Was this code helpful
1
2
3
4
5
6
7
8
9
10
11
12
13
14
require 'rubygems'
require "/root/plivo-ruby/lib/plivo.rb"
include Plivo
include Plivo::Exceptions
api = RestClient.new("<auth_id>", "<auth_token>")
begin
response = api.maskingsession.list()
puts response
rescue PlivoRESTError => e
puts 'Exception: ' + e.message
end
Was this code helpful
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
var plivo = require('plivo');
(function main() {
'use strict';
var client = new plivo.Client("<auth_id>", "<auth_token>");
client.maskingSession.listMaskingSession(
{
Limit: 10
}
).then(function (response) {
console.log(response);
}, function (err) {
console.error(err);
});
})();
Was this code helpful
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<?php
/**
* Example for List Session
*/
require 'vendor/autoload.php';
use Plivo\RestClient;
use Plivo\Exceptions\PlivoRestException;
$client = new RestClient("<auth_id>", "<auth_token>");
try {
$response = $client->maskingSessions->listMaskingSession(
array('status'=>'active'
)
);
print_r($response);
}
catch (PlivoRestException $ex) {
print_r($ex);
}
Was this code helpful
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
package com.plivo.examples;
import java.io.IOException;
import com.plivo.api.Plivo;
import com.plivo.api.exceptions.PlivoRestException;
import com.plivo.api.exceptions.PlivoValidationException;
import com.plivo.api.models.base.ListResponse;
import com.plivo.api.models.maskingsession.MaskingSession;
class ListSession {
public static void main(String [] args) {
Plivo.init("<auth_id>","<auth_token>");
try {
ListResponse<MaskingSession> response = MaskingSession.lister().
.list();
System.out.println(response);
} catch (PlivoRestException | IOException | PlivoValidationException e) {
e.printStackTrace();
}
}
}
Was this code helpful
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
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.List();
Console.WriteLine(response);
}
catch (PlivoRestException e)
{
Console.WriteLine("Exception: " + e.Message);
}
}
}
}
Was this code helpful
1
2
curl -X GET "https://api.plivo.com/v1/Account/{Auth ID}/Masking/Session/" \
-H "Content-Type: application/json" \
Was this code helpful
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
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.ListMaskingSession(
plivo.ListSessionFilterParams{
Limit: 10},
)
if err != nil {
fmt.Print("Error", err.Error())
return
}
fmt.Printf("Response: %#v\n", response)
}
Was this code helpful
{
"api_id": "7d962130-8eb6-49f1-920b-ae4609bf6dfe",
"response": {
"meta": {
"limit": 20,
"next": null,
"offset": 0,
"previous": null,
"total_count": 1
},
"objects": [
{
"amount": 0,
"call_time_limit": 14400,
"callback_method": "POST",
"callback_url": "",
"created_time": "2024-02-01 06:28:15 +0000 UTC",
"duration": 1800,
"expiry_time": "2024-02-01 06:58:15 +0000 UTC",
"first_party": "919003459051",
"first_party_play_url": "",
"initiate_call_to_first_party": false,
"interaction": null,
"last_interaction_time": "",
"modified_time": "2024-02-01 06:28:37 +0000 UTC",
"record": true,
"record_file_format": "mp3",
"recording_callback_method": "POST",
"recording_callback_url": "",
"resource_uri": "/v1/Account/MAOTQ3NGFLNZRMZME1MT/Masking/Session/c28b77d4-21e7-43bd-9447-04bfee92e651/",
"ring_timeout": 45,
"second_party": "918197241073",
"second_party_play_url": "",
"session_uuid": "c28b77d4-21e7-43bd-9447-04bfee92e651",
"status": "expired",
"total_call_amount": 0,
"total_call_billed_duration": 0,
"total_call_count": 0,
"total_session_amount": 0,
"virtual_number": "912269947011"
}
]
}
}
This method terminates an ongoing session and marks it as expired.
DELETE
https://api.plivo.com/v1/Account/{Auth ID}/Masking/Session/{session_uuid}
1
2
3
4
5
import plivo
client = plivo.RestClient(auth_id='<auth_id>', auth_token='<auth_token>')
response = client.masking_sessions.delete_masking_session("session_uuid")
print(response)
Was this code helpful
1
2
3
4
5
6
7
8
9
10
11
12
13
14
require 'rubygems'
require "/root/plivo-ruby/lib/plivo.rb"
include Plivo
include Plivo::Exceptions
api = RestClient.new("<auth_id>", "<auth_token>")
begin
response = api.maskingsession.delete("<session_uuid>")
puts response
rescue PlivoRESTError => e
puts 'Exception: ' + e.message
end
Was this code helpful
1
2
3
4
5
6
7
8
9
10
11
12
13
var plivo = require('plivo');
(function main() {
'use strict';
var client = new plivo.Client("<auth_id>", "<auth_token>");
client.maskingSession.deleteMaskingSession("SessionUUID"
).then(function (response) {
console.log(response);
}, function (err) {
console.error(err);
});
})();
Was this code helpful
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<?php
/**
* Example for Delete Session
*/
require 'vendor/autoload.php';
use Plivo\RestClient;
use Plivo\Exceptions\PlivoRestException;
$client = new RestClient("<auth_id>", "<auth_token>");
try {
$response = $client->maskingSessions->deleteMaskingSession(
'SessionUUID'
);
print_r($response);
}
catch (PlivoRestException $ex) {
print_r($ex);
}
Was this code helpful
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
package com.plivo.examples;
import com.plivo.api.Plivo;
import com.plivo.api.exceptions.PlivoRestException;
import com.plivo.api.exceptions.PlivoValidationException;
import com.plivo.api.models.maskingsession.MaskingSession;
import java.io.IOException;
class DeleteSession {
public static void main(String [] args) {
Plivo.init("<auth_id>","<auth_token>");
try {
MaskingSession.deleter("<session_uuid>").delete();
} catch (PlivoRestException | IOException e) {
System.out.println(e);
e.printStackTrace();
} catch (PlivoValidationException e) {
throw new RuntimeException(e);
}
}
}
Was this code helpful
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
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.Delete(sessionUuid: "<session_uuid>");
Console.WriteLine(response);
}
catch (PlivoRestException e)
{
Console.WriteLine("Exception: " + e.Message);
}
}
}
}
Was this code helpful
1
2
curl -X DELETE "https://api.plivo.com/v1/Account/{Auth ID}/Masking/Session/{session_uuid}" \
-H "Content-Type: application/json" \
Was this code helpful
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
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.DeleteMaskingSession("SessionUUID")
if err != nil {
fmt.Print("Error", err.Error())
return
}
fmt.Printf("Response: %#v\n", response)
}
Was this code helpful
{
"api_id": "69f64f62-80f6-494f-b0c0-1f9dfa29ad05",
"message": "Session expired"
}
Configure the “callback_url” with your web server URL to receive important session events and status updates. Plivo passes these events to the callback URL.
SessionFirstPartyAnswer |
Triggered when the first party answers the call. |
SessionSecondPartyRing |
Triggered when the second party’s phone starts ringing. |
SessionSecondPartyAnswer |
Triggered when the second party answers the call. |
SessionSecondPartyHangup |
Triggered when the Second party disconnects the call. |
SessionFirstPartyHangup |
Triggered when the First party disconnects the call. |
SessionPinAuthenticationStatus |
Triggered when the PIN authentication status is success, failed or if the call is from an authorised caller. |
SessionTimeout |
Triggered when the session expires. |
SessionVirtualNumberReplaced |
This attribute is triggered when the health of the number utilized in the session is sub-optimal. Plivo will replace the sub-optimal number with a temporary, fully functional one to sustain the session and prevent call connectivity issues. The VirtualNumber field transmitted with this event contains the fully operational number. This event is a notification for you to update the older number with the new virtual number in your application. |
For each event, the below attributes will be posted to your web server.
EventName (string) |
Event that triggered this callback. This parameter will have one of the values from the list of events above. |
EventTimestamp (string) |
Timestamp in UTC at which the event occurred. |
SessionUUID (string) |
Timestamp in UTC at which the event occurred. |
SessionUUID (string) |
Unique ID of the masking session for which callback is sent. |
From (string) |
Actual from number used to interact with the virtual number |
To (string) |
Actual to number dialing out from the virtual number. |
PinAuthenticationStatus (string) |
Status of the PIN authentication during the interaction. |
PinRetryCounter (integer) |
Indicates the pin retry counter on account of incorrect Pin input. |
VirtualNumber (string) |
The virtual number used in the session. |
Amount (string) |
Total amount incurred for the call. |
BilledDuration (string) |
Duration in seconds for which the call was billed. |
Duration (string) |
Actual duration of the call in seconds. |
PlivoHangupCause (string) |
Reason for the call termination. |
PlivoHangupCauseCode (integer) |
A unique integer code for the termination cause. |
SequenceNumber (string) |
Indicates the sequence of the callback. Helpful to sort the callback events posted to the recording_callback_url.
|
1
2
3
4
5
import plivo
client = plivo.RestClient(auth_id='<auth_id>', auth_token='<auth_token>')
response = client.masking_sessions.delete_masking_session("session_uuid")
print(response)
Was this code helpful
1
2
3
4
5
6
7
8
9
10
11
12
13
14
require 'rubygems'
require "/root/plivo-ruby/lib/plivo.rb"
include Plivo
include Plivo::Exceptions
api = RestClient.new("<auth_id>", "<auth_token>")
begin
response = api.maskingsession.delete("<session_uuid>")
puts response
rescue PlivoRESTError => e
puts 'Exception: ' + e.message
end
Was this code helpful
1
2
3
4
5
6
7
8
9
10
11
12
13
var plivo = require('plivo');
(function main() {
'use strict';
var client = new plivo.Client("<auth_id>", "<auth_token>");
client.maskingSession.deleteMaskingSession("SessionUUID"
).then(function (response) {
console.log(response);
}, function (err) {
console.error(err);
});
})();
Was this code helpful
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<?php
/**
* Example for Delete Session
*/
require 'vendor/autoload.php';
use Plivo\RestClient;
use Plivo\Exceptions\PlivoRestException;
$client = new RestClient("<auth_id>", "<auth_token>");
try {
$response = $client->maskingSessions->deleteMaskingSession(
'SessionUUID'
);
print_r($response);
}
catch (PlivoRestException $ex) {
print_r($ex);
}
Was this code helpful
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
package com.plivo.examples;
import com.plivo.api.Plivo;
import com.plivo.api.exceptions.PlivoRestException;
import com.plivo.api.exceptions.PlivoValidationException;
import com.plivo.api.models.maskingsession.MaskingSession;
import java.io.IOException;
class DeleteSession {
public static void main(String [] args) {
Plivo.init("<auth_id>","<auth_token>");
try {
MaskingSession.deleter("<session_uuid>").delete();
} catch (PlivoRestException | IOException e) {
System.out.println(e);
e.printStackTrace();
} catch (PlivoValidationException e) {
throw new RuntimeException(e);
}
}
}
Was this code helpful
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
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.Delete(sessionUuid: "<session_uuid>");
Console.WriteLine(response);
}
catch (PlivoRestException e)
{
Console.WriteLine("Exception: " + e.Message);
}
}
}
}
Was this code helpful
1
2
curl -X DELETE "https://api.plivo.com/v1/Account/{Auth ID}/Masking/Session/{session_uuid}" \
-H "Content-Type: application/json" \
Was this code helpful
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
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.DeleteMaskingSession("SessionUUID")
if err != nil {
fmt.Print("Error", err.Error())
return
}
fmt.Printf("Response: %#v\n", response)
}
Was this code helpful
Configure the “recording callback URL” to receive recording-related callback events
SessionRecordingInitiated |
Triggered when the first party and the second party are connected via the virtual phone number and the recording begins. |
SessionRecordingCompleted |
Triggered when one of the parties disconnects the call. |
SessionRecordingFailed |
Triggered when the record attribute is set to true for a masking session but the recording could not be started. |
For each event, the below attributes will be posted to your web server.
EventName (string) |
Event that triggered this callback. This parameter will have one of the values from the list of events above. |
EventTimestamp (string) |
Timestamp at which the event occurred. |
From (string) |
Actual from number used to interact with the virtual number. |
RecordingDuration (string) |
Duration of recording in seconds. |
RecordingEndTime (string) |
UTC Timestamp at which the recording ended. |
RecordingFormat (string) |
Format of the recording. |
RecordingResourceURL (string) |
Complete URL path to the recording resource URL. |
RecordingStartTime (string) |
UTC Timestamp at which the recording started. |
RecordingURL (string) |
Actual media URL path of the recording. |
RecordingUUID (string) |
Unique identifier of the recording file. |
SequenceNumber (string) |
Indicates the sequence of the callback. It’s helpful to sort the callback events posted to the recording_callback_url. |
SessionUUID (string) |
Unique ID of the masking session. |
To (string) |
Actual to number dialing out from the virtual number. |
VirtualNumber (string) |
The virtual number used in the session. |
1
2
3
4
5
import plivo
client = plivo.RestClient(auth_id='<auth_id>', auth_token='<auth_token>')
response = client.masking_sessions.delete_masking_session("session_uuid")
print(response)
Was this code helpful
1
2
3
4
5
6
7
8
9
10
11
12
13
14
require 'rubygems'
require "/root/plivo-ruby/lib/plivo.rb"
include Plivo
include Plivo::Exceptions
api = RestClient.new("<auth_id>", "<auth_token>")
begin
response = api.maskingsession.delete("<session_uuid>")
puts response
rescue PlivoRESTError => e
puts 'Exception: ' + e.message
end
Was this code helpful
1
2
3
4
5
6
7
8
9
10
11
12
13
var plivo = require('plivo');
(function main() {
'use strict';
var client = new plivo.Client("<auth_id>", "<auth_token>");
client.maskingSession.deleteMaskingSession("SessionUUID"
).then(function (response) {
console.log(response);
}, function (err) {
console.error(err);
});
})();
Was this code helpful
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<?php
/**
* Example for Delete Session
*/
require 'vendor/autoload.php';
use Plivo\RestClient;
use Plivo\Exceptions\PlivoRestException;
$client = new RestClient("<auth_id>", "<auth_token>");
try {
$response = $client->maskingSessions->deleteMaskingSession(
'SessionUUID'
);
print_r($response);
}
catch (PlivoRestException $ex) {
print_r($ex);
}
Was this code helpful
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
package com.plivo.examples;
import com.plivo.api.Plivo;
import com.plivo.api.exceptions.PlivoRestException;
import com.plivo.api.exceptions.PlivoValidationException;
import com.plivo.api.models.maskingsession.MaskingSession;
import java.io.IOException;
class DeleteSession {
public static void main(String [] args) {
Plivo.init("<auth_id>","<auth_token>");
try {
MaskingSession.deleter("<session_uuid>").delete();
} catch (PlivoRestException | IOException e) {
System.out.println(e);
e.printStackTrace();
} catch (PlivoValidationException e) {
throw new RuntimeException(e);
}
}
}
Was this code helpful
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
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.Delete(sessionUuid: "<session_uuid>");
Console.WriteLine(response);
}
catch (PlivoRestException e)
{
Console.WriteLine("Exception: " + e.Message);
}
}
}
}
Was this code helpful
1
2
curl -X DELETE "https://api.plivo.com/v1/Account/{Auth ID}/Masking/Session/{session_uuid}" \
-H "Content-Type: application/json" \
Was this code helpful
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
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.DeleteMaskingSession("SessionUUID")
if err != nil {
fmt.Print("Error", err.Error())
return
}
fmt.Printf("Response: %#v\n", response)
}
Was this code helpful