Call Buttons - CometChat Docs

AI Integration Quick Reference

{
  "component": "CometChatCallButtons",
  "package": "@cometchat/chat-uikit-react",
  "import": "import { CometChatCallButtons } from \"@cometchat/chat-uikit-react\";",
  "cssImport": "import \"@cometchat/chat-uikit-react/css-variables.css\";",
  "description": "Voice and video call initiation buttons for user or group conversations.",
  "cssRootClass": ".cometchat-call-button",
  "primaryOutput": {
    "description": "Initiates calls via SDK, emits CometChatCallEvents"
  },
  "props": {
    "data": {
      "user": {
        "type": "CometChat.User",
        "default": "undefined",
        "note": "Pass either user or group, not both"
      },
      "group": {
        "type": "CometChat.Group",
        "default": "undefined",
        "note": "Pass either user or group, not both"
      }
    },
    "callbacks": {
      "onError": "((error: CometChat.CometChatException) => void) | null",
      "onVoiceCallClick": "(user?: CometChat.User, group?: CometChat.Group) => void",
      "onVideoCallClick": "(user?: CometChat.User, group?: CometChat.Group) => void"
    },
    "visibility": {
      "hideVoiceCallButton": { "type": "boolean", "default": false },
      "hideVideoCallButton": { "type": "boolean", "default": false }
    },
    "configuration": {
      "callSettingsBuilder": "(isAudioOnlyCall: boolean, user?: CometChat.User, group?: CometChat.Group) => typeof CometChatUIKitCalls.CallSettingsBuilder",
      "outgoingCallConfiguration": {
        "type": "OutgoingCallConfiguration",
        "default": "new OutgoingCallConfiguration({})",
        "properties": {
          "disableSoundForCalls": "boolean",
          "customSoundForCalls": "string",
          "onError": "(error: CometChat.CometChatException) => void",
          "onCallCanceled": "Function",
          "titleView": "(call: CometChat.Call) => JSX.Element",
          "subtitleView": "(call: CometChat.Call) => JSX.Element",
          "avatarView": "(call: CometChat.Call) => JSX.Element",
          "cancelButtonView": "(call: CometChat.Call) => JSX.Element"
        }
      }
    }
  },
  "events": [
    {
      "name": "CometChatCallEvents.ccOutgoingCall",
      "payload": "CometChat.Call",
      "description": "Call initiated"
    },
    {
      "name": "CometChatCallEvents.ccCallRejected",
      "payload": "CometChat.Call",
      "description": "Call rejected/cancelled"
    },
    {
      "name": "CometChatCallEvents.ccCallEnded",
      "payload": "CometChat.Call",
      "description": "Call session ends"
    },
    {
      "name": "CometChatMessageEvents.ccMessageSent",
      "payload": "IMessages",
      "description": "Group call message sent"
    }
  ],
  "sdkListeners": [
    "onIncomingCallReceived",
    "onIncomingCallCancelled",
    "onOutgoingCallRejected",
    "onOutgoingCallAccepted"
  ],
  "compositionExample": {
    "description": "Standalone call buttons or embedded in MessageHeader auxiliary view",
    "components": ["CometChatCallButtons", "CometChatOutgoingCall", "CometChatOngoingCall"],
    "flow": "user/group prop -> click button -> SDK initiateCall -> CometChatOutgoingCall overlay -> onOutgoingCallAccepted -> CometChatOngoingCall"
  }
}

Where It Fits

CometChatCallButtons renders voice and video call buttons. Pass a user for 1-on-1 calls or a group for group calls. Typically embedded in CometChatMessageHeader’s auxiliary view or used standalone. The component handles call initiation, renders CometChatOutgoingCall internally, and manages the full call lifecycle.

import { useState, useEffect } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatCallButtons } from "@cometchat/chat-uikit-react";
import "@cometchat/chat-uikit-react/css-variables.css";

