Skip to main content
Base path: /audio-management

​
Types

// ============ 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;
}

​
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

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: 
{
  "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

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: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Welcome Message",
  "description": "Welcome audio for customers",
  "usageType": "welcome",
  ...
}

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: 
{
  "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

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: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Updated Welcome Message",
  "tags": ["welcome", "updated"],
  ...
}

​
Generate a temporary signed URL for audio playback

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: 
{
  "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

curl -X GET https://api.gomobile.ma/api/audio-management/audios/usage/welcome \
  -H "x-api-key: YOUR_API_KEY"
Response: 
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Welcome Message",
    "usageType": "welcome",
    ...
  }
]

​
Delete audio file and remove from storage

curl -X DELETE https://api.gomobile.ma/api/audio-management/audio/550e8400-e29b-41d4-a716-446655440000 \
  -H "x-api-key: YOUR_API_KEY"
Response: 
{
  "message": "Audio deleted successfully"
}