Hold Music API

Configure and manage hold music and on-hold announcements for your Audian phone system. Keep callers informed and entertained while on hold.

Endpoint

POST https://api.audian.com:8443/v2/media/hold-music

Request

Headers

Content-Type: application/json
X-Auth-Token: YOUR_API_KEY

Parameters

Parameter	Type	Required	Description
name	String	Yes	Name for the hold music configuration
media_id	String	Yes	Media file ID for hold music
loop	Boolean	No	Loop the audio (default: true)
volume	Number	No	Volume level 0-100 (default: 80)
announcements	Array	No	On-hold announcements
announcement_interval	Number	No	Interval between announcements in seconds (default: 30)

Examples

Set Basic Hold Music

curl -X POST https://api.audian.com:8443/v2/media/hold-music \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "default-hold-music",
    "media_id": "media_abc123def456",
    "loop": true,
    "volume": 80
  }'

JavaScript/Node.js

const axios = require('axios');

const setHoldMusic = async () => {
  try {
    const response = await axios.post(
      'https://api.audian.com:8443/v2/media/hold-music',
      {
        name: 'default-hold-music',
        media_id: 'media_abc123def456',
        loop: true,
        volume: 80
      },
      {
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
        }
      }
    );
    console.log('Hold music configured:', response.data);
  } catch (error) {
    console.error('Configuration failed:', error);
  }
};

setHoldMusic();

Python

import requests

def set_hold_music(api_key, name, media_id, loop=True, volume=80,
                  announcements=None, announcement_interval=30):
    url = 'https://api.audian.com:8443/v2/media/hold-music'
    headers = {
        'X-Auth-Token': api_key,
        'Content-Type': 'application/json'
    }
    
    payload = {
        'name': name,
        'media_id': media_id,
        'loop': loop,
        'volume': volume,
        'announcement_interval': announcement_interval
    }
    
    if announcements:
        payload['announcements'] = announcements
    
    response = requests.post(url, headers=headers, json=payload)
    return response.json()

# Usage
result = set_hold_music(
    api_key='YOUR_API_KEY',
    name='default-hold-music',
    media_id='media_abc123def456',
    loop=True,
    volume=80
)
print(result)

Hold Music with Announcements

curl -X POST https://api.audian.com:8443/v2/media/hold-music \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "premium-hold-music",
    "media_id": "media_music_xyz789",
    "loop": true,
    "volume": 75,
    "announcements": [
      {
        "media_id": "media_announcement_1",
        "interval": 30
      },
      {
        "media_id": "media_announcement_2",
        "interval": 60
      }
    ],
    "announcement_interval": 45
  }'

Response

Success (200)

{
  "id": "hold_music_abc123",
  "name": "default-hold-music",
  "media_id": "media_abc123def456",
  "loop": true,
  "volume": 80,
  "announcements": [],
  "announcement_interval": 30,
  "created_at": "2024-02-04T10:45:00Z",
  "updated_at": "2024-02-04T10:45:00Z"
}

Error (400)

{
  "error": "invalid_volume",
  "message": "Volume must be between 0 and 100"
}

Queue Announcements

Periodically announce wait time or position in queue:

const queueAnnouncements = {
  announcements: [
    {
      media_id: 'media_wait_time_1',
      delay: 30, // Play after 30 seconds
      message: 'You are caller number 1 in the queue'
    },
    {
      media_id: 'media_wait_time_2',
      delay: 60, // Play after 60 seconds
      message: 'Thank you for your patience'
    },
    {
      media_id: 'media_wait_time_3',
      delay: 120, // Play after 2 minutes
      message: 'An agent will be with you shortly'
    }
  ]
};

Volume Levels

Level	Use Case
100	Attention-grabbing announcements
80	Standard background music
60	Subtle background, less intrusive
40	Very subtle, conversation-like
0	Silence only

Best Practices

1. Music Selection: Use royalty-free or properly licensed music
2. Clear Announcements: Keep on-hold messages concise and professional
3. Volume Balance: Set volume appropriate for the environment
4. Testing: Test hold music in your call queue before deployment
5. Regular Updates: Refresh announcements with current information
6. Brand Consistency: Use music and messages that reflect your brand

On-Hold Announcement Strategy

Frequent Announcements

• Interval: 20-30 seconds
• Use for: High wait time periods
• Purpose: Keep callers engaged and informed

Standard Announcements

• Interval: 45-60 seconds
• Use for: Typical wait times
• Purpose: Provide occasional updates

Minimal Announcements

• Interval: 90-120 seconds
• Use for: Short wait times
• Purpose: Maintain brand presence without interruption

Common Configurations

Professional Office

{
  "name": "professional-hold",
  "loop": true,
  "volume": 70,
  "announcement_interval": 45
}

Customer Service Queue

{
  "name": "support-queue-hold",
  "loop": true,
  "volume": 75,
  "announcement_interval": 30
}

Extended Wait Hold

{
  "name": "extended-wait-hold",
  "loop": true,
  "volume": 80,
  "announcement_interval": 20
}

Limits and Quotas

• Max hold music configurations: 50 per account
• Max announcements per config: 10
• Min announcement interval: 10 seconds
• Max announcement interval: 600 seconds
• Volume range: 0-100
• Max announcement duration: 30 seconds each