Message Structure & Hierarchy

Understanding message categories, types, and properties in CometChat

Quick Reference for AI Agents & Developers

// Message categories
CometChat.CATEGORY_MESSAGE      // text, image, video, audio, file
CometChat.CATEGORY_CUSTOM       // custom types you define
CometChat.CATEGORY_ACTION       // system events (join, leave, kick)
CometChat.CATEGORY_CALL         // audio, video calls
CometChat.CATEGORY_INTERACTIVE  // form, card, customInteractive

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

if (category === CometChat.CATEGORY_MESSAGE) {
  if (type === CometChat.MESSAGE_TYPE.TEXT) {
    console.log(message.getText());
  }
}

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

Message Hierarchy

Categories Overview

Category	Description	Types
message	Standard chat messages	text, image, video, audio, file
custom	Developer-defined messages	Any custom type
interactive	Interactive UI elements	form, card, customInteractive
action	System-generated events	groupMember, message
call	Call-related messages	audio, video

---

Message Category

Standard messages for text and media content.

Type	Description	Use Case
text	Plain text message	Chat messages
image	Image attachment	Photo sharing
video	Video attachment	Video sharing
audio	Audio attachment	Voice messages
file	File attachment	Document sharing

JavaScript

// Check message category and type
if (message.getCategory() === CometChat.CATEGORY_MESSAGE) {
  switch (message.getType()) {
    case CometChat.MESSAGE_TYPE.TEXT:
      console.log("Text:", message.getText());
      break;
    case CometChat.MESSAGE_TYPE.IMAGE:
    case CometChat.MESSAGE_TYPE.VIDEO:
    case CometChat.MESSAGE_TYPE.AUDIO:
    case CometChat.MESSAGE_TYPE.FILE:
      console.log("Media:", message.getAttachment());
      break;
  }
}

TypeScript

// Check message category and type
if (message.getCategory() === CometChat.CATEGORY_MESSAGE) {
  switch (message.getType()) {
    case CometChat.MESSAGE_TYPE.TEXT:
      const textMsg = message as CometChat.TextMessage;
      console.log("Text:", textMsg.getText());
      break;
    case CometChat.MESSAGE_TYPE.IMAGE:
    case CometChat.MESSAGE_TYPE.VIDEO:
    case CometChat.MESSAGE_TYPE.AUDIO:
    case CometChat.MESSAGE_TYPE.FILE:
      const mediaMsg = message as CometChat.MediaMessage;
      console.log("Media:", mediaMsg.getAttachment());
      break;
  }
}

---

Custom Category

Custom messages allow you to send any data structure that doesn’t fit standard message types.

Custom messages have no predefined types. You define your own type string to identify different custom message formats.

Common Use Cases:

• Location sharing (type: "location")
• Polls (type: "poll")
• Product cards (type: "product")
• Meeting invites (type: "meeting")

JavaScript

// Send custom location message
const customMessage = new CometChat.CustomMessage(
  receiverID,
  CometChat.RECEIVER_TYPE.USER,
  "location",  // Your custom type
  {
    latitude: 37.7749,
    longitude: -122.4194,
    address: "San Francisco, CA"
  }
);

await CometChat.sendCustomMessage(customMessage);

// Handle received custom message
if (message.getCategory() === CometChat.CATEGORY_CUSTOM) {
  const type = message.getType();
  const data = message.getCustomData();
  
  if (type === "location") {
    console.log("Location:", data.latitude, data.longitude);
  }
}

TypeScript

// Send custom location message
const customMessage = new CometChat.CustomMessage(
  receiverID,
  CometChat.RECEIVER_TYPE.USER,
  "location",
  {
    latitude: 37.7749,
    longitude: -122.4194,
    address: "San Francisco, CA"
  }
);

await CometChat.sendCustomMessage(customMessage);

// Handle received custom message
if (message.getCategory() === CometChat.CATEGORY_CUSTOM) {
  const customMsg = message as CometChat.CustomMessage;
  const type = customMsg.getType();
  const data = customMsg.getCustomData() as { latitude: number; longitude: number };
  
  if (type === "location") {
    console.log("Location:", data.latitude, data.longitude);
  }
}

---

Interactive Category

Interactive messages contain UI elements users can interact with directly in the chat.

Type	Description	Use Case
form	Embedded form	Surveys, data collection
card	Interactive card	Product displays, previews
customInteractive	Custom interactive element	Any custom UI

For detailed implementation, see Interactive Messages.

---

Action Category

System-generated messages for group and message events.

Group Member Actions

Action	Description
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 scope was changed

Message Actions

Action	Description
edited	Message was edited
deleted	Message was deleted

JavaScript

