Message Structure and Hierarchy

Understand the message categories, types, and hierarchy in the CometChat React Native SDK including text, media, custom, card, action, and call messages.

AI Integration Quick Reference

Message categories and types:

• message → text, image, video, audio, file
• custom → Developer-defined types (e.g., location, poll)
• card → CardMessage (receive-only rich cards)
• action → groupMember (joined/left/kicked/banned), message (edited/deleted)
• call → audio, video

Every message in CometChat belongs to a category (message, custom, card, action, call) and has a specific type within that category.

Message Hierarchy

Categories Overview

Category	Types	Description
message	text, image, video, audio, file	Standard user messages
custom	Developer-defined	Custom data (location, polls, etc.)
card	CardMessage	Receive-only rich, structured cards
action	groupMember, message	System-generated events
call	audio, video	Call-related messages

Checking Message Category and Type

Use getCategory() and getType() to determine how to handle a received message:

TypeScript

const category: string = message.getCategory();
const type: string = message.getType();

switch (category) {
  case CometChat.CATEGORY_MESSAGE:
    if (type === CometChat.MESSAGE_TYPE.TEXT) {
      const textMsg = message as CometChat.TextMessage;
      console.log("Text:", textMsg.getText());
    } else if (type === CometChat.MESSAGE_TYPE.IMAGE) {
      const mediaMsg = message as CometChat.MediaMessage;
      console.log("Image URL:", mediaMsg.getData().url);
    }
    break;
  case CometChat.CATEGORY_CUSTOM:
    const customMsg = message as CometChat.CustomMessage;
    console.log("Custom type:", type, "data:", customMsg.getData());
    break;
  case CometChat.CATEGORY_ACTION:
    console.log("Action:", message.getAction());
    break;
  case CometChat.CATEGORY_CALL:
    console.log("Call status:", message.getStatus());
    break;
}

JavaScript

const category = message.getCategory();
const type = message.getType();

switch (category) {
  case CometChat.CATEGORY_MESSAGE:
    if (type === CometChat.MESSAGE_TYPE.TEXT) {
      console.log("Text:", message.getText());
    } else if (type === CometChat.MESSAGE_TYPE.IMAGE) {
      console.log("Image URL:", message.getData().url);
    }
    break;
  case CometChat.CATEGORY_CUSTOM:
    console.log("Custom type:", type, "data:", message.getData());
    break;
  case CometChat.CATEGORY_ACTION:
    console.log("Action:", message.getAction());
    break;
  case CometChat.CATEGORY_CALL:
    console.log("Call status:", message.getStatus());
    break;
}

Standard Messages (message Category)

Messages with category message are standard user-sent messages:

Type	Description
text	Plain text message
image	Image attachment
video	Video attachment
audio	Audio attachment
file	File attachment

Custom Messages (custom Category)

Custom messages allow you to send data that doesn’t fit the default categories. You define your own type to identify the message (e.g., location, poll, sticker).

// Example: Sending a location as a custom message
const customMessage = new CometChat.CustomMessage(
  receiverID,
  CometChat.RECEIVER_TYPE.USER,
  "location",
  { latitude: 37.7749, longitude: -122.4194 }
);

See Send Message → Custom Messages for details.

Card Messages (card Category)

A message with category card is a CardMessage — a rich, structured card rendered from Card Schema JSON.

Card messages are receive-only: they cannot be sent from the SDK. They are created and sent exclusively via the Platform (REST) API or the Dashboard Bubble Builder, and delivered through the onCardMessageReceived callback of the MessageListener.

Method	Return Type	Description
getCard()	object	The raw Card Schema JSON payload. Pass it to the CometChatCardView renderer.
getText()	string	Preview text for notifications and the conversation list.
getFallbackText()	string	Fallback text used for accessibility or when the renderer fails.
getTags()	Array<string>	Tags associated with the message.

See Receive Messages → Card Messages and Campaigns → Card Messages for details.

Action Messages (action Category)

Action messages are system-generated events. They have a type and an action property:

Type: groupMember — Actions on group members:

• joined — Member joined the group
• left — Member left the group
• kicked — Member was kicked
• banned — Member was banned
• unbanned — Member was unbanned
• added — Member was added
• scopeChanged — Member’s scope was changed

Type: message — Actions on messages:

• edited — Message was edited
• deleted — Message was deleted

Call Messages (call Category)

Call messages track call events with types audio or video. The status property indicates the call state:

Status	Description
initiated	Call started
ongoing	Call accepted and in progress
canceled	Caller canceled
rejected	Receiver rejected
unanswered	No answer
busy	Receiver on another call
ended	Call completed

See Default Calling or Direct Calling for implementation.

---

Next Steps

Send Messages

Send text, media, and custom messages

Receive Messages

Listen for incoming messages in real time

Card Messages

Receive and render rich, structured card messages

Message Filtering

Advanced message filtering with RequestBuilder