# 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:

{% code title="curl" %}

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

{% endcode %}

Response:

{% code title="response.json" %}

```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"
}
```

{% endcode %}

### Download Recording

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

{% code title="downloadRecording.ts" %}

```typescript
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();
}
```

{% endcode %}

### Get Recording URL Only

For efficiency, you can request just the recording URL:

```
GET /calls/{id}/recording
```

Response:

{% code title="response.json" %}

```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
}
```

{% endcode %}

## Transcripts

### Transcript Format

Transcripts are provided as plain text with speaker labels:

{% code title="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!
```

{% endcode %}

### Get Transcript Only

```
GET /calls/{id}/transcript
```

Response:

{% code title="response.json" %}

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

{% endcode %}

## Recording Settings

### Enable/Disable Recording

Configure recording at the organization level:

{% code title="curl" %}

```bash
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
  }'
```

{% endcode %}

### Per-Call Recording Control

Override recording settings for specific calls:

{% code title="curl" %}

```bash
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": "+2348012345678",
    "to_number": "+14155551234",
    "endpoint_id": "ep_abc123",
    "recording_enabled": false
  }'
```

{% endcode %}

## 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:

{% code title="curl" %}

```bash
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
  }'
```

{% endcode %}

## Code Examples

### TypeScript - Batch Download Recordings

{% code title="download-all-recordings.ts" %}

```typescript
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}`);
  }
}
```

{% endcode %}

### Python - Export Transcripts

{% code title="export-transcripts.py" %}

```python
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')
```

{% endcode %}

### Streaming Audio Playback

{% code title="CallRecordingPlayer.tsx" %}

```typescript
// 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>
  );
}
```

{% endcode %}

## 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:

{% code title="curl" %}

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

{% endcode %}

{% hint style="danger" %}
Warning: This action is irreversible.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.krosai.com/voice/recordings.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.