Record

Records audio from the call to a wav file in the Aculab media file store. The recording can be encrypted by supplying an encryption cipher property when setting up the record action. Recorded files are available immediately to play in the same application, but generally take a few seconds to become available elsewhere. See Media File Availability for more details.

The record properties are:

Property	Required/Optional	Default	Description
beep on start	optional	false	true or false. Whether to play a beep before starting to record.
barge in digits	optional	"#"	A string of zero or more digits. This stops the record action if any of these digits are pressed.
seconds max duration	optional	60	An integer value. The maximum duration of the recording.
milliseconds max silence	optional	3000	An integer value. The maximum period of silence allowed in the recording. If this is encountered the recording is stopped.
format	optional	determined automatically	One of "alaw" or "ulaw". The companding used to encode the audio data in the file.
next page	optional	null	A web page request object that defines the web page to be requested once the recording has finished. If null or no page is specified then the subsequent action in the action array will be executed.
encryption cipher	optional	null	The cipher object to be used to encrypt the recorded file.

web page request defines how a specific web page is requested:

Property	Required/Optional	Default	Description
url	required	-	The address of the web page to request.
method	optional	GET	Only "GET" is supported when uploading a file. The HTTP request method to use when requesting the url.

encryption cipher contains the details of a cipher used to encrypt media files:

Property	Required/Optional	Description
type	required	The cipher type, currently only "aescbc" (AES algorithm, CBC mode) is supported.

For the aescbc cipher the following properties must be supplied in the cipher object:

Property	Required/Optional	Description
key	required	The cipher key as a string, either 128, 192 or 256 bits represented as 16, 24 or 32 hexadecimal bytes.
initialisation vector	required	The initialisation vector as a string, 128 bits represented as 16 hexadecimal bytes.

Returns

The name of the recorded file is generated automatically and returned to the application via the subsequent http request to the next page in action result along with details of the recording as follows:

Property	Description
filename	A string representing the filename of the recording on the Aculab media file store.
contains sound	true or false. Indicates whether the recorded file contains sound above the general background level of noise.
seconds duration	A floating point value to one decimal place. The estimated duration of the file in seconds.

See also:

Simple Record, Voicemail

JSONC#VBJavaPythonPHP

Examples:

Example 1Example 2Example 3Example 4

Record a call's incoming audio using the defaults:

"record" : 
{
}

Note that by default there is no next page defined, so no action result is returned.

Record a call's incoming audio and specify a page to receive the recorded file name:

"record" :
{
    "next_page" : 
    {
        "url" : "my_record_handler_page"
    }
}

The following may be returned:

"action_result" :
{
    "action" : "record",
    "result" : 
    {  
        "filename" : "/rest_api/recordings/2013/07/16/14_35_03_04f01fb92e8913a8.62100.wav",
        "contains_sound" : true,
        "seconds_duration" : 16.7
    }
}

Record a call's incoming audio to an encrypted media file and specify a page to receive the recorded file name. Specify the cipher to encrypt the recording:

"record" :
{
    "next_page" : 
    {
        "url" : "my_record_handler_page"
    },
    "encryption_cipher": 
    {
        "type" : "aescbc",
        "key" : "431F43FAF57534C91F2DEB2E502A4C8CBA58AB5018BD1506419EEA86DF595D3A",
        "initialisation_vector" : "F846443B9B85FAED9AB17570D5A82A31"
    }
}

The following may be returned:

"action_result" :
{
    "action" : "record",
    "result" : 
    {  
        "filename" : "/rest_api/recordings/2013/07/16/14_35_03_04f01fb92e8913a8.62100.wav",
        "contains_sound" : true,
        "seconds_duration" : 16.7
    }
}

Record a call's incoming audio for up to 3 minutes, enabling barge in for '#' and '*', stopping the record on 5 seconds of silence:

