Call Recording

The Audian API provides comprehensive call recording capabilities. You can record incoming and outgoing calls, control recording during calls, and access recordings through simple APIs.

Automatic Recording

Enable automatic recording for all calls made through an API call:

curl -X POST https://api.audian.com:8443/v2/calls \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+14155552671",
    "to": "+14155552672",
    "recording": {
      "enabled": true,
      "format": "mp3",
      "participant": "all"
    }
  }'

Recording Parameters

Parameter	Type	Options	Description
`enabled`	boolean	-	Enable/disable recording
`format`	string	`wav`, `mp3`, `opus`	Audio file format
`participant`	string	`all`, `caller`, `callee`	Who to record
`bitrate`	integer	-	Audio bitrate in kbps
`sample_rate`	integer	`8000`, `16000`	Audio sample rate

Start Recording During Call

Start recording an active call:

curl -X POST https://api.audian.com:8443/v2/calls/call_xyz789/record/start \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "mp3",
    "participant": "all"
  }'

Response:

{
  "call_id": "call_xyz789",
  "recording_id": "rec_abc123",
  "status": "recording",
  "started_at": "2024-01-15T10:30:05Z",
  "format": "mp3"
}

Stop Recording

Stop an active recording:

curl -X POST https://api.audian.com:8443/v2/calls/call_xyz789/record/stop \
  -H "X-Auth-Token: YOUR_API_KEY"

Response:

{
  "call_id": "call_xyz789",
  "recording_id": "rec_abc123",
  "status": "stopped",
  "stopped_at": "2024-01-15T10:35:10Z",
  "duration": 305
}

Pause Recording

Pause recording without stopping it:

curl -X POST https://api.audian.com:8443/v2/calls/call_xyz789/record/pause \
  -H "X-Auth-Token: YOUR_API_KEY"

Resume Recording

Resume a paused recording:

curl -X POST https://api.audian.com:8443/v2/calls/call_xyz789/record/resume \
  -H "X-Auth-Token: YOUR_API_KEY"

Recording for Inbound Calls

Enable recording for all calls to a phone number:

curl -X POST https://api.audian.com:8443/v2/call-flows \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Recorded Support Line",
    "phone_number": "+14155552671",
    "recording": {
      "enabled": true,
      "format": "mp3",
      "participant": "all"
    },
    "routing": [
      {
        "pattern": "*",
        "destination": "+14155552673",
        "destination_type": "phone_number"
      }
    ]
  }'

Get Recording Information

Retrieve information about a recording:

curl https://api.audian.com:8443/v2/recordings/rec_abc123 \
  -H "X-Auth-Token: YOUR_API_KEY"

Response:

{
  "recording_id": "rec_abc123",
  "call_id": "call_xyz789",
  "duration": 305,
  "file_size": 1536000,
  "file_format": "mp3",
  "bitrate": 64,
  "sample_rate": 16000,
  "channels": 1,
  "status": "completed",
  "created_at": "2024-01-15T10:35:10Z",
  "completed_at": "2024-01-15T10:36:00Z"
}

Download Recording

Get the download URL for a recording:

curl https://api.audian.com:8443/v2/recordings/rec_abc123/download \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -L

The response will redirect to a temporary download URL that's valid for 24 hours.

You can also get the download URL from the recording completion webhook:

{
  "event": "recording.completed",
  "data": {
    "recording_id": "rec_abc123",
    "call_id": "call_xyz789",
    "download_url": "https://api.audian.com:8443/v2/recordings/rec_abc123/download",
    "file_size": 1536000,
    "duration": 305,
    "completed_at": "2024-01-15T10:36:00Z"
  }
}

List Recordings

List all recordings for a specific call or date range:

# List recordings for a specific call
curl "https://api.audian.com:8443/v2/recordings?call_id=call_xyz789" \
  -H "X-Auth-Token: YOUR_API_KEY"

# List recordings from the last 7 days
curl "https://api.audian.com:8443/v2/recordings?since=2024-01-08T10:30:00Z" \
  -H "X-Auth-Token: YOUR_API_KEY"

