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

# Play Audio Before Conversations Start

> Play a recorded message or audio file immediately when calls connect, before your AI agent speaks. Use for compliance disclosures, greetings, or branded intros.

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

<Tabs>
  <Tab title="Dashboard">
    1. Open your agent's configuration
    2. Navigate to the **Features** tab
    3. Find **Pre-Conversation Media** and toggle it on
    4. Select a media file from your uploaded files
    5. Enable for specific call types (inbound, outbound, web)
    6. Save your agent
  </Tab>

  <Tab title="API">
    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    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
        }
      })
    });
    ```
  </Tab>
</Tabs>

***

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

<Tabs>
  <Tab title="Dashboard">
    1. Navigate to **Media** in the sidebar
    2. Click **Upload** and select your audio file
    3. The filename will appear in the pre-conversation media dropdown
  </Tab>

  <Tab title="API">
    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    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
    ```
  </Tab>
</Tabs>

**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        |

<Accordion title="Example: Inbound-only compliance">
  ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  preConversationMedia: {
    isEnabled: true,
    mediaFilename: 'recording-notice.mp3',
    enabledForInbound: true,
    enabledForOutbound: false,  // Outbound calls skip the intro
    enabledForWebCall: false
  }
  ```
</Accordion>

<Accordion title="Example: All call types">
  ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  preConversationMedia: {
    isEnabled: true,
    mediaFilename: 'welcome-message.mp3',
    enabledForInbound: true,
    enabledForOutbound: true,
    enabledForWebCall: true
  }
  ```
</Accordion>

***

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

<CardGroup cols={2}>
  <Card title="Talk First" icon="message" href="/docs/advanced-features/talk-first">
    Control agent's opening greeting
  </Card>

  <Card title="Ambient Noise" icon="volume-high" href="/docs/advanced-features/ambient-noise">
    Add background sounds
  </Card>

  <Card title="Voice & Speech" icon="microphone" href="/docs/create/voice-and-speech">
    Configure TTS voice
  </Card>

  <Card title="Inbound Calls" icon="phone-arrow-down-left" href="/docs/deploy/inbound-calls">
    Set up incoming call handling
  </Card>
</CardGroup>