function CallButtonsDemo() {
  const [chatUser, setChatUser] = useState<CometChat.User>();

  useEffect(() => {
    CometChat.getUser("uid").then((user) => setChatUser(user));
  }, []);

  return chatUser ? <CometChatCallButtons user={chatUser} /> : null;
}

export default CallButtonsDemo;

Minimal Render

import { CometChatCallButtons } from "@cometchat/chat-uikit-react";
import "@cometchat/chat-uikit-react/css-variables.css";

function CallButtonsMinimal() {
  return <CometChatCallButtons user={chatUser} />;
}

Root CSS class: .cometchat-call-button

Actions and Events

Callback Props

onVoiceCallClick

Overrides the default voice call initiation behavior. When set, clicking the voice button invokes this callback instead of initiating a call via the SDK.

import { useState, useEffect } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatCallButtons } from "@cometchat/chat-uikit-react";

function CallButtonsVoiceOverride() {
  const [chatUser, setChatUser] = useState<CometChat.User>();

  useEffect(() => {
    CometChat.getUser("uid").then((user) => setChatUser(user));
  }, []);

  return (
    <CometChatCallButtons
      user={chatUser}
      onVoiceCallClick={() => {
        console.log("Custom voice call logic");
      }}
    />
  );
}

onVideoCallClick

Overrides the default video call initiation behavior.

import { useState, useEffect } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatCallButtons } from "@cometchat/chat-uikit-react";

function CallButtonsVideoOverride() {
  const [chatUser, setChatUser] = useState<CometChat.User>();

  useEffect(() => {
    CometChat.getUser("uid").then((user) => setChatUser(user));
  }, []);

  return (
    <CometChatCallButtons
      user={chatUser}
      onVideoCallClick={() => {
        console.log("Custom video call logic");
      }}
    />
  );
}

onError

Fires on internal errors during call initiation.

import { CometChatCallButtons } from "@cometchat/chat-uikit-react";
import { CometChat } from "@cometchat/chat-sdk-javascript";

function CallButtonsWithError() {
  return (
    <CometChatCallButtons
      user={chatUser}
      onError={(error: CometChat.CometChatException) => {
        console.error("CallButtons error:", error);
      }}
    />
  );
}

Global UI Events

CometChatCallEvents emits call lifecycle events subscribable from anywhere.

Event	Fires when	Payload
`ccOutgoingCall`	User initiates a voice/video call	`CometChat.Call`
`ccCallRejected`	Initiated call is rejected/cancelled	`CometChat.Call`
`ccCallEnded`	Call session ends	`CometChat.Call`

import { useEffect } from "react";
import { CometChatCallEvents } from "@cometchat/chat-uikit-react";
import { CometChat } from "@cometchat/chat-sdk-javascript";

function useCallButtonEvents() {
  useEffect(() => {
    const outgoingSub = CometChatCallEvents.ccOutgoingCall.subscribe(
      (call: CometChat.Call) => {
        console.log("Outgoing call:", call.getSessionId());
      }
    );
    const rejectedSub = CometChatCallEvents.ccCallRejected.subscribe(
      (call: CometChat.Call) => {
        console.log("Call rejected:", call.getSessionId());
      }
    );
    const endedSub = CometChatCallEvents.ccCallEnded.subscribe(
      (call: CometChat.Call) => {
        console.log("Call ended:", call.getSessionId());
      }
    );

    return () => {
      outgoingSub?.unsubscribe();
      rejectedSub?.unsubscribe();
      endedSub?.unsubscribe();
    };
  }, []);
}

SDK Events (Real-Time, Automatic)

The component attaches SDK call listeners internally:

SDK Listener	Internal behavior
`onIncomingCallReceived`	Disables call buttons to prevent concurrent calls
`onIncomingCallCancelled`	Re-enables call buttons
`onOutgoingCallRejected`	Hides outgoing call screen, re-enables buttons
`onOutgoingCallAccepted`	Transitions to ongoing call screen

Configuring the Outgoing Call Sub-Component

CometChatCallButtons renders CometChatOutgoingCall internally. Customize it via outgoingCallConfiguration.

import { CometChatCallButtons, OutgoingCallConfiguration } from "@cometchat/chat-uikit-react";

function CallButtonsCustomOutgoing() {
  return (
    <CometChatCallButtons
      user={chatUser}
      outgoingCallConfiguration={
        new OutgoingCallConfiguration({
          disableSoundForCalls: true,
          titleView: (call) => <div>{call.getCallReceiver().getName()}</div>,
        })
      }
    />
  );
}

OutgoingCallConfiguration properties:

Property	Type	Description
`disableSoundForCalls`	`boolean`	Disables outgoing call ringtone
`customSoundForCalls`	`string`	Custom ringtone URL
`onError`	`(error: CometChat.CometChatException) => void`	Error callback
`onCallCanceled`	`Function`	Cancel button callback
`titleView`	`(call: CometChat.Call) => JSX.Element`	Custom title
`subtitleView`	`(call: CometChat.Call) => JSX.Element`	Custom subtitle
`avatarView`	`(call: CometChat.Call) => JSX.Element`	Custom avatar
`cancelButtonView`	`(call: CometChat.Call) => JSX.Element`	Custom cancel button

Refer to CometChatOutgoingCall for details on each view slot.

Call Settings

Customize the calling experience via callSettingsBuilder.

import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatCallButtons, CometChatUIKitCalls } from "@cometchat/chat-uikit-react";

function CallButtonsCustomSettings() {
  return (
    <CometChatCallButtons
      user={chatUser}
      callSettingsBuilder={(isAudioOnlyCall, user, group) =>
        new CometChatUIKitCalls.CallSettingsBuilder()
          .enableDefaultLayout(true)
          .setIsAudioOnlyCall(isAudioOnlyCall)
      }
    />
  );
}

Common Patterns

Voice-only call button

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

function VoiceOnlyCallButtons() {
  return <CometChatCallButtons user={chatUser} hideVideoCallButton={true} />;
}

Group call buttons

import { useState, useEffect } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatCallButtons } from "@cometchat/chat-uikit-react";

function GroupCallButtons() {
  const [group, setGroup] = useState<CometChat.Group>();

  useEffect(() => {
    CometChat.getGroup("guid").then((g) => setGroup(g));
  }, []);

  return group ? <CometChatCallButtons group={group} /> : null;
}

CSS Architecture

The component uses CSS custom properties (design tokens) defined in @cometchat/chat-uikit-react/css-variables.css. The cascade:

Global tokens set on the .cometchat root wrapper.
Component CSS (.cometchat-call-button) consumes these tokens via var().
Overrides target .cometchat-call-button descendant selectors.

Key Selectors

Target	Selector
Root	`.cometchat-call-button`
Voice button wrapper	`.cometchat-call-button__voice`
Video button wrapper	`.cometchat-call-button__video`
Button element	`.cometchat-call-button .cometchat-button`
Button icon	`.cometchat-call-button .cometchat-button__icon`
Outgoing call backdrop	`.cometchat-outgoing-call__backdrop`

Example: Themed call buttons

.cometchat-call-button {
  display: flex;
  padding: 8px 16px;
  justify-content: center;
  align-items: center;
  background: #fff;
}

.cometchat .cometchat-button {
  border-radius: 8px;
  border: 1px solid #e8e8e8;
  background: #edeafa;
}

.cometchat-call-button .cometchat-call-button__video .cometchat-button__icon,
.cometchat-call-button .cometchat-call-button__voice .cometchat-button__icon {
  background-color: #6852d6;
}

Customization Matrix

What to change	Where	Property/API	Example
Override call initiation	Component props	`onVoiceCallClick` / `onVideoCallClick`	`onVoiceCallClick={() => customCall()}`
Hide a call button	Component props	`hideVoiceCallButton` / `hideVideoCallButton`	`hideVideoCallButton={true}`
Customize outgoing call UI	Component props	`outgoingCallConfiguration`	`outgoingCallConfiguration={new OutgoingCallConfiguration({...})}`
Customize call settings	Component props	`callSettingsBuilder`	`callSettingsBuilder={(audio) => builder}`
Change colors, fonts, spacing	Global CSS	Target `.cometchat-call-button` class	`.cometchat-call-button .cometchat-button__icon { background: red; }`

Props

All props are optional. Sorted alphabetically.

callSettingsBuilder

Builder function for customizing call settings.


Type	`(isAudioOnlyCall: boolean, user?: CometChat.User, group?: CometChat.Group) => typeof CometChatUIKitCalls.CallSettingsBuilder`
Default	`undefined`

group

The group for group call buttons. Pass either user or group, not both.


Type	`CometChat.Group`
Default	`undefined`

hideVideoCallButton

Hides the video call button.


Type	`boolean`
Default	`false`

hideVoiceCallButton

Hides the voice call button.


Type	`boolean`
Default	`false`

onError

Callback fired when the component encounters an error.


Type	`((error: CometChat.CometChatException) => void) \| null`
Default	`undefined`

outgoingCallConfiguration

Configuration object for the internal CometChatOutgoingCall sub-component.


Type	`OutgoingCallConfiguration`
Default	`new OutgoingCallConfiguration({})`

See Configuring the Outgoing Call Sub-Component for properties.

user

The user for 1-on-1 call buttons. Pass either user or group, not both.


Type	`CometChat.User`
Default	`undefined`

Events

Event	Payload	Fires when
`CometChatCallEvents.ccOutgoingCall`	`CometChat.Call`	Call initiated
`CometChatCallEvents.ccCallRejected`	`CometChat.Call`	Call rejected/cancelled
`CometChatCallEvents.ccCallEnded`	`CometChat.Call`	Call session ends
`CometChatMessageEvents.ccMessageSent`	`IMessages`	Group call message sent

All call events are Subject<CometChat.Call> from RxJS. Subscribe with .subscribe(), unsubscribe with the returned subscription’s .unsubscribe().

CSS Selectors

Target	Selector
Root	`.cometchat-call-button`
Voice button wrapper	`.cometchat-call-button__voice`
Video button wrapper	`.cometchat-call-button__video`
Button element	`.cometchat-call-button .cometchat-button`
Button icon	`.cometchat-call-button .cometchat-button__icon`
Outgoing call backdrop	`.cometchat-outgoing-call__backdrop`

Documentation Index

​Where It Fits

​Minimal Render

​Actions and Events

​Callback Props

​onVoiceCallClick

​onVideoCallClick

​onError

​Global UI Events

​SDK Events (Real-Time, Automatic)

​Configuring the Outgoing Call Sub-Component

​Call Settings

​Common Patterns

​Voice-only call button

​Group call buttons

​CSS Architecture

​Key Selectors

​Example: Themed call buttons

​Customization Matrix

​Props

​callSettingsBuilder

​group

​hideVideoCallButton

​hideVoiceCallButton

​onError

​outgoingCallConfiguration

​user

​Events

​CSS Selectors

Where It Fits

Minimal Render

Actions and Events

Callback Props

onVoiceCallClick

onVideoCallClick

onError

Global UI Events

SDK Events (Real-Time, Automatic)

Configuring the Outgoing Call Sub-Component

Call Settings

Common Patterns

Voice-only call button

Group call buttons

CSS Architecture

Key Selectors

Example: Themed call buttons

Customization Matrix

Props

callSettingsBuilder

group

hideVideoCallButton

hideVoiceCallButton

onError

outgoingCallConfiguration

user

Events

CSS Selectors