The building blocks
Tropo uploads the file to your web server using HTTP POST, sending the file in a field called “filename”. In PHP, you can access this file with the variable $_FILES[‘filename’]. This file is going to be saved in a place the web server can serve it up later.
The VoiceBase API uses the same URI for all API calls, and an “action” parameter in the API call tells VoiceBase what API call is being made. All API calls are authenticated with an API key and the VoiceBase account password, also both passed as API parameters. A version parameter indicates which VoiceBase API version is being accessed.
To upload a recording, a POST request will be used. The API name is uploadMedia. Instead of sending the recording file to VoiceBase, the API call includes a URL where VoiceBase will download the recording. And the VoiceBase API allows an externalID to be set that later be used retrieve the transcription.
Transcription is asynchronous. The upload API call returns immediately, and the transcription is fetched with another API call when it is complete. The upload API allows a callback URL to be set, and when the transcription is complete, VoiceBase will send a webhook request to this URL.
The webhook is a GET request with a series of query string parameters. The two that we’re interested in are state, which indicates whether or not the transcription worked, and externalId, which contains the unique ID we set for this recording.
To fetch the recording, a GET with query string parameters is sent. The API name is getTranscript. The version and authentication keys are included in the query string. The externalID is specified in the query string to tell VoiceBase which transcription to retrieve. The format parameter indicates how you would like the transcription formatted. VoiceBase supports a variety of output formats including plain text and even PDF.