Call Recordings

Enabling Recording

Add the following fields to the VoiceElements_Instructions block of your CallStart response to enable and optionally encrypt call recordings.

{
  "VoiceElements_Instructions": {
    "aiUrl": { ... },
    "maxSeconds": 300,
    "defaultToolsUrlBase": { ... },

    "recordCall": true,
    "recordCallFormat": "opus",
    "recordCallPassword": "EncryptMe"
  }
}

Recording Formats

Choose the format that best fits your downstream processing needs.

Downloading Recordings

Completed recordings are retrievable via the VNS API. Recordings that have not been explicitly deleted are automatically purged after 7 days — download or archive any recordings you wish to keep before that window expires.

Use the GetRecording endpoint on the VNS API, passing the sessionGuid from the CallEnd webhook. The API returns the .enc encrypted file if a password was set, or the plain audio file if no password was used.

Decrypting with the FileDecryptor Utility

A ready-to-run .NET 8 command-line utility is available to decrypt .enc files without writing any code. Only use this section if you set a recordCallPassword — unencrypted recordings download directly as playable audio files.

Usage

FileDecryptor <fileName> <password> <outputExtension>

Example

FileDecryptor recording_abc123.enc EncryptMe opus

This produces recording_abc123.opus in the same directory.

Decrypting in C#

Adapt the following code to decrypt recordings directly in your own application. No external dependencies — only System.Security.Cryptography from the .NET base class library.

using System.Security.Cryptography;

const int SaltSize   = 16;
const int NonceSize  = 12;
const int TagSize    = 16;
const int HeaderSize = SaltSize + NonceSize; // 28 bytes
const int Iterations = 310_000;

// ── Read the .enc file ────────────────────────────────────────────────────────
byte[] fileBytes = File.ReadAllBytes("recording.enc");

// ── Extract header components ─────────────────────────────────────────────────
var salt         = fileBytes[..SaltSize];
var nonce        = fileBytes[SaltSize..HeaderSize];
var cipherAndTag = fileBytes[HeaderSize..];
var ciphertext   = cipherAndTag[..^TagSize];
var tag          = cipherAndTag[^TagSize..];

// ── Derive 256-bit key via PBKDF2-SHA256 ──────────────────────────────────────
var key = new byte[32];
Rfc2898DeriveBytes.Pbkdf2("YourPassword", salt, key, Iterations, HashAlgorithmName.SHA256);

// ── Decrypt with AES-256-GCM ──────────────────────────────────────────────────
var plaintext = new byte[ciphertext.Length];
using (var aes = new AesGcm(key, TagSize))
{
    aes.Decrypt(nonce, ciphertext, tag, plaintext);
}

CryptographicOperations.ZeroMemory(key);

// ── Write the decrypted audio file ────────────────────────────────────────────
File.WriteAllBytes("recording.opus", plaintext);

.enc File Format

The .enc file uses AES-256-GCM with a PBKDF2-derived key. The binary layout is: