Creating a Transcription Request for a Voice Recording with MessageBird

A transcription is a textual representation of a recording that has speech. The MessageBird API provides an easy way to create a transcription for a recording file that was previously generated for a specific call or call leg.

In this MessageBird Tutorial you’ll learn how to create a transcription request for a voice recording with our API.

Step 1: Create the Transcription Request

To create a transcription request with MessageBird Voice API, you need to know the ID of the recording. You can find more information about the transcription object in the 'Transcriptions' section of our Voice Calling API documentation.

The Voice API endpoint for creating a transcription request for a leg is:

https://voice.messagebird.com/recordings/{recordingID}/transcriptions/

This is a transcription request example with cURL:

curl -X "POST"
"http://voice.messagebird.com/recordings/{recordingID}/transcriptions" \
  -H "Authorization: AccessKey :your_access_key:"

Here’s an example result to a request like that:

{
  "data": [
    {
      "id": "{transcriptionID}",
      "recordingID": "{recordingID}",
      "createdAt": "2017-06-26T10:12:14Z",
      "updatedAt": "2017-06-26T10:12:14Z"
    }
  ],
  "_links": {
    "self": "/transcriptions/{transcriptionID}"
    "file": "/transcriptions/{transcriptionID}.txt"
  }
}

The your_access_key is your API access token that can be found under your API access tab in the MessageBird Dashboard. This request will initiate a transcription for that recording.

Step 2: Get the transcription result

You can access the transcription object that you previously created by making a GET request to the endpoint:

http://voice.messagebird.com/transcriptions/{transcriptionID}

The MessageBird API also provides an endpoint for downloading the .txt result of a transcription:

http://voice.messagebird.com/transcriptions/{transcriptionID}.txt

By marking a request in the previous endpoint, you can download the text file with the transcription result:

## List Calls
curl
"http://voice.messagebird.com/transcriptions/{transcriptionID}.txt" \
  -H "Authorization: AccessKey :your_access_key:"

Keep in mind

If the transcription has failed, we’ll return an error message. Reasons for a failed transcription may include not recognition of the voice in a recording due to background noise, unidentified language and low volume in the recorded message.

You can create a transcription request immediately after a recording has ended by providing the transcription parameter as true in the record step of a call flow; you can read more about this in our Call Recording MessageBird Tutorial.

The transcriptions are being generated asynchronously, which means that when you POST a transcription request, the result will be available some time after the transcription ends; you may then get the transcription text file by marking the request we just described.

Nice work! 🎉

You just learned how to create a transcription for a recording with the MessageBird API!

Start building!

Want to build something similar but not quite sure how to get started? Feel free to let us know at support@messagebird.com; we'd love to help!

Is this page useful?

Questions?

We’re always happy to help with code or other doubts you might have! Check out our Quickstarts, API Reference, Tutorials, SDKs, or contact our Support team.