// Handle action messages
if (message.getCategory() === CometChat.CATEGORY_ACTION) {
  const action = message.getAction();
  const actionBy = message.getActionBy();
  const actionOn = message.getActionOn();
  
  switch (action) {
    case CometChat.ACTION_TYPE.MEMBER_JOINED:
      console.log(`${actionOn.getName()} joined the group`);
      break;
    case CometChat.ACTION_TYPE.MEMBER_KICKED:
      console.log(`${actionOn.getName()} was kicked by ${actionBy.getName()}`);
      break;
    case CometChat.ACTION_TYPE.MEMBER_SCOPE_CHANGED:
      console.log(`${actionOn.getName()} scope changed to ${message.getNewScope()}`);
      break;
  }
}

TypeScript

// Handle action messages
if (message.getCategory() === CometChat.CATEGORY_ACTION) {
  const actionMsg = message as CometChat.Action;
  const action = actionMsg.getAction();
  const actionBy = actionMsg.getActionBy() as CometChat.User;
  const actionOn = actionMsg.getActionOn() as CometChat.User;
  
  switch (action) {
    case CometChat.ACTION_TYPE.MEMBER_JOINED:
      console.log(`${actionOn.getName()} joined the group`);
      break;
    case CometChat.ACTION_TYPE.MEMBER_KICKED:
      console.log(`${actionOn.getName()} was kicked by ${actionBy.getName()}`);
      break;
    case CometChat.ACTION_TYPE.MEMBER_SCOPE_CHANGED:
      console.log(`${actionOn.getName()} scope changed`);
      break;
  }
}

---

Call Category

Call-related messages with status tracking.

Type	Description
audio	Voice call
video	Video call

Call Status Values

Status	Description
initiated	Call started
ongoing	Call in progress
canceled	Caller cancelled
rejected	Receiver rejected
unanswered	No answer
busy	Receiver busy
ended	Call completed

JavaScript

// Handle call messages
if (message.getCategory() === CometChat.CATEGORY_CALL) {
  const callType = message.getType(); // "audio" or "video"
  const status = message.getStatus();
  
  switch (status) {
    case CometChat.CALL_STATUS.INITIATED:
      console.log(`${callType} call initiated`);
      break;
    case CometChat.CALL_STATUS.ONGOING:
      console.log("Call in progress");
      break;
    case CometChat.CALL_STATUS.ENDED:
      console.log("Call ended");
      break;
    case CometChat.CALL_STATUS.CANCELLED:
      console.log("Call cancelled");
      break;
    case CometChat.CALL_STATUS.REJECTED:
      console.log("Call rejected");
      break;
    case CometChat.CALL_STATUS.UNANSWERED:
      console.log("Call unanswered");
      break;
    case CometChat.CALL_STATUS.BUSY:
      console.log("User busy");
      break;
  }
}

TypeScript

// Handle call messages
if (message.getCategory() === CometChat.CATEGORY_CALL) {
  const callMsg = message as CometChat.Call;
  const callType = callMsg.getType();
  const status = callMsg.getStatus();
  
  switch (status) {
    case CometChat.CALL_STATUS.INITIATED:
      console.log(`${callType} call initiated`);
      break;
    case CometChat.CALL_STATUS.ONGOING:
      console.log("Call in progress");
      break;
    case CometChat.CALL_STATUS.ENDED:
      console.log("Call ended");
      break;
    // ... handle other statuses
  }
}

---

Complete Message Handler

JavaScript

function handleMessage(message) {
  const category = message.getCategory();
  
  switch (category) {
    case CometChat.CATEGORY_MESSAGE:
      handleStandardMessage(message);
      break;
    case CometChat.CATEGORY_CUSTOM:
      handleCustomMessage(message);
      break;
    case CometChat.CATEGORY_ACTION:
      handleActionMessage(message);
      break;
    case CometChat.CATEGORY_CALL:
      handleCallMessage(message);
      break;
    case CometChat.CATEGORY_INTERACTIVE:
      handleInteractiveMessage(message);
      break;
  }
}

TypeScript

function handleMessage(message: CometChat.BaseMessage): void {
  const category = message.getCategory();
  
  switch (category) {
    case CometChat.CATEGORY_MESSAGE:
      handleStandardMessage(message as CometChat.TextMessage | CometChat.MediaMessage);
      break;
    case CometChat.CATEGORY_CUSTOM:
      handleCustomMessage(message as CometChat.CustomMessage);
      break;
    case CometChat.CATEGORY_ACTION:
      handleActionMessage(message as CometChat.Action);
      break;
    case CometChat.CATEGORY_CALL:
      handleCallMessage(message as CometChat.Call);
      break;
    case CometChat.CATEGORY_INTERACTIVE:
      handleInteractiveMessage(message as CometChat.InteractiveMessage);
      break;
  }
}

Next Steps

Send Messages

Learn to send different message types

Interactive Messages

Build interactive chat experiences