> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-rn-guide-message-privately.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.