Skip to main content

How to Record Calls and Transcribe

In this guide we will show you how to record any inbound or outbound call and produce a transcription of these recordings. Please ensure you have followed our earlier guide on how to make an outbound call with Bandwidth.

Calls may be recorded or transcribed to enhance customer experience and training, for dispute resolution or for regulatory compliance reasons.

There are two ways you can record a call; with <Record> or with <StartRecording>. Please select the use case that best suits your needs.

Use <Record> if:

  • You're capturing a voicemail
  • You only need a single party recording
  • You're capturing input that should pause the call until finished

Use <StartRecording> if:

  • You want to record both ends (together or separate) of a phone call
  • You want to record a call for quality assurance
  • You need other BXML verbs to execute while a recording is going on

Recording a Call


The <Record> verb starts recording in a call and pauses all BXML execution until the recording is terminated by a timeout (maxDuration) or a terminating digit (terminatingDigits). Once the recording ends, BXML execution will continue at the next verb, or at the BXML at the recordCompleteUrl if this attribute is set.

If the recordingAvailableUrl attribute is set, this URL will receive a callback once the recording is available to use.

<?xml version="1.0" encoding="UTF-8"?>
<SpeakSentence>Please say your name.</SpeakSentence>
<Record recordCompleteUrl="/nextBxml" maxDuration="10"/>
<!-- Any verbs after this point would be replaced by those returned by the recordCompleteUrl -->

The /nextBXML endpoint responds with the following.

<SpeakSentence>Thank you.</SpeakSentence>

In this example, a <SpeakSentence> prompts the caller to say their name. The record then records the next 10 seconds, after which it will then play the BXML located at the /recordCompleteUrl endpoint, which says thank you.


The <StartRecording> verb starts recording in a call without pausing BXML execution. The <PauseRecording>, <ResumeRecording>, and <StopRecording> BXML verbs can be used to toggle the recording. Recording is terminated by either the call ending, or by a StopRecording verb.

Much like the Record verb, <StartRecording> also has a recordingAvailableUrl attribute to receive the recording available callback.

<?xml version="1.0" encoding="UTF-8"?>
<StartRecording recordingAvailableUrl="https://myapp.test/noBXML"/> //Note: This will send a callback that only notifies you that your recording is ready.
<SpeakSentence>Hello secret agent. What is your message?</SpeakSentence>
<Pause duration="10"/>
<SpeakSentence>Please say your secret passcode to send. Don't worry, the recording is paused!</SpeakSentence>
<Pause duration="5"/>
<SpeakSentence>Restarting the recording now.</SpeakSentence>
<SpeakSentence>Thank you agent. Good luck on your mission!</SpeakSentence>
<SpeakSentence>Recording has been stopped.</SpeakSentence>

The example above uses all the different forms of the controllable recording bxml, with StartRecording, PauseRecording, ResumeRecording, and StopRecording. In this scenario, the recording is started, a message is given, then the recording is paused to allow for sensitive information to be left out of the recording. Once the information is said, the recording is resumed to catch the last part of the conversation, then stopped to hang up the call.

Download Recording

After the call has completed you can retrieve information on the recording and download the file in .mp3 or .wav format. Recordings are stored for 30 days.

curl '$BW_ACCOUNT_ID/calls/{CALL_ID}/recordings/{RECORDING_ID}' \

Transcribing a Call

Request Transcription of an Existing Recording

You can also choose to request transcription of a recording after it has been completed via the API.


Transcription can succeed only for recordings of length greater than 500 milliseconds and less than 4 hours.

//Remember to add an auth header with your Bandwidth credentials

"callbackUrl": "http://transcription.test",

In this example, using our callId and recordingId we are requesting to download a specific recording. You can use this to download as many recordings as you require.

Request Transcription when creating a Recording

The transcribe attribute can be added to the <Record> or <StartRecording> BXML verbs to automatically generate a transcription when the recording is done. If you want to receive a TranscriptionAvailable callback, you can additionally set the transcriptionAvailableUrl to a URL on your callback server and transcriptionAvailableMethod to its associated HTTP method (GET or POST, the default).

<?xml version="1.0" encoding="UTF-8"?>
<Record transcribe='true' transcriptionAvailableUrl="/transcription_callback" maxDuration="10"/>

In this example, we have just built on our original <Record> example to add transcription to our recording and specified a callback URL.

Download Transcription

After the call has completed, you can download the transcribed file in JSON format. Transcriptions are stored for 30 days.

curl '{accountId}/calls/{callId}/recordings/{recordingId}/transcription' \

In this example, using your callId and recordingId you are requesting to download a specific transcription. Similar to requesting a recording, you can use this to download as many transcriptions as you require.

Where to next?

Now that you have learnt how to record and transcribe calls, check out some of the available actions in the following guides: