Skip to main content

Documentation Index

Fetch the complete documentation index at: https://plivo.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

The <Record> element records audio from the call and returns the URL of the recording file. Use it for voicemail, call logging, or quality monitoring.

​
Basic Usage

<Response>
    <Speak>Please leave a message after the beep.</Speak>
    <Record action="https://example.com/handle-recording/" />
</Response>

from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(plivoxml.SpeakElement('Please leave a message after the beep.'))
response.add(plivoxml.RecordElement(action='https://example.com/handle-recording/'))
print(response.to_string())

​
Attributes

​
Basic Settings

AttributeTypeDefaultDescription
actionURL-URL to receive recording data
methodstringPOSTHTTP method for action (GET, POST)
fileFormatstringmp3Recording format (mp3, wav)
redirectbooleantrueRedirect to action URL when complete

​
Timing

AttributeTypeDefaultDescription
timeoutinteger15Seconds of silence before stopping
maxLengthinteger60Maximum recording duration in seconds
finishOnKeystring#Key to stop recording (digit, #, *, or none)
playBeepbooleantruePlay beep before recording

​
Session Recording

AttributeTypeDefaultDescription
recordSessionbooleanfalseRecord entire call in background
startOnDialAnswerbooleanfalseStart recording when B-leg answers
recordChannelTypestringstereoChannel type (mono, stereo)

​
Transcription

AttributeTypeDefaultDescription
transcriptionTypestring-Transcription type. Values: auto, hybrid, manual
transcriptionUrlURL-URL to receive transcription
transcriptionMethodstringPOSTHTTP method for sending transcription results to transcriptionUrl. Values: GET, POST
transcriptionReportTypestringcompactFormat of the transcription report. Values: full, compact

​
Callbacks

AttributeTypeDefaultDescription
callbackUrlURL-URL notified when recording is ready
callbackMethodstringPOSTHTTP method for callback

​
Voicemail

<Response>
    <Speak>
        You've reached John's voicemail.
        Leave a message after the beep, press pound when finished.
    </Speak>
    <Record
        action="https://example.com/save-voicemail/"
        maxLength="120"
        finishOnKey="#"
        playBeep="true"
    />
    <Speak>Thank you for your message. Goodbye.</Speak>
</Response>

from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(plivoxml.SpeakElement(
    "You've reached John's voicemail. Leave a message after the beep."
))
response.add(plivoxml.RecordElement(
    action='https://example.com/save-voicemail/',
    max_length=120,
    finish_on_key='#',
    play_beep=True
))
response.add(plivoxml.SpeakElement('Thank you for your message. Goodbye.'))
print(response.to_string())

​
Record Entire Session

Record the complete call in the background: 
<Response>
    <Record recordSession="true"
            callbackUrl="https://example.com/recording-ready/" />
    <Speak>This call is being recorded for quality purposes.</Speak>
    <Dial>
        <Number>+14155551234</Number>
    </Dial>
</Response>
Notes:
  • Recording starts immediately and continues until the call ends
  • timeout, finishOnKey, and playBeep are ignored
  • Recording is sent to callbackUrl when complete

​
Record Dial Conversation

Record both parties after the dial connects: 
<Response>
    <Record startOnDialAnswer="true"
            callbackUrl="https://example.com/recording-ready/" />
    <Dial>
        <Number>+14155551234</Number>
    </Dial>
</Response>

​
Stereo vs Mono Recording

Stereo (default): Each party on separate audio channels - useful for call analytics. Mono: Both parties on single channel - smaller file size. 
<Record recordSession="true" recordChannelType="mono" />

​
With Transcription

Get automatic speech-to-text: 
<Response>
    <Speak>Please leave your message.</Speak>
    <Record
        action="https://example.com/handle-recording/"
        transcriptionType="auto"
        transcriptionUrl="https://example.com/transcription/"
    />
</Response>
Transcription limits:
  • English only
  • Duration: 500ms to 4 hours
  • File size: under 2GB

​
Action URL Parameters

Sent when recording completes:
ParameterDescription
RecordUrlURL of the recording file
RecordingIDUnique recording identifier
RecordingDurationDuration in seconds
RecordingDurationMsDuration in milliseconds
RecordingStartMsStart time (epoch ms)
RecordingEndMsEnd time (epoch ms)
DigitsKey pressed to stop (if any)
Note: When recordSession or startOnDialAnswer is true, duration values are -1 in the initial request. Final values are sent to callbackUrl.

​
Callback URL Parameters

Sent when recording file is ready:
ParameterDescription
RecordUrlURL of the recording file
RecordingIDRecording identifier
RecordingDurationDuration in seconds
RecordingDurationMsDuration in milliseconds
RecordingStartMsStart time (epoch ms)
RecordingEndMsEnd time (epoch ms)

​
Transcription URL Parameters

ParameterDescription
transcriptionTranscribed text
transcription_chargeCost of transcription
transcription_rateRate per minute
durationRecording duration
call_uuidCall identifier
recording_idRecording identifier
errorError message (if failed)

​
Best Practices

  1. Inform callers - Always notify that the call is being recorded (legal requirement in many jurisdictions)
  2. Set appropriate limits - Use maxLength to prevent very long recordings
  3. Use callbacks - Use callbackUrl for reliable notification when recording is ready
  4. Choose format wisely - MP3 for smaller files, WAV for highest quality
  5. Handle storage - Download recordings from Plivo; they’re deleted after 30 days