Play Audio Before Conversations Start - Dasha BlackBox Documentation

Play an audio file the moment a call connects — before your agent says anything. Use it for compliance disclosures, branded greetings, or hold music that plays while the conversation initializes. What you’ll learn: How to configure pre-conversation media, enable it per call type, and upload custom audio files.

When to use pre-conversation media

Use case	Example
Compliance disclosures	”This call may be recorded for quality assurance”
Branded greetings	Company jingle or professional intro
Legal notices	Privacy or terms acknowledgment
Hold music	Brief audio while the agent initializes

The audio plays once, immediately when the call connects, and cannot be interrupted by the caller.

Configure pre-conversation media

Dashboard
API

Open your agent’s configuration
Navigate to the Features tab
Find Pre-Conversation Media and toggle it on
Select a media file from your uploaded files
Enable for specific call types (inbound, outbound, web)
Save your agent

const response = await fetch('https://blackbox.dasha.ai/api/v1/agents', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Support Agent',
    config: {
      features: {
        preConversationMedia: {
          isEnabled: true,
          mediaFilename: 'compliance-disclosure.mp3',
          enabledForInbound: true,
          enabledForOutbound: true,
          enabledForWebCall: false
        }
      }
      // ... other config
    }
  })
});

Configuration options

Field	Type	Default	Description
`isEnabled`	boolean	`false`	Master toggle for the feature
`mediaFilename`	string	`null`	Filename of uploaded media to play
`enabledForInbound`	boolean	`false`	Play media on incoming calls
`enabledForOutbound`	boolean	`false`	Play media on outgoing calls
`enabledForWebCall`	boolean	`false`	Play media on browser-based calls

Upload media files

Before using pre-conversation media, upload your audio file:

Dashboard
API

Navigate to Media in the sidebar
Click Upload and select your audio file
The filename will appear in the pre-conversation media dropdown

const formData = new FormData();
formData.append('file', audioFile);

const response = await fetch('https://blackbox.dasha.ai/api/v1/media/upload', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: formData
});

const { filename } = await response.json();
// Use this filename in preConversationMedia.mediaFilename

Supported formats: MP3, WAV, OGG Recommended specs:

Duration: 3–10 seconds (keep it brief)
Sample rate: 44.1kHz or 48kHz
Bit depth: 16-bit minimum

Call type behavior

Enable pre-conversation media independently for each call type:

Call type	When it plays	Typical use
Inbound	When customer calls your agent	”Thank you for calling…”
Outbound	When agent calls a customer	”This is an automated call from…”
Web call	When user starts browser call	Branded intro for web widget

Example: Inbound-only compliance

preConversationMedia: {
  isEnabled: true,
  mediaFilename: 'recording-notice.mp3',
  enabledForInbound: true,
  enabledForOutbound: false,  // Outbound calls skip the intro
  enabledForWebCall: false
}

Example: All call types

preConversationMedia: {
  isEnabled: true,
  mediaFilename: 'welcome-message.mp3',
  enabledForInbound: true,
  enabledForOutbound: true,
  enabledForWebCall: true
}

Troubleshooting

Audio doesn’t play

Symptom	Fix
No audio on any calls	Check `isEnabled` is `true` and media file exists
No audio on specific call type	Enable the call type flag (`enabledForInbound`, etc.)
404 error on media	Re-upload the file and update the filename

Audio quality issues

Issue	Fix
Clipping or distortion	Re-encode at lower volume (-3dB headroom)
Too quiet	Normalize audio before upload
Wrong format	Convert to MP3, WAV, or OGG

Next steps

Talk First

Control agent’s opening greeting

Ambient Noise

Add background sounds

Voice & Speech

Configure TTS voice

Inbound Calls

Set up incoming call handling

Documentation Index

​When to use pre-conversation media

​Configure pre-conversation media

​Configuration options

​Upload media files

​Call type behavior

​Troubleshooting

​Audio doesn’t play

​Audio quality issues

​Next steps