Incoming Call - CometChat Docs

AI Integration Quick Reference

{
  "component": "CometChatIncomingCall",
  "package": "@cometchat/chat-uikit-react",
  "import": "import { CometChatIncomingCall } from \"@cometchat/chat-uikit-react\";",
  "description": "Displays an incoming call notification with caller info, accept/decline buttons, and transitions to the ongoing call screen.",
  "cssRootClass": ".cometchat-incoming-call",
  "primaryOutput": {
    "prop": "onAccept",
    "type": "(call: CometChat.Call) => void"
  },
  "props": {
    "callbacks": {
      "onAccept": "(call: CometChat.Call) => void",
      "onDecline": "(call: CometChat.Call) => void",
      "onCallEnded": "() => void",
      "onError": "((error: CometChat.CometChatException) => void) | null"
    },
    "sound": {
      "disableSoundForCalls": { "type": "boolean", "default": false },
      "customSoundForCalls": { "type": "string", "default": "built-in" }
    },
    "configuration": {
      "callSettingsBuilder": {
        "type": "(call: CometChat.Call) => any",
        "default": "undefined",
        "note": "Custom call settings for the ongoing call session after accepting"
      }
    },
    "viewSlots": {
      "itemView": "(call: CometChat.Call) => ReactNode",
      "leadingView": "(call: CometChat.Call) => ReactNode",
      "titleView": "(call: CometChat.Call) => ReactNode",
      "subtitleView": "(call: CometChat.Call) => ReactNode",
      "trailingView": "(call: CometChat.Call) => ReactNode"
    }
  },
  "events": [
    {
      "name": "ui:call/rejected",
      "payload": "{ call }",
      "description": "Call declined by user"
    },
    {
      "name": "ui:call/ended",
      "payload": "{}",
      "description": "Ongoing call ended"
    }
  ],
  "sdkListeners": [
    "onIncomingCallReceived",
    "onIncomingCallCancelled",
    "onOutgoingCallAccepted",
    "onOutgoingCallRejected"
  ],
  "types": {
    "CometChatDateFormatConfig": {
      "today": "string | undefined",
      "yesterday": "string | undefined",
      "lastWeek": "string | undefined",
      "otherDays": "string | undefined"
    }
  }
}

Overview

CometChatIncomingCall is a full-screen notification component that automatically listens for incoming calls via the CometChat SDK CallListener. When an incoming call is detected, it displays the caller’s avatar, name, and call type (Voice/Video) with accept and decline buttons.

Live Preview — interact with the default incoming call screen.Open in Storybook ↗

The component handles:

Automatic detection of incoming calls via SDK CallListener
Caller avatar, name, and call type display (Voice/Video)
Accept button — transitions to CometChatOngoingCall internally
Decline button — rejects the call via SDK
Incoming call sound playback (looping while notification is visible)
Self-managed visibility (renders nothing when no incoming call is active)

Placement: Render CometChatIncomingCall at your app’s root level. It manages its own visibility internally and only appears when an incoming call is detected.

Note: Call initiation buttons are provided by the standalone CometChatCallButtons component (also rendered automatically inside CometChatMessageHeader). CometChatIncomingCall is separate — it handles the incoming call notification flow.

Usage

Flat API

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

function App() {
  return (
    <div>
      {/* Your app content */}
      <CometChatIncomingCall
        onAccept={(call) => {
          console.log("Call accepted:", call.getSessionId());
        }}
        onDecline={(call) => {
          console.log("Call declined:", call.getSessionId());
        }}
        onCallEnded={() => {
          console.log("Call ended");
        }}
      />
    </div>
  );
}

Full Layout Example

import {
  CometChatConversations,
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
  CometChatIncomingCall,
} from "@cometchat/chat-uikit-react";

function ChatApp() {
  return (
    <div style={{ display: "flex", height: "100vh" }}>
      <div style={{ width: 360 }}>
        <CometChatConversations onItemClick={handleConversationClick} />
      </div>
      <div style={{ flex: 1, display: "flex", flexDirection: "column" }}>
        <CometChatMessageHeader user={user} group={group} />
        <CometChatMessageList user={user} group={group} />
        <CometChatMessageComposer user={user} group={group} />
      </div>

      {/* Render at root level — manages its own visibility */}
      <CometChatIncomingCall />
    </div>
  );
}

Actions and Events

Callback Props

Prop	Signature	Fires when
`onAccept`	`(call: CometChat.Call) => void`	User clicks the accept button
`onDecline`	`(call: CometChat.Call) => void`	User clicks the decline button
`onCallEnded`	`() => void`	Ongoing call session ends
`onError`	`((error: CometChat.CometChatException) => void) \| null`	SDK error occurs

Events Emitted

UI events this component publishes:

Event	Payload	Fires when
`ui:call/rejected`	`{ call }`	Call declined by user
`ui:call/ended`	`{}`	Ongoing call ended

Events Received

This component does not subscribe to any UI events from other components.

SDK Listeners (Automatic)

These SDK CallListener callbacks are attached internally. The component updates its state automatically:

onIncomingCallReceived — shows the incoming call notification
onIncomingCallCancelled — hides the notification (caller cancelled)
onOutgoingCallAccepted — transitions to ongoing call screen
onOutgoingCallRejected — hides the notification (call rejected elsewhere)

Customization

View Props

Use view props to replace sections of the default UI while keeping the component’s behavior intact:

<CometChatIncomingCall
  leadingView={(call) => <MyCustomAvatar call={call} />}
  titleView={(call) => <span>{call.getSender().getName()}</span>}
  subtitleView={(call) => <span>Incoming {call.getType()} call</span>}
/>