# List recordings with pagination
curl "https://api.audian.com:8443/v2/recordings?limit=50&offset=0" \
  -H "X-Auth-Token: YOUR_API_KEY"

Response:

{
  "data": [
    {
      "recording_id": "rec_abc123",
      "call_id": "call_xyz789",
      "duration": 305,
      "file_size": 1536000,
      "status": "completed",
      "created_at": "2024-01-15T10:35:10Z"
    },
    {
      "recording_id": "rec_abc124",
      "call_id": "call_xyz790",
      "duration": 125,
      "file_size": 640000,
      "status": "completed",
      "created_at": "2024-01-14T14:20:30Z"
    }
  ],
  "pagination": {
    "total": 152,
    "limit": 50,
    "offset": 0,
    "has_more": true
  }
}

Delete Recording

Delete a recording when no longer needed:

curl -X DELETE https://api.audian.com:8443/v2/recordings/rec_abc123 \
  -H "X-Auth-Token: YOUR_API_KEY"

Response:

{
  "recording_id": "rec_abc123",
  "deleted_at": "2024-01-15T11:00:00Z"
}

Recording Webhooks

You'll receive webhook events for recording activities:

recording.started

{
  "event": "recording.started",
  "data": {
    "call_id": "call_xyz789",
    "recording_id": "rec_abc123",
    "started_at": "2024-01-15T10:30:05Z"
  }
}

recording.stopped

{
  "event": "recording.stopped",
  "data": {
    "call_id": "call_xyz789",
    "recording_id": "rec_abc123",
    "duration": 305,
    "stopped_at": "2024-01-15T10:35:10Z"
  }
}

recording.completed

{
  "event": "recording.completed",
  "data": {
    "call_id": "call_xyz789",
    "recording_id": "rec_abc123",
    "duration": 305,
    "file_size": 1536000,
    "file_format": "mp3",
    "download_url": "https://api.audian.com:8443/v2/recordings/rec_abc123/download",
    "completed_at": "2024-01-15T10:36:00Z",
    "checksum": {
      "algorithm": "sha256",
      "value": "abcdef0123456789"
    }
  }
}

recording.failed

{
  "event": "recording.failed",
  "data": {
    "call_id": "call_xyz789",
    "recording_id": "rec_abc123",
    "reason": "storage_error",
    "failed_at": "2024-01-15T10:36:00Z"
  }
}

Recording Storage

Recordings are stored securely and are:

Encrypted at rest: Using AES-256 encryption
Retained for 30 days: Automatically deleted after 30 days
Accessible via API: Download at any time
Webhooks: Get notified when recording completes

Recording Formats

MP3 Format

Default format, compressed audio:

Bitrate: 64 kbps (default), configurable
Sample Rate: 16 kHz
File Size: ~300 KB per minute at 64 kbps
Use Case: Web playback, storage efficiency

WAV Format

Uncompressed audio, highest quality:

Bitrate: PCM 256 kbps
Sample Rate: 16 kHz
File Size: ~1.9 MB per minute
Use Case: Archival, legal requirements

Opus Format

Modern compressed format:

Bitrate: 32 kbps (default)
Sample Rate: 16 kHz or 48 kHz
File Size: ~240 KB per minute at 32 kbps
Use Case: Best compression, modern browsers

Recording States

State	Description
`initiated`	Recording request received
`recording`	Currently recording
`paused`	Temporarily paused
`stopped`	Recording stopped but not yet processed
`processing`	Recording being processed
`completed`	Ready for download
`failed`	Recording failed

Participant Recording

Control who is recorded:

Record All Participants

{
  "participant": "all"
}

Records both parties in the conversation.

Record Caller Only

{
  "participant": "caller"
}

Records only the incoming call party.

Record Callee Only

{
  "participant": "callee"
}

Records only the answering party.

Recording Compliance

Legal Notices

When recording is enabled, you may need to:

Notify callers: Audian can play a notification tone
Get consent: Ensure legal compliance in your jurisdiction
Document recording: Keep records of when/why calls were recorded

Enable notification tone:

curl -X POST https://api.audian.com:8443/v2/calls \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+14155552671",
    "to": "+14155552672",
    "recording": {
      "enabled": true,
      "announce": true,
      "announcement": "This call is being recorded"
    }
  }'

