Sound Manager - CometChat Docs

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)

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:

Global config — Set on CometChatProvider via the config prop. Applies to all components.
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:

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

{/* 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`

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.

Custom Sound URLs

Replace default sounds with your own audio files:

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.

​Overview

​Sound Types

​Disabling & Customizing Sounds

​Global Config

​Component-Level Props (Override)

​Custom Sound URLs

​API Reference

​Static Methods

​Browser Autoplay Policy

​SSR Safety

Overview

Sound Types

Disabling & Customizing Sounds

Global Config

Component-Level Props (Override)

Custom Sound URLs

API Reference

Static Methods

Browser Autoplay Policy

SSR Safety