Customize Audio Notifications

Manage and customize audio cues for calls and messages using CometChatSoundManager

AI Agent Component Spec

{
  "package": "@cometchat/chat-uikit-react",
  "import": "import { CometChatSoundManager } from \"@cometchat/chat-uikit-react\";",
  "methods": {
    "play": "Play default or custom sound for an event",
    "pause": "Pause currently playing sound",
    "onIncomingMessage": "Play incoming message sound",
    "onOutgoingMessage": "Play outgoing message sound",
    "onIncomingCall": "Play incoming call sound (loops)",
    "onOutgoingCall": "Play outgoing call sound (loops)"
  },
  "soundEvents": ["incomingCall", "outgoingCall", "incomingMessage", "incomingMessageFromOther", "outgoingMessage"]
}

Overview

CometChatSoundManager is a helper class for managing audio cues in the UI Kit. Use it to play default sounds or custom audio files for calls and messages.

Time estimate: 5 minutes
Difficulty: Beginner

Prerequisites

• React.js integration completed

Steps

Step 1: Import the sound manager

import { CometChatSoundManager } from "@cometchat/chat-uikit-react";

Step 2: Play default sounds

Use the built-in sounds for common events:

// Play incoming call sound (loops until paused)
CometChatSoundManager.play(CometChatSoundManager.Sound.incomingCall);

// Play outgoing call sound (loops until paused)
CometChatSoundManager.play(CometChatSoundManager.Sound.outgoingCall);

// Play incoming message sound
CometChatSoundManager.play(CometChatSoundManager.Sound.incomingMessage);

// Play incoming message from another conversation
CometChatSoundManager.play(CometChatSoundManager.Sound.incomingMessageFromOther);

// Play outgoing message sound
CometChatSoundManager.play(CometChatSoundManager.Sound.outgoingMessage);

// Pause any playing sound
CometChatSoundManager.pause();

Step 3: Use custom sounds

Pass a custom audio file URL as the second argument:

// Custom incoming message sound
CometChatSoundManager.play(
  CometChatSoundManager.Sound.incomingMessage,
  "/sounds/custom-notification.mp3"
);

// Custom call ringtone
CometChatSoundManager.play(
  CometChatSoundManager.Sound.incomingCall,
  "/sounds/custom-ringtone.mp3"
);

Step 4: Use convenience methods

Direct methods for common scenarios:

// Incoming call (loops)
CometChatSoundManager.onIncomingCall();
CometChatSoundManager.onIncomingCall("/sounds/custom-ringtone.mp3");

// Outgoing call (loops)
CometChatSoundManager.onOutgoingCall();
CometChatSoundManager.onOutgoingCall("/sounds/custom-dialing.mp3");

// Messages
CometChatSoundManager.onIncomingMessage();
CometChatSoundManager.onIncomingOtherMessage();
CometChatSoundManager.onOutgoingMessage("/sounds/sent.mp3");

Step 5: Check user interaction

Browsers require user interaction before playing audio. Check if the user has interacted:

if (CometChatSoundManager.hasInteracted()) {
  CometChatSoundManager.play(CometChatSoundManager.Sound.incomingMessage);
} else {
  console.log("User hasn't interacted yet - sound won't play");
}

Complete Example

import { useEffect } from "react";
import { 
  CometChatSoundManager,
  CometChatCallEvents,
  CometChatMessageEvents,
} from "@cometchat/chat-uikit-react";

function CustomSoundHandler() {
  useEffect(() => {
    // Custom sounds for calls
    const incomingCallSub = CometChatCallEvents.ccOutgoingCall.subscribe(() => {
      CometChatSoundManager.onOutgoingCall("/sounds/dialing.mp3");
    });

    const callEndedSub = CometChatCallEvents.ccCallEnded.subscribe(() => {
      CometChatSoundManager.pause();
    });

    // Custom sounds for messages
    const messageSentSub = CometChatMessageEvents.ccMessageSent.subscribe(() => {
      CometChatSoundManager.play(
        CometChatSoundManager.Sound.outgoingMessage,
        "/sounds/message-sent.mp3"
      );
    });

    return () => {
      incomingCallSub?.unsubscribe();
      callEndedSub?.unsubscribe();
      messageSentSub?.unsubscribe();
    };
  }, []);

  return null; // This is a behavior-only component
}

export default CustomSoundHandler;

Sound Events Reference

Event	When it plays	Loops
incomingCall	Incoming call detected	Yes
outgoingCall	Outgoing call initiated	Yes
incomingMessage	New message in current conversation	No
incomingMessageFromOther	New message from different conversation	No
outgoingMessage	Message sent	No

Methods Reference

Method	Parameters	Description
play(sound, customSound?)	Sound event key, optional URL	Play sound
pause()	None	Stop current sound
onIncomingCall(customSound?)	Optional URL	Play incoming call
onOutgoingCall(customSound?)	Optional URL	Play outgoing call
onIncomingMessage(customSound?)	Optional URL	Play incoming message
onIncomingOtherMessage(customSound?)	Optional URL	Play other message
onOutgoingMessage(customSound?)	Optional URL	Play outgoing message
hasInteracted()	None	Check user interaction

Common Issues

Browser autoplay policies require user interaction before audio can play. The first sound may be blocked until the user clicks or taps somewhere on the page.

Issue	Solution
Sound not playing	Check hasInteracted() - user may need to interact first
Sound keeps looping	Call pause() when call ends
Custom sound not found	Verify the audio file path is correct

Next Steps

Events

Subscribe to UI Kit events

Voice & Video

Implement calling features

Related Guides

Voice & Video Calling

Messaging