Error Handling

Recording Quota Exceeded

{
  "error": "quota_exceeded",
  "message": "Recording storage quota exceeded",
  "code": 429
}

Recording Not Available

{
  "error": "not_found",
  "message": "Recording not found",
  "code": 404
}

Invalid Recording Format

{
  "error": "invalid_format",
  "message": "Recording format is not supported",
  "code": 400
}

Code Examples

Node.js

const axios = require('axios');
const fs = require('fs');

async function downloadRecording(recordingId) {
  try {
    const response = await axios.get(
      `https://api.audian.com:8443/v2/recordings/${recordingId}/download`,
      {
        headers: {
          'Authorization': `Bearer ${process.env.AUDIAN_API_KEY}`
        },
        responseType: 'stream'
      }
    );

    const filename = `recording_${recordingId}.mp3`;
    response.data.pipe(fs.createWriteStream(filename));

    console.log(`Recording saved to ${filename}`);
  } catch (error) {
    console.error('Error downloading recording:', error);
  }
}

async function startRecording(callId) {
  try {
    const response = await axios.post(
      `https://api.audian.com:8443/v2/calls/${callId}/record/start`,
      {
        format: 'mp3',
        participant: 'all'
      },
      {
        headers: {
          'Authorization': `Bearer ${process.env.AUDIAN_API_KEY}`
        }
      }
    );

    console.log('Recording started:', response.data.recording_id);
  } catch (error) {
    console.error('Error starting recording:', error.response?.data);
  }
}

Python

import requests
import os

def download_recording(recording_id):
    url = f'https://api.audian.com:8443/v2/recordings/{recording_id}/download'
    headers = {
        'Authorization': f"Bearer {os.getenv('AUDIAN_API_KEY')}"
    }

    response = requests.get(url, headers=headers)

    filename = f'recording_{recording_id}.mp3'
    with open(filename, 'wb') as f:
        f.write(response.content)

    print(f'Recording saved to {filename}')

def start_recording(call_id):
    url = f'https://api.audian.com:8443/v2/calls/{call_id}/record/start'
    headers = {
        'Authorization': f"Bearer {os.getenv('AUDIAN_API_KEY')}",
        'Content-Type': 'application/json'
    }
    payload = {
        'format': 'mp3',
        'participant': 'all'
    }

    response = requests.post(url, json=payload, headers=headers)
    print(f"Recording started: {response.json()['recording_id']}")

Best Practices

Handle webhook events: Process recording.completed events
Download promptly: Download recordings within 30 days
Implement encryption: Encrypt recordings when storing
Audit trail: Log all recording access
Retention policy: Define how long to retain recordings
Compliance: Check local laws regarding recording

Automatic Recording​

Recording Parameters​

Start Recording During Call​

Stop Recording​

Pause Recording​

Resume Recording​

Recording for Inbound Calls​

Get Recording Information​

Download Recording​

List Recordings​

Delete Recording​

Recording Webhooks​

recording.started​

recording.stopped​

recording.completed​

recording.failed​

Recording Storage​

Recording Formats​

MP3 Format​

WAV Format​

Opus Format​

Recording States​

Participant Recording​

Record All Participants​

Record Caller Only​

Record Callee Only​

Recording Compliance​

Legal Notices​

Error Handling​

Recording Quota Exceeded​

Recording Not Available​

Invalid Recording Format​

Code Examples​

Node.js​

Python​

Best Practices​

Next Steps​

Automatic Recording

Recording Parameters

Start Recording During Call

Stop Recording

Pause Recording

Resume Recording

Recording for Inbound Calls

Get Recording Information

Download Recording

List Recordings

Delete Recording

Recording Webhooks

recording.started

recording.stopped

recording.completed

recording.failed

Recording Storage

Recording Formats

MP3 Format

WAV Format

Opus Format

Recording States

Participant Recording

Record All Participants

Record Caller Only

Record Callee Only

Recording Compliance

Legal Notices

Error Handling

Recording Quota Exceeded

Recording Not Available

Invalid Recording Format

Code Examples

Node.js

Python

Best Practices

Next Steps