By using the Aculab site, you agree with our use of cookies.
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.

language wrappers and examples

The record properties are:

PropertyRequired/OptionalDefaultDescription
next pagerequiredA web page request object that defines the web page to be called once the recording has finished. It is passed the filename and details of the recording, which will be immediately available to play within the same application, but may not yet be available for general access.
id
from API V2.0
optional""A user-defined string that can be used to uniquely identify each recording.
barge in digitsoptional"#"A string of zero or more digits. This stops the record action if any of these digits are pressed.
seconds max durationoptional60An integer value. The maximum duration of the recording.
milliseconds max silenceoptional3000An integer value. The amount of silence in milliseconds after which the recording stops.
milliseconds max initial silence
from API V2.0
optional0An integer value. The maximum amount of time in milliseconds to listen for the first audio input. The recording starts when the first audio input is heard. Setting this to 0 (the default) indicates that the value of milliseconds_max_silence will be used to listen for the first audio input.
formatoptionaldetermined automaticallyOne of "alaw" or "ulaw". The companding used to encode the audio data in the file.
encryption cipheroptional-A cipher object to be used to encrypt the recorded file. If none is supplied the recorded file is saved unencrypted.
beep on startoptionalfalsetrue or false. Whether to play a beep before starting to record.
recording available page
from API V2.0
optional-A web page request object that defines a web page that is notified once the recorded file is fully available to all applications and can be downloaded. The request to this page happens asynchronously and is not restricted to the lifetime of the application that made the recording. Its response is not considered part of the application flow.

Returns to next page

As soon as recording is completed the recorded file can be played or deleted by the same application (see Recording Available Notification for wider availability). The name of the recorded file is generated automatically and returned to the application via the subsequent HTTP Request to the next page in the action result along with details of the recording as follows:

PropertyAvailabilityDescription
filenamealwaysA string representing the filename of the recording on the Aculab media file store.
file available
from API V2.0
alwaystrue or false. Indicates whether the recorded file is available from the Aculab media file store outside of this application.
id
from API V2.0
alwaysThe user-defined id specified in the action.
contains soundalwaystrue or false. Indicates whether the recorded file contains sound above the general background level of noise.
seconds durationalwaysA floating point value to one decimal place. The estimated duration of the file in seconds.
reason
from API V2.0
alwaysA string indicating the reason the recording completed. One of 'duration', 'bargein', 'aborted', 'filesize', 'silence', 'error', 'other', 'hangup'. Available in REST API Version 2 and later.
barge in digit
from API V2.0
if reason is 'bargein'A string containing the single digit that was pressed to barge in. Available in REST API Version 2 and later.

Recording Available Notifications

The recorded file can be accessed by the same application once next page has been called. However, more general access may not be available for several seconds (see Media File Availability).
When the file is available for general access, the page supplied in recording available page will be requested, which can use the Managing Files Web Services API to download it. An action result is included which is exactly the same as that in the next page request above, but with the file available property set to true.

 Note that requests to this page are for notification only and should respond with a 204 response code indicating no content.

 See also: Simple Record, Voicemail

  • Examples:

    • 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 to next page once 3 seconds of silence is detected during the recording:

      "action_result" :
      {
          "action" : "record",
          "result" : 
          {  
      		"id": "",
      		"filename" : "/rest_api/recordings/2018/06/16/14_35_03_04f01fb92e8913a8.62100.wav",
      		"file_available" : false,
      		"contains_sound" : true,
      		"seconds_duration" : 16.7,
      		"reason" : "silence"
          }
      }