Tropo is part of CiscoLearn More

startCallRecording

startCallRecording allows Tropo applications to begin recording the current call. The resulting recording may then be sent via FTP, an HTTP POST/Multipart Form, or to an Amazon S3 bucket. To stop the recording, see stopCallRecording.

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.

Parameters

recordURL

Array

Accepts an array with the following keys:

  • 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 up to three URLs to upload to, and Tropo will attempt them in order until uploading succeeds to one of them. 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 succeeeding. If your application needs to play back the audio immediately after recording is completed, the object returned by the record method has a "value" property that contains a url of a temporary local copy of the file. This temporary copy will be deleted as soon as the call ends.

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, or if you want to record audio for playback in the same application without needing to store a copy of it.

Map Parameters

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

The format to record in. This can be either 'audio/wav', 'audio/mp3' or 'audio/au'.

transcriptionOutURI

String

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.

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

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

Examples

  startCallRecording({url: "http://example.com/recording.js"});
ask("What's your favorite color?  Choose from red, blue or green.", {
  choices:"red, blue, green"
});
stopCallRecording();  
startCallRecording {:url => "http://example.com/recording"}
ask "What's your favorite color?  Choose from red, blue or green.", {
   :choices => "red, blue, green",
   :attempts => 3}
stopCallRecording
<?php
 
startCallRecording(array("url" => "http://example.com/recording.php"));
ask("What's your favorite color?  Choose from red, blue or green.", array(
    "choices" =>"red, blue, green",
    "attempts" => 3
));
stopCallRecording();
 
?>
startCallRecording({"url":"http://example.com/recording"});
ask("What's your favorite color?  Choose from red, blue or green.", {
  "choices":"red, blue, green",
  "attempts":3
});
stopCallRecording();
startCallRecording([url: "http://example.com/recording"]);
ask("What's your favorite color?  Choose from red, blue or green.", [
  choices:"red, blue, green",
  attempts:3
]);
stopCallRecording();