Sound Manager

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

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:

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:

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