right  Talk To Us!

record Action

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:

PropertyRequired/OptionalDefaultDescription
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:

PropertyRequired/OptionalDefaultDescription
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:

PropertyRequired/OptionalDescription
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:

PropertyRequired/OptionalDescription
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:

PropertyDescription
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.
  • Examples:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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();