Recordings

KrosAI automatically records all calls and generates transcripts. Access recordings via the API or dashboard.

Overview

• Automatic Recording: All calls are recorded by default

• Transcription: Speech-to-text transcripts generated automatically

• Storage: Secure cloud storage with 90-day retention (configurable)

• Format: MP3 audio, 48kHz mono

Accessing Recordings

Via Call Detail

Recordings are included in the call detail response:

curl

curl -X GET "https://api.krosai.com/v1/calls/call_abc123" \
  -H "x-api-key: kros_live_your_key"

Response:

response.json

{
  "id": "call_abc123",
  "status": "completed",
  "duration": 180,
  "recording_url": "https://storage.krosai.com/recordings/call_abc123.mp3",
  "transcript": "[Agent]: Hello, how can I help you today?\n[Caller]: I need help with my order...",
  "created_at": "2025-01-10T10:00:00Z"
}

Download Recording

Recordings are served via presigned URLs that are valid for 1 hour:

downloadRecording.ts

async function downloadRecording(callId: string): Promise<Blob> {
  // Get call details with recording URL
  const call = await fetch(`https://api.krosai.com/v1/calls/${callId}`, {
    headers: { 'x-api-key': process.env.KROSAI_API_KEY! },
  }).then(r => r.json());

  if (!call.recording_url) {
    throw new Error('No recording available');
  }

  // Download the audio file
  const response = await fetch(call.recording_url);
  return response.blob();
}

Get Recording URL Only

For efficiency, you can request just the recording URL:

GET /calls/{id}/recording

Response:

response.json

{
  "recording_url": "https://storage.krosai.com/recordings/call_abc123.mp3",
  "expires_at": "2025-01-10T11:00:00Z",
  "duration_seconds": 180,
  "format": "mp3",
  "size_bytes": 2160000
}

Transcripts

Transcript Format

Transcripts are provided as plain text with speaker labels:

transcript.txt

[Agent]: Hello, thank you for calling. How can I help you today?
[Caller]: Hi, I'm calling about my recent order.
[Agent]: I'd be happy to help with that. Can you provide your order number?
[Caller]: Sure, it's ORD-12345.
[Agent]: Thank you. I can see your order here. It was shipped yesterday and should arrive tomorrow.
[Caller]: Great, thanks for the update!
[Agent]: You're welcome. Is there anything else I can help with?
[Caller]: No, that's all. Thank you.
[Agent]: Have a great day. Goodbye!

Get Transcript Only

GET /calls/{id}/transcript

Response:

response.json

{
  "transcript": "[Agent]: Hello, thank you for calling...",
  "word_count": 156,
  "language": "en",
  "confidence": 0.94
}

Recording Settings

Enable/Disable Recording

Configure recording at the organization level:

curl

curl -X PATCH "https://api.krosai.com/v1/settings" \
  -H "x-api-key: kros_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "recording_enabled": true,
    "transcription_enabled": true
  }'

Per-Call Recording Control

Override recording settings for specific calls:

curl

curl -X POST "https://api.krosai.com/v1/outbound-calls" \
  -H "x-api-key: kros_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "[phone]",
    "to_number": "[phone]",
    "endpoint_id": "ep_abc123",
    "recording_enabled": false
  }'

Recording Retention

Plan	Default Retention	Maximum Retention
Free	7 days	7 days
Pro	30 days	90 days
Business	90 days	365 days
Enterprise	Custom	Unlimited

Extend Retention

Keep specific recordings longer:

curl

curl -X POST "https://api.krosai.com/v1/calls/call_abc123/recording/extend" \
  -H "x-api-key: kros_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "days": 365
  }'

Code Examples

TypeScript - Batch Download Recordings

download-all-recordings.ts

import fs from 'fs';
import path from 'path';

async function downloadAllRecordings(fromDate: string, outputDir: string) {
  // Get calls with recordings
  const response = await fetch(
    `https://api.krosai.com/v1/calls?from_date=${fromDate}&status=completed`,
    {
      headers: { 'x-api-key': process.env.KROSAI_API_KEY! },
    }
  );
  
  const { calls } = await response.json();
  
  for (const call of calls) {
    if (!call.recording_url) continue;
    
    const audioResponse = await fetch(call.recording_url);
    const buffer = await audioResponse.arrayBuffer();
    
    const filename = `${call.id}_${call.from_number}_${call.duration}s.mp3`;
    fs.writeFileSync(
      path.join(outputDir, filename),
      Buffer.from(buffer)
    );
    
    console.log(`Downloaded: ${filename}`);
  }
}

Python - Export Transcripts

export-transcripts.py

import requests
import os
import json

def export_transcripts(from_date: str, output_file: str):
    api_key = os.environ['KROSAI_API_KEY']
    
    # Get completed calls
    response = requests.get(
        f'https://api.krosai.com/v1/calls',
        headers={'x-api-key': api_key},
        params={
            'from_date': from_date,
            'status': 'completed',
            'limit': 100
        }
    )
    
    calls = response.json()['calls']
    
    transcripts = []
    for call in calls:
        if call.get('transcript'):
            transcripts.append({
                'call_id': call['id'],
                'from': call['from_number'],
                'to': call['to_number'],
                'duration': call['duration'],
                'transcript': call['transcript'],
                'timestamp': call['created_at']
            })
    
    with open(output_file, 'w') as f:
        json.dump(transcripts, f, indent=2)
    
    print(f'Exported {len(transcripts)} transcripts to {output_file}')

# Export last 30 days
export_transcripts('2025-01-01', 'transcripts.json')

Streaming Audio Playback

CallRecordingPlayer.tsx

// React component for audio playback
function CallRecordingPlayer({ callId }: { callId: string }) {
  const [audioUrl, setAudioUrl] = useState<string | null>(null);
  const [loading, setLoading] = useState(true);
  
  useEffect(() => {
    async function loadRecording() {
      const response = await fetch(`/api/calls/${callId}`);
      const call = await response.json();
      setAudioUrl(call.recording_url);
      setLoading(false);
    }
    loadRecording();
  }, [callId]);
  
  if (loading) return <Skeleton className="h-12 w-full" />;
  if (!audioUrl) return <p>No recording available</p>;
  
  return (
    <audio controls className="w-full">
      <source src={audioUrl} type="audio/mpeg" />
      Your browser does not support the audio element.
    </audio>
  );
}

Compliance & Privacy

Recording Disclosure

Ensure compliance with local laws regarding call recording:

• United States: Two-party consent in some states

• European Union: GDPR requires explicit consent

• Nigeria: Recording allowed for business purposes

Data Protection

• Recordings are encrypted at rest (AES-256)

• Transmitted via HTTPS/TLS 1.3

• Access logged for audit purposes

• Automatic deletion after retention period

Delete Recording

Permanently delete a recording:

curl

curl -X DELETE "https://api.krosai.com/v1/calls/call_abc123/recording" \
  -H "x-api-key: kros_live_your_key"

Warning: This action is irreversible.