> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-agent-native-development.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Sound Manager

> Play notification sounds for incoming/outgoing messages and calls with custom sound URL support.

<Accordion title="AI Integration Quick Reference">
  | Field | Value |
  | - | - |
  | Class | `CometChatSoundManager` |
  | Package | `@cometchat/chat-uikit-react` |
  | Sound types | `incomingMessage`, `outgoingMessage`, `incomingMessageFromOther`, `incomingCall`, `outgoingCall` |
  | Custom sounds | Pass URL as second argument: `CometChatSoundManager.play('incomingMessage', '/my-sound.mp3')` |
  | Global config | `disableSoundForMessages`, `customSoundForMessages`, `disableSoundForCalls`, `customSoundForCalls` via `config` prop on `CometChatProvider` |
  | Component override | Same props on individual components (props take precedence over global config) |
</Accordion>

## Overview

`CometChatSoundManager` handles audio notifications for chat events. It plays sounds when messages are sent/received and when calls are initiated/received. Components use it internally — you don't need to call it manually unless you want custom behavior.

***

## Sound Types

| Type | When it plays | Loops |
| - | - | - |
| `outgoingMessage` | User sends a message | No |
| `incomingMessage` | Message received in the active conversation | No |
| `incomingMessageFromOther` | Message received in a different conversation | No |
| `incomingCall` | Incoming call notification | Yes |
| `outgoingCall` | Outgoing call ringing | Yes |

***

## Disabling & Customizing Sounds

Sound behavior can be configured at two levels:

1. **Global config** — Set on `CometChatProvider` via the `config` prop. Applies to all components.
2. **Component props** — Set directly on individual components. Takes precedence over global config.

### Global Config

Use the `config` prop on `CometChatProvider` to control sound behavior across all components:

```tsx theme={null}
<CometChatProvider
  config={{
    disableSoundForMessages: true,
    customSoundForMessages: "/sounds/custom-message.mp3",
    disableSoundForCalls: true,
    customSoundForCalls: "/sounds/custom-ringtone.mp3",
  }}
>
  <MyChatApp />
</CometChatProvider>
```

| Property | Type | Description |
| - | - | - |
| `disableSoundForMessages` | `boolean` | Disable sound for incoming messages across all components. Default: `false` |
| `customSoundForMessages` | `string` | Custom sound URL for incoming message notifications |
| `disableSoundForCalls` | `boolean` | Disable sound for incoming/outgoing calls. Default: `false` |
| `customSoundForCalls` | `string` | Custom sound URL for calls |

### Component-Level Props (Override)

Individual components accept the same props. When set, they override the global config for that component only.

```tsx theme={null}
{/* Override global config for this specific component */}
<CometChatConversations
  disableSoundForMessages={false}
  customSoundForMessages="/sounds/conversation-alert.mp3"
/>

<CometChatIncomingCall
  disableSoundForCalls={false}
  customSoundForCalls="/sounds/incoming-ring.mp3"
/>
```

**Components that accept sound props:**

| Component | Props |
| - | - |
| `CometChatConversations` | `disableSoundForMessages`, `customSoundForMessages` |
| `CometChatMessageList` | `disableSoundForMessages`, `customSoundForMessages` |
| `CometChatMessageComposer` | `disableSoundForMessage`, `customSoundForMessage` |
| `CometChatIncomingCall` | `disableSoundForCalls`, `customSoundForCalls` |
| `CometChatOutgoingCall` | `disableSoundForCalls`, `customSoundForCalls` |

<Note>
  Component-level props always take precedence over the global config. If a prop is not set on a component, it falls back to the global config value.
</Note>

***

## Custom Sound URLs

Replace default sounds with your own audio files:

```tsx theme={null}
import { CometChatSoundManager } from "@cometchat/chat-uikit-react";

// Play a custom notification sound
CometChatSoundManager.play("incomingMessage", "/sounds/notification.mp3");

// Or use convenience methods
CometChatSoundManager.onIncomingMessage("/sounds/notification.mp3");
CometChatSoundManager.onOutgoingMessage("/sounds/sent.mp3");
```

***

## API Reference

### Static Methods

| Method | Signature | Description |
| - | - | - |
| `play` | `(sound: SoundType, customUrl?: string) => void` | Play a sound (with optional custom URL) |
| `pause` | `() => void` | Stop the currently playing sound |
| `onOutgoingMessage` | `(customUrl?: string) => void` | Play outgoing message sound |
| `onIncomingMessage` | `(customUrl?: string) => void` | Play incoming message sound |
| `onIncomingOtherMessage` | `(customUrl?: string) => void` | Play incoming message from other conversation |
| `onIncomingCall` | `(customUrl?: string) => void` | Play incoming call sound (loops) |
| `onOutgoingCall` | `(customUrl?: string) => void` | Play outgoing call sound (loops) |

***

## Browser Autoplay Policy

Browsers require user interaction before playing audio. `CometChatSoundManager` checks `navigator.userActivation` before attempting playback. If the user hasn't interacted with the page yet, sounds are silently skipped.

***

## SSR Safety

All `Audio` API usage is guarded behind `typeof Audio !== 'undefined'` checks. The sound manager is safe to import in server-side rendering environments — it simply no-ops when `Audio` is unavailable.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.