Tropo is part of CiscoLearn More

startRecording

Allows Tropo applications to begin recording the current session. The resulting recording may then be sent via FTP or an HTTP POST/Multipart Form.

The audio file can also be transcribed and the text returned to you via an email address or HTTP POST/Multipart Form - currently, transcription only supports US English.

Note
Transcription is not available in the tropo.eu environment. See API Differences for details.

Tips and Tricks

  • Recording files are 16 bit, 8KHz files, regardless of the audio type
  • If you record a conference or a transfer, you'll get a stereo recording. One channel contains the caller, the other contains the conference or transferred party.
  • Transcription results will be better if you use WAV as your audio type. The higher-quality audio gives more for the transcription engine to work with.

Fields

asyncUpload

Boolean
Default: 
false

Setting to true will instruct Tropo to upload the recording file in the background as soon as the recording is completed.

If this is set to false (the default behavior), Tropo will wait until the file is uploaded before returning or running the onRecord callback.

format

String
Default: 
audio/wav

This specifies the format for the audio recording; it can be 'audio/wav', 'audio/mp3' or 'audio/au'.

recordingURL

Array or Object

Accepts an object with the following keys, or an array of these objects:

  • url: The URL that Tropo should send the recording to. This should be a full HTTP or HTTPS URL. If your URL includes a file extension, and the recording format parameter is not set, the extension will be used to guess your desired format. Files ending in .wav will be recorded using the format 'audio/wav', .mp3 as 'audio/mp3', and .au as 'audio/au'.
  • username: The username that should be transmitted along with your request. For S3 uploads, this is your S3 Access Key ID.
  • password: The passwor that should be transmitted along with your request. For S3 uploads, this is your S3 Access Key Secret.
  • method: The HTTP Method (PUT or POST) that Tropo should send the file as. POST is the default. When sending via POST, the file is delivered as if you had an HTML form with an upload field named "filename". If the upload is an S3 upload, this is ignored.

Tropo will examine your URL to determine if it is an S3 bucket - there's no need to tell Tropo you're uploading to S3.

You can specify an array of objects and Tropo will attempt each one in order until uploading succeeds to one of them, with a maximum of three attempts. There is no retry mechanism; once Tropo fails to upload to one of your URLs, it will skip to the next one, and continue that until either the recording is uploaded or Tropo has tried all of the URLs you gave. If you give more than three URLs, Tropo will only try the first three.

The file will take a few moments to upload to your server. The exact amount of time depends on many factors, including the network connection of your server and how many of your failover URLs we need to attempt before succeeding.

This parameter is not required, but if you do not include it, Tropo will not send your recording anywhere. This can be useful if you wish to transcribe something, but don't need the audio file.

transcriptionOutURI

String
Default: 
none

Setting this to anything enables transcription on this recording. The e-mail address or HTTP URL to send the transcription results to; the transcription arrives as the content of the HTTP POST, as opposed to a header, named field or variable, and is not sent as form data.

Email addresses must be prefaced with mailto: if used (mailto:you@example.com)

Transcription is a paid feature and is not included in the per-minute rate for phone calls. Transcription is billed for each minute of transcribed recording. See Tropo Pricing for current rates.

Note
Transcription is not available in the tropo.eu environment. See API Differences for details.

transcriptionEmailFormat

String
Default: 
plain

Specifies the encoding used when delivering transcriptions via e-mail. Values can be "plain" or "encoded".

transcriptionID

String
Default: 
none

User definable ID that can be included when the transcription is posted to transcriptionOutURI.

Examples

Example with stopRecording

{
   "tropo":[
      {
         "startRecording":{
            "name":"myrecording",
            "recordURL" : {"url":"http://example.com/recording"},
         }
      },
      {
         "say":[
            {
               "value":"I am now recording!"
            }
         ]
      },
      {
         "stopRecording":null
      }
   ]
}