> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gomobile.ma/llms.txt
> Use this file to discover all available pages before exploring further.

# Audio Management

> Upload, organize, and manage audio files for call flows

<Info>
  **Base path: `/audio-management`**
</Info>

## Types

<Accordion title="Type Definitions">
  ```typescript theme={null}
  // ============ Enums ============

  type AudioUsageType =
    | 'welcome'
    | 'goodbye'
    | 'question'
    | 'prompt'
    | 'hold_music'
    | 'notification'
    | 'other';

  type SortOrder = 'asc' | 'desc';

  // ============ Request Types ============

  interface UploadAudioRequest {
    file: File;                   // multipart/form-data
    title?: string;               // max 255 characters
    description?: string;         // max 500 characters
    usageType?: AudioUsageType;
    tags?: string[];
  }

  interface UpdateAudioRequest {
    title?: string;               // max 255 characters
    description?: string;         // max 500 characters
    usageType?: AudioUsageType;
    tags?: string[];
  }

  // ============ Query Parameters ============

  interface AudioListQueryParams {
    page?: number;                // default: 1, min: 1
    limit?: number;               // default: 20, max: 100
    search?: string;              // searches title, description, tags
    sortBy?: string;              // createdAt, title, durationSeconds
    sortOrder?: SortOrder;        // default: 'desc'
    organizationId?: string;      // UUID filter
    usageType?: AudioUsageType;
    tags?: string[];              // comma-separated or array
  }

  // ============ Response Types ============

  interface AudioFile {
    id: string;
    name: string;
    contentType: string;
    fileSize: number;
    checksum: string | null;
  }

  interface AudioResponse {
    id: string;
    title: string;
    description: string | null;
    usageType: AudioUsageType;
    tags: string[] | null;
    durationSeconds: number | null;
    sampleRate: number | null;
    channels: number | null;
    bitDepth: number | null;
    organizationId: string | null;
    originalFileName: string | null;
    createdAt: string;            // ISO date
    updatedAt: string;            // ISO date
    file: AudioFile;
  }

  interface AudioWithRelationsResponse extends AudioResponse {
    organization: {
      id: string;
      name: string;
      slug: string;
    };
  }

  interface AudioListResponse {
    data: AudioResponse[];
    meta: PaginationMeta;
  }

  interface PlaybackUrlResponse {
    id: string;
    playbackUrl: string;
    expiresIn: number;            // seconds
    expiresAt: string;            // ISO date
  }

  interface PaginationMeta {
    page: number;
    limit: number;
    total: number;
    totalPages: number;
    hasNextPage: boolean;
    hasPreviousPage: boolean;
  }

  interface MessageResponse {
    message: string;
  }
  ```
</Accordion>

### Upload and process audio file for use in call flows

```
// Request
POST /audio-management/upload
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: multipart/form-data

file: [binary audio file]
title: "Welcome Message"
description: "Welcome audio for customers"
usageType: "welcome"
tags: ["welcome", "greeting"]

// Response 201
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Welcome Message",
  "description": "Welcome audio for customers",
  "usageType": "welcome",
  "tags": ["welcome", "greeting"],
  "durationSeconds": 15.5,
  "sampleRate": 8000,
  "channels": 1,
  "bitDepth": 16,
  "organizationId": "660e8400-e29b-41d4-a716-446655440001",
  "originalFileName": "welcome.wav",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z",
  "file": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "name": "welcome_processed.wav",
    "contentType": "audio/wav",
    "fileSize": 248000,
    "checksum": "abc123..."
  }
}
```

***

### Get paginated list of audio files

```bash theme={null}
curl -X GET https://api.gomobile.ma/api/audio-management/audios?page=1&limit=20&usageType=welcome \
  -H "x-api-key: YOUR_API_KEY"
```

Response:

```json theme={null}
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Welcome Message",
      "description": "Welcome audio for customers",
      "usageType": "welcome",
      "tags": ["welcome", "greeting"],
      "durationSeconds": 15.5,
      "sampleRate": 8000,
      "channels": 1,
      "bitDepth": 16,
      "organizationId": "660e8400-e29b-41d4-a716-446655440001",
      "originalFileName": "welcome.wav",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z",
      "file": {
        "id": "770e8400-e29b-41d4-a716-446655440002",
        "name": "welcome_processed.wav",
        "contentType": "audio/wav",
        "fileSize": 248000,
        "checksum": "abc123..."
      }
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPreviousPage": false
  }
}
```

***

### Stream audio file directly for playback

***

### Get audio metadata without streaming content

```bash theme={null}
curl -X GET https://api.gomobile.ma/api/audio-management/audio/550e8400-e29b-41d4-a716-446655440000/metadata \
  -H "x-api-key: YOUR_API_KEY"
```

Response:

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Welcome Message",
  "description": "Welcome audio for customers",
  "usageType": "welcome",
  ...
}
```

***

### Get audio with related entities

```bash theme={null}
curl -X GET https://api.gomobile.ma/api/audio-management/audio/550e8400-e29b-41d4-a716-446655440000/details \
  -H "x-api-key: YOUR_API_KEY"
```

Response:

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Welcome Message",
  "description": "Welcome audio for customers",
  "usageType": "welcome",
  ...
  "organization": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "name": "Acme Corporation",
    "slug": "acme-corp"
  }
}
```

***

### Update audio metadata

```bash theme={null}
curl -X PUT https://api.gomobile.ma/api/audio-management/audio/550e8400-e29b-41d4-a716-446655440000 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
  "title": "Updated Welcome Message",
  "tags": ["welcome", "updated"]
}
'
```

Response:

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Updated Welcome Message",
  "tags": ["welcome", "updated"],
  ...
}
```

***

### Generate a temporary signed URL for audio playback

```bash theme={null}
curl -X GET https://api.gomobile.ma/api/audio-management/audio/550e8400-e29b-41d4-a716-446655440000/playback-url?expiresIn=7200 \
  -H "x-api-key: YOUR_API_KEY"
```

Response:

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "playbackUrl": "https://s3.amazonaws.com/bucket/audio.wav?X-Amz-Signature=...",
  "expiresIn": 7200,
  "expiresAt": "2025-01-15T12:30:00.000Z"
}
```

***

### Get audio files filtered by usage type

```bash theme={null}
curl -X GET https://api.gomobile.ma/api/audio-management/audios/usage/welcome \
  -H "x-api-key: YOUR_API_KEY"
```

Response:

```json theme={null}
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Welcome Message",
    "usageType": "welcome",
    ...
  }
]
```

***

### Delete audio file and remove from storage

```bash theme={null}
curl -X DELETE https://api.gomobile.ma/api/audio-management/audio/550e8400-e29b-41d4-a716-446655440000 \
  -H "x-api-key: YOUR_API_KEY"
```

Response:

```json theme={null}
{
  "message": "Audio deleted successfully"
}
```