Slot	Signature	Replaces
`itemView`	`(call: CometChat.Call) => ReactNode`	Entire call notification card
`leadingView`	`(call: CometChat.Call) => ReactNode`	Avatar section
`titleView`	`(call: CometChat.Call) => ReactNode`	Caller name
`subtitleView`	`(call: CometChat.Call) => ReactNode`	Call type label
`trailingView`	`(call: CometChat.Call) => ReactNode`	Trailing section

leadingView

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

function CustomLeadingIncoming() {
  return (
    <CometChatIncomingCall
      leadingView={(call: CometChat.Call) => (
        <CometChatAvatar.Root
          name={call.getCallInitiator()?.getName()}
          image={call.getCallInitiator()?.getAvatar()}
        >
          <CometChatAvatar.Image />
          <CometChatAvatar.Initials />
        </CometChatAvatar.Root>
      )}
    />
  );
}

titleView

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

function CustomTitleIncoming() {
  return (
    <CometChatIncomingCall
      titleView={(call: CometChat.Call) => (
        <div>{call.getCallInitiator()?.getName()}</div>
      )}
    />
  );
}

itemView

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

function CustomItemViewIncoming() {
  return (
    <CometChatIncomingCall
      itemView={(call: CometChat.Call) => (
        <div className="incoming-call__item">
          <CometChatAvatar.Root
            name={call.getCallInitiator()?.getName()}
            image={call.getCallInitiator()?.getAvatar()}
          >
            <CometChatAvatar.Image />
            <CometChatAvatar.Initials />
          </CometChatAvatar.Root>
          <div>{call.getCallInitiator()?.getName()}</div>
        </div>
      )}
    />
  );
}

CSS Styling

Override design tokens on the component selector:

.cometchat-incoming-call {
  --cometchat-background-color-01: #1a1a2e;
  --cometchat-text-color-primary: #ffffff;
}

.cometchat-incoming-call__button-accept {
  background: var(--cometchat-success-color);
}

.cometchat-incoming-call__button-decline {
  background: var(--cometchat-error-color);
}

Props

All props are optional.

onAccept

Custom accept handler. When provided, overrides the default CometChat.acceptCall behavior.


Type	`(call: CometChat.Call) => void`
Default	`undefined`

onDecline

Custom decline handler. When provided, overrides the default CometChat.rejectCall behavior.


Type	`(call: CometChat.Call) => void`
Default	`undefined`

onCallEnded

Callback when the ongoing call session ends and the call screen should close.


Type	`() => void`
Default	`undefined`

disableSoundForCalls

Disable the incoming call ringtone sound.


Type	`boolean`
Default	`false`

customSoundForCalls

Custom sound URL to play for incoming calls (replaces the built-in ringtone).


Type	`string`
Default	Built-in ringtone

callSettingsBuilder

Custom call settings builder for the ongoing call session after accepting. If not provided, the component uses default settings.


Type	`(call: CometChat.Call) => any`
Default	`undefined`

<CometChatIncomingCall
  callSettingsBuilder={(call) => {
    return new CometChat.CallSettingsBuilder()
      .enableDefaultLayout(true)
      .setIsAudioOnlyCall(call.getType() === "audio")
      .build();
  }}
/>

onError

Callback when an SDK error occurs.


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

itemView

Custom renderer for the entire incoming call notification card.


Type	`(call: CometChat.Call) => ReactNode`
Default	`undefined`

leadingView

Custom renderer for the avatar section.


Type	`(call: CometChat.Call) => ReactNode`
Default	`undefined`

titleView

Custom renderer for the caller name.


Type	`(call: CometChat.Call) => ReactNode`
Default	`undefined`

subtitleView

Custom renderer for the call type label (Voice/Video).


Type	`(call: CometChat.Call) => ReactNode`
Default	`undefined`

trailingView

Custom renderer for the trailing section.


Type	`(call: CometChat.Call) => ReactNode`
Default	`undefined`

className

Additional CSS class name applied to the root element.


Type	`string`
Default	`undefined`

CSS Selectors

Target	Selector
Root container	`.cometchat-incoming-call`
Info section	`.cometchat-incoming-call__info`
Avatar	`.cometchat-incoming-call__avatar`
Details container	`.cometchat-incoming-call__details`
Title	`.cometchat-incoming-call__title`
Subtitle	`.cometchat-incoming-call__subtitle`
Trailing section	`.cometchat-incoming-call__trailing`
Button group	`.cometchat-incoming-call__button-group`
Accept button	`.cometchat-incoming-call__button-accept`
Decline button	`.cometchat-incoming-call__button-decline`

Next Steps

Outgoing Call

Display the outgoing call screen while waiting for the receiver to answer

Call Logs

Browse call history and re-initiate calls

Theming

Customize colors, fonts, and spacing

​Overview

​Usage

​Flat API

​Full Layout Example

​Actions and Events

​Callback Props

​Events Emitted

​Events Received

​SDK Listeners (Automatic)

​Customization

​View Props

​leadingView

​titleView

​itemView

​CSS Styling

​Props

​onAccept

​onDecline

​onCallEnded

​disableSoundForCalls

​customSoundForCalls

​callSettingsBuilder

​onError

​itemView

​leadingView

​titleView

​subtitleView

​trailingView

​className

​CSS Selectors

​Next Steps

Outgoing Call

Call Logs

Theming

Overview

Usage

Flat API

Full Layout Example

Actions and Events

Callback Props

Events Emitted

Events Received

SDK Listeners (Automatic)

Customization

View Props

leadingView

titleView

itemView

CSS Styling

Props

onAccept

onDecline

onCallEnded

disableSoundForCalls

customSoundForCalls

callSettingsBuilder

onError

itemView

leadingView

titleView

subtitleView

trailingView

className

CSS Selectors

Next Steps