Skip to content

Retrieve file for playback

The audio file of a call can be delivered to the end user's web browser in two ways:

  1. Signed URL (recommended). Your web application requests a signed file URL from the MiaRec REST API and passes it to the browser. The browser retrieves the file directly from the MiaRec web portal.
  2. Proxy download. Your web application downloads the file from the MiaRec REST API and streams it to the browser.

Both endpoints require the Download action of the Calls permission.

GET /api/v2/calls/<call-id>.json/file_url.json?expires=<seconds>
Parameter Required Description
expires yes Validity of the URL in seconds. After that time, the URL is rejected.
file_id no ID of the file to return, when the call has several files (see File object fields). When omitted, all files of the call are concatenated into one stream.

Example of response:

{
  "signed_url": "https://miarec.example.com/calls/file/e03f497d-bdff-11e7-2790-4b6ab9967d89/signed?expires=1493100525&sign=NMxBcIFB6t2M...<TRUNCATED>"
}

How it works

How it works

  1. The end user's browser requests the playback of a call from your web application. For example, you render the following HTML:

    <audio controls>
    <source src="https://YOUR-WEB-SERVER/recordings/CALL-ID" type="audio/mpeg">
</audio>

  2. Your web application verifies that the user is allowed to hear the call, and requests the signed URL from the MiaRec REST API:

    GET /api/v2/calls/{call-id}.json/file_url.json?expires=3600

  3. The MiaRec web portal returns the signed URL. The signature protects the URL parameters (call ID, expiration time, host name) from modification. The URL is valid only for that call and only until the expiration time.

  4. Your web application redirects the browser to the signed URL:

    HTTP/1.1 302 Found
Location: https://miarec.example.com/calls/file/e03f...<TRUNCATED>

  5. The browser follows the redirect transparently.

  6. The MiaRec web portal verifies the signature and the expiration time, reads the file from the storage, and streams it to the browser. Encrypted files are decrypted on the fly.

Things to consider

  • It is the responsibility of your web application to check the permissions of the end user. The MiaRec web portal generates a signed URL for any call that is accessible to your REST API account. Limit the access scope of that account to the tenants, groups, or users your application serves.
  • Do not generate signed URLs in advance for every call on a page (for example, in a table of 50 calls). Each URL costs one request to the MiaRec web portal, whether the user plays the call or not. Generate the URL when the user clicks play.
  • The browser connects to the MiaRec web portal directly. Deploy a valid TLS certificate on the MiaRec web server, and make sure that the browser can reach it.

Method 2. Proxy download

GET /api/v2/calls/<call-id>.json/file
Parameter Required Description
file_id no ID of the file to return. When omitted, all files of the call are concatenated into one stream.

The response body is the audio data. The Content-Type header is audio/mpeg for MP3 files and audio/x-wav for WAV files.

How it works

How it works

  1. The end user's browser requests the playback of a call from your web application.
  2. Your web application sends the request above to the MiaRec REST API.
  3. The MiaRec web portal reads the file location from its database.
  4. The MiaRec web portal reads the file from the storage.
  5. The MiaRec web portal streams the file to your web application. Encrypted files are decrypted on the fly.
  6. Your web application streams the file to the browser.

Things to consider

  • The connection between the end user and your web application is usually slower than the connection between your web application and the MiaRec server. The download to the browser can time out on large files. Support resumable downloads with HTTP Range headers on your side.
  • If your web application and the MiaRec web portal are in different data centers, every file crosses the network twice (inbound to your application, then outbound to the browser).

Encrypted files

Both methods support encrypted files. The MiaRec web portal decrypts the file on the fly with the private key of the REST API account. The account must be granted access to the encryption key of the file. See Encryption keys.

Responses

Response Description
200 OK The signed URL (method 1) or the audio data (method 2) is returned
400 Bad Request The expires parameter is missing or is not an integer (method 1)
403 Forbidden The API user has no permission to download this call, or (method 1) the API user has no key pair, which is created when the user's password is set ({"error": "PermissionError", "explanation": "Could not load private key for your session. Try to reset password"})
404 Not Found Call with such ID does not exist, or the call has no audio file