Latest Legacy

Update a number masking session

The following resource allows you to update the session.

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

Attributes

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

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 will 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.

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.

Note: The below parameters cannot be updated for the active session
  • first_party
  • Second_party
  • initiate_call_to_first_party
  • is_pin_authentication_required
  • pin_prompt_play
  • pin_retry
  • pin_retry_wait
  • incorrect_pin_play
  • Unknown_caller_play
  • geomatch
  • subaccount

Response

{
  "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": ""
  }
}

Example Request

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)
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
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);
    });
})();
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);
}
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);
    }
  }
}
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);
            }
        }
    }
}
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",
  }'
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)
}