"record" :
{
    "beep_on_start" : false,
    "barge_in_digits" : "#*",
    "seconds_max_duration : 180,
    "milliseconds_max_silence" : 5000,
    "format" : "alaw",
    "next_page" : 
    {
        "url" : "my_record_handler_page"
    }
}

The following may be returned:

"action_result" :
{
    "action" : "record",
    "result" : 
    {  
        "filename" : "/rest_api/recordings/2013/07/16/14_35_03_04f01fb92e8913a8.62100.wav",
        "contains_sound" : true,
        "seconds_duration" : 32.9
    }
}

API Reference:

class Record : TelephonyAction

Represents a record action.

Constructors:

Record();
Record(WebPageRequest nextPage);

Members:

bool BeepOnStart;
String BargeInDigits;
int SecondsMaxDuration;
int MillisecondsMaxSilence;
String Format;
Cipher EncryptionCipher;
WebPageRequest NextPage;

class WebPageRequest

Represents a request to a web page.

Constructors:

WebPageRequest(String url);
WebPageRequest(String url, String method);

Members:

String Method;

class Cipher

Represents a cipher to be used for file encryption/decryption.

Members:

String Type;

class AesCbcCipher : Cipher

Represents the AES cipher in CBC mode.

Constructors:

AesCbcCipher(byte[] key, byte[] initialisationVector);

Members:

byte[] InitialisationVector;

class RecordResult : ActionResult

Represents the result of a record action.

Members:

String Filename;
bool ContainsSound;
double SecondsDuration;

Examples:

Example 1Example 2Example 3Example 4

Record a call's incoming audio using the default parameters:

actions.Add(new Record());

Record a call's incoming audio and specify a page to receive the recorded file name:

actions.Add(new Record(new WebPageRequest("MyRecordHandlerPage.aspx")));

Record a call's incoming audio to an encrypted media file and specify a page to receive the recorded file name. Specify the cipher to encrypt the recording:

// Specify a 256 bit cipher to be used to encrypt the recording
byte[] key = new byte[] {
  0x43, 0x1F, 0x43, 0xFA, 0xF5, 0x75, 0x34, 0xC9,
  0x1F, 0x2D, 0xEB, 0x2E, 0x50, 0x2A, 0x4C, 0x8C,
  0xBA, 0x58, 0xAB, 0x50, 0x18, 0xBD, 0x15, 0x06,
  0x41, 0x9E, 0xEA, 0x86, 0xDF, 0x59, 0x5D, 0x3A };

byte[] initialisationVector = new byte[] {
  0xF8, 0x46, 0x44, 0x3B, 0x9B, 0x85, 0xFA, 0xED,
  0x9A, 0xB1, 0x75, 0x70, 0xD5, 0xA8, 0x2A, 0x31 };

Cipher encryptionCipher = new AesCbcCipher(key, initialisationVector);

Record recordAction = new Record(new WebPageRequest("MyRecordHandlerPage.aspx"));
recordAction.EncryptionCipher = encryptionCipher;

actions.Add(recordAction);

Record a call's incoming audio for up to 3 minutes, enabling barge in for '#' and '*', with no beep and stopping the record on 5 seconds of silence:

Record recordAction = new Record(new WebPageRequest("MyRecordHandlerPage.aspx"));
recordAction.BargeInDigits = "#*";
recordAction.SecondsMaxDuration = 180;
recordAction.MillisecondsMaxSilence = 5000;
actions.Add(recordAction);

The record result is obtained from the request for the next page:

RecordResult recordResult = (RecordResult)ourRequest.InstanceInfo.ActionResult;
String recordedFilename = recordResult.Filename;
if (recordResult.ContainsSound)
{
...

API Reference:

Class Record Inherits TelephonyAction

Represents a record action.

Constructors:

New()
New(nextPage As RestAPIWrapper.WebPageRequest)

Members:

BeepOnStart As Boolean
BargeInDigits As String
SecondsMaxDuration As Integer
MillisecondsMaxSilence As Integer
Format As String
EncryptionCipher As Cipher
NextPage As RestAPIWrapper.WebPageRequest

Class WebPageRequest

Represents a request to a web page.

Constructors:

New(url As String)
New(url As String, method As String)

Members:

Method As String

class Cipher

Represents a cipher to be used for file encryption/decryption.

Members:

  Type As String

class AesCbcCipher : Cipher

Represents the AES cipher in CBC mode.

Constructors:

  AesCbcCipher(ByVal key As Byte(), ByVal initialisationVector As Byte())

Members:

  InitialisationVector As Byte()

Class RecordResult Inherits RestAPIWrapper.ActionResult

Represents the result of a record action.

Members:

Filename As String
ContainsSound As Boolean
SecondsDuration As Double

Examples:

Example 1Example 2Example 3Example 4

Record a call's incoming audio using the default parameters:

actions.Add(New Record())

Record a call's incoming audio and specify a page to receive the recorded file name:

actions.Add(New Record(New WebPageRequest("MyRecordHandlerPage.aspx")))

Record a call's incoming audio to an encrypted media file and specify a page to receive the recorded file name. Specify the cipher to encrypt the recording:

' Specify a 256 bit cipher to be used to encrypt the recording
Dim key As Byte() = {
  &H43, &H1F, &H43, &HFA, &HF5, &H75, &H34, &HC9,
  &H1F, &H2D, &HEB, &H2E, &H50, &H2A, &H4C, &H8C,
  &HBA, &H58, &HAB, &H50, &H18, &HBD, &H15, &H06,
  &H41, &H9E, &HEA, &H86, &HDF, &H59, &H5D, &H3A }

Dim initialisationVector As Byte() = {
  &HF8, &H46, &H44, &H3B, &H9B, &H85, &HFA, &HED,
  &H9A, &HB1, &H75, &H70, &HD5, &HA8, &H2A, &H31 }

Cipher encryptionCipher = New AesCbcCipher(key, initialisationVector)

Record recordAction = New Record(New WebPageRequest("MyRecordHandlerPage.aspx"))
recordAction.EncryptionCipher = encryptionCipher

actions.Add(recordAction)

Record a call's incoming audio for up to 3 minutes, enabling barge in for '#' and '*', with no beep and stopping the record on 5 seconds of silence:

Dim recordAction As Record = New Record(New WebPageRequest("MyRecordHandlerPage.aspx"))
recordAction.BargeInDigits = "#*"
recordAction.SecondsMaxDuration = 180
recordAction.MillisecondsMaxSilence = 5000
actions.Add(recordAction)

The record result is obtained from the request for the next page:

Dim recordResult As RecordResult = ourRequest.InstanceInfo.ActionResult
Dim recordedFilename As String = recordResult.Filename
if recordResult.ContainsSound Then
...

API Reference:

class Record extends TelephonyAction

Represents a record action.

Constructors:

Record();
Record(WebPageRequest nextPage);

Members:

setBeepOnStart(boolean enabled);
setBargeInDigits(String digits);
setSecondsMaxDuration(int seconds);
setMillisecondsMaxSilence(int milliseconds);
setFormat(String format);
setEncryptionCipher(Cipher encryptionCipher);
setNextPage(WebPageRequest nextPage);

class WebPageRequest

Represents a request to a web page.

Constructors:

WebPageRequest(String url);
WebPageRequest(String url, String method);

Members:

setMethod(String method);

class Cipher

Represents a cipher to be used for file encryption/decryption.

Members:

String getType();

class AesCbcCipher extends Cipher

Represents the AES cipher in CBC mode.

Constructors:

AesCbcCipher(byte[] key, byte[] initialisationVector);

Members:

byte[] getInitialisationVector();
setInitialisationVector(byte[] iv);

class RecordResult extends ActionResult

Represents the result of a record action.

Members:

String getFilename();
boolean containsSound();
double getSecondsDuration();

Examples:

Example 1Example 2Example 3Example 4

Record a call's incoming audio using the default parameters:

actions.add(new Record());

Record a call's incoming audio and specify a page to receive the recorded file name:

actions.add(new Record(new WebPageRequest("myRecordHandlerPage")));

Record a call's incoming audio to an encrypted media file and specify a page to receive the recorded file name. Specify the cipher to encrypt the recording:

// Specify a 256 bit cipher to be used to encrypt the recording
byte[] key = new byte[] {
  0x43, 0x1F, 0x43, 0xFA, 0xF5, 0x75, 0x34, 0xC9,
  0x1F, 0x2D, 0xEB, 0x2E, 0x50, 0x2A, 0x4C, 0x8C,
  0xBA, 0x58, 0xAB, 0x50, 0x18, 0xBD, 0x15, 0x06,
  0x41, 0x9E, 0xEA, 0x86, 0xDF, 0x59, 0x5D, 0x3A };

byte[] initialisationVector = new byte[] {
  0xF8, 0x46, 0x44, 0x3B, 0x9B, 0x85, 0xFA, 0xED,
  0x9A, 0xB1, 0x75, 0x70, 0xD5, 0xA8, 0x2A, 0x31 };

Cipher encryptionCipher = new AesCbcCipher(key, initialisationVector);

Record recordAction = new Record(new WebPageRequest("myRecordHandlerPage"));
recordAction.setEncryptionCipher(encryptionCipher);

actions.add(recordAction);

Record a call's incoming audio for up to 3 minutes, enabling barge in for '#' and '*', with no beep and stopping the record on 5 seconds of silence:

Record recordAction = new Record(new WebPageRequest("myRecordHandlerPage"));
recordAction.setBargeInDigits("#*");
recordAction.setSecondsMaxDuration(180);
recordAction.setMillisecondsMaxSilence(5000);
actions.add(recordAction);

The record result is obtained from the request for the next page:

public void doGet(HttpServletRequest request, HttpServletResponse response) 
{
  TelephonyRequest ourRequest = new TelephonyRequest(request);
  RecordResult recordResult = (RecordResult)ourRequest.getInstanceInfo().getActionResult();
  String recordedFilename = recordResult.getFilename();
  if (recordResult.containsSound())
  {
    ...
}

API Reference:

class Record

Represents a record action.

Constructors:

Record(format=None,
       seconds_max_duration=None,
       beep_on_start=None,
       barge_in_digits=None,
       milliseconds_max_silence=None,
       next_page=None,  # A WebPage object, see Redirect() for details
       encryption_cipher=None)

Members:

def set_format(format)
def set_encryption_cipher(encryption_cipher)
def set_seconds_max_duration(seconds_max_duration)
def set_beep_on_start(beep_on_start)
def set_barge_in_digits(barge_in_digits)
def set_milliseconds_max_silence(milliseconds_max_silence)
def set_next_page(next_page) # A WebPage object

Examples:

Example 1Example 2Example 3Example 4

Record a call using the default parameters:

from aculab.telephony_rest_api import Actions, Record

my_actions = Actions('Usage example 1: Record.')
my_actions.add(Record())

response_body = my_actions.get_json()

Record a call using the default parameters. Also provide a cipher to encrypt the recorded file:

from aculab.telephony_rest_api import Actions, Record, AESCBCCipher

my_actions = Actions('Usage example 2: Record.')

my_cipher = AESCBCCipher(key='407e4cc1a732cb2ac1b84395488f3322404e414ffeba8a8d692c034d608d9cc8', 
                         initialisation_vector='3bfd048ecaad5515f1ca7b9b58302c04')
my_actions.add(Record(encryption_cipher=my_cipher))

response_body = my_actions.get_json()

Record a call and specify a page to receive the recorded file name:

from aculab.telephony_rest_api import Actions, Record

my_actions = Actions('Usage example 3: Record.')
my_actions.add(Record(next_page=WebPage(url='my_record_handler_page')))

response_body = my_actions.get_json()

Record a call for up to 3 minutes, enabling bargein for '#' and '*', with no beep and stopping the record on 5 seconds of silence:

from aculab.telephony_rest_api import Actions, Record

my_actions = Actions('Usage example 4: Record.')

my_actions.add(Record(seconds_max_duration=180,
                      beep_on_start=False,
                      barge_in_digits="#*",
                      milliseconds_max_silence=5000, 
                      format='alaw',
                      next_page=WebPage(url='my_record_handler_page'),
                     ))

response_body = my_actions.get_json()

API Reference:

The Record class

Introduction

Represents a record action.

Class synopsis

class Record extends ActionBase {

    /* methods */
    public __construct($options = null)
    public void setFormat(string $format)
    public void setSecondsMaxDuration(int $secs)
    public void setBeepOnStart(boolean $beep)
    public void setBargeInDigits(string $digits)
    public void setMillisecondsMaxSilence(int $msecs)
    public void setNextPage(string $next_page, string $method = null)
    public void setEncryptionCipher(Cipher $cipher)
}

The RecordResult class

Introduction

Represents the result of a record action.

Class synopsis

class RecordResult extends ActionResult {

    /* Methods */
    public string getFilename()
    public boolean getContainsSound()
    public float getSecondsDuration()

    /* inherited methods */
    public string getAction()
    public boolean getInterrupted()
}

The Cipher class

Introduction

An abstract class to represent ciphers.

Class synopsis

abstract class Cipher {

    /* methods */
    public __construct(string $type)
}

The AesCbcCipher class

Introduction

A class to represent a cipher using AES in CBC mode.

Class synopsis

$key and $initialisation_vector are strings of hexadecimal bytes.

class AesCbcCipher extends Cipher{

    /* methods */
    public __construct(string $key, string $initialisation_vector)
}

Examples:

Example 1Example 2Example 3Example 4

Record a call's incoming audio using the defaults:

$actions->add(new Aculab\TelephonyRestAPI\Record());
// NOTE: the filename of the recording is not known to the app

Record a call's incoming audio and specify a page to receive the recorded file name:

$actions->add(new Aculab\TelephonyRestAPI\Record(array('next_page' => 'my_record_handler_page')));

Get the filename of the recording from the action's next page request:

$info = InstanceInfo::getInstanceInfo();
$recordResult = $info->getActionResult();
$recordFilename = $recordResult->getFilename();

Record a call's incoming audio to an encrypted media file and specify a page to receive the recorded file name. Specify the cipher to encrypt the recording:

$r = new Aculab\TelephonyRestAPI\Record();
$->setNextPage('my_record_handler_page');

$cipher = new Aculab\TelephonyRestAPI\AesCbcCipher(
    "431F43FAF57534C91F2DEB2E502A4C8CBA58AB5018BD1506419EEA86DF595D3A",
    "F846443B9B85FAED9AB17570D5A82A31"
);
$r->setEncryptionCipher($cipher);

$actions->add($r);

Get the filename of the recording from the action's next page request:

$info = InstanceInfo::getInstanceInfo();
$recordResult = $info->getActionResult();
$recordFilename = $recordResult->getFilename();

Record a call's incoming audio for up to 3 minutes, enabling barge in for '#' and '*', stopping the record on 5 seconds of silence:

$recopt = array(
    'seconds_max_duration' => 180,
    'beep_on_start' => false,
    'barge_in_digits' => '*#',
    'milliseconds_max_silence' => 5000
);
$recAction = new Aculab\TelephonyRestAPI\Record($recopt)
$recAction->setNextPage('my_record_handler_page');
$actions->add($recAction);

Get the filename of the recording from the action's next page request:

$info = InstanceInfo::getInstanceInfo();
$recordResult = $info->getActionResult();
$recordFilename = $recordResult->getFilename();