Message Structure and Hierarchy

Understand the message categories, types, and hierarchy in the CometChat JavaScript SDK including text, media, custom, action, interactive, 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)
• interactive → form, card, customInteractive
• action → groupMember (joined/left/kicked/banned), message (edited/deleted)
• call → audio, video

Every message in CometChat belongs to a category and has a specific type. Understanding this hierarchy helps you handle different message types correctly in your application.

Message Hierarchy

Categories Overview

Category	Types	Description
message	text, image, video, audio, file	Standard user messages
custom	Developer-defined	Custom data (location, polls, etc.)
interactive	form, card, customInteractive	Messages with actionable UI elements
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:

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;
}

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:
    const actionMsg = message as CometChat.Action;
    console.log("Action:", actionMsg.getAction());
    break;
  case CometChat.CATEGORY_CALL:
    const callMsg = message as CometChat.Call;
    console.log("Call status:", callMsg.getStatus());
    break;
}

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 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.

Interactive Category

Interactive messages contain actionable UI elements that users can interact with directly in the chat:

Type	Description
form	Embedded form with input fields
card	Card with buttons and actions
customInteractive	Custom interactive elements

See Interactive Messages for implementation details.

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 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

Interactive Messages

Send messages with embedded forms and buttons

Additional Filtering

Advanced message filtering with RequestBuilder