Call Buttons - CometChat Docs

AI Agent Component Spec

{
  "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; }`

Accessibility

The voice and video call buttons are keyboard-focusable and activate on Enter/Space. Each button includes hover text (“Voice Call” / “Video Call”) for tooltip display. Buttons are disabled during active calls to prevent concurrent call initiation.

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`

​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

​Accessibility

​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

Accessibility

Props

callSettingsBuilder

group

hideVideoCallButton

hideVoiceCallButton

onError

outgoingCallConfiguration

user

Events

CSS Selectors