Interactive Messages

Send and receive interactive messages with embedded forms, buttons, and other UI elements using the CometChat JavaScript SDK.

Quick Reference

Component	Description
InteractiveMessage	Message containing interactive UI elements (forms, buttons, etc.)
InteractionGoal	Defines the desired outcome of user interactions
Interaction	Represents a single user action on an interactive element

// Create and send an interactive form
const interactiveMessage = new CometChat.InteractiveMessage(
  receiverId,
  receiverType,
  "form",
  interactiveData
);
await CometChat.sendInteractiveMessage(interactiveMessage);

// Listen for interactive messages
CometChat.addMessageListener("LISTENER_ID", new CometChat.MessageListener({
  onInteractiveMessageReceived: (message) => console.log("Received:", message),
  onInteractionGoalCompleted: (receipt) => console.log("Goal completed:", receipt)
}));

Interactive messages embed UI elements like forms, buttons, and dropdowns directly within chat messages. Users can interact with these elements without leaving the conversation, enabling surveys, quick actions, and data collection.

InteractiveMessage

The InteractiveMessage class represents a message with embedded interactive content.

Parameter	Type	Description	Required
receiverId	string	UID of user or GUID of group	Yes
receiverType	string	CometChat.RECEIVER_TYPE.USER or GROUP	Yes
messageType	string	Type identifier (e.g., "form", "card")	Yes
interactiveData	Object	JSON structure defining the interactive elements	Yes
allowSenderInteraction	boolean	Whether sender can interact with the message	No (default: false)
interactionGoal	InteractionGoal	Defines when the interaction is considered complete	No (default: none)

Send an Interactive Message

Use sendInteractiveMessage() to send an interactive message.

JavaScript

let receiverId = "UID";
let receiverType = CometChat.RECEIVER_TYPE.USER;

let interactiveData = {
  title: "Survey",
  formFields: [
    {
      elementType: "textInput",
      elementId: "name",
      optional: false,
      label: "Name",
      placeholder: { text: "Enter your name" }
    },
    {
      elementType: "textInput",
      elementId: "age",
      optional: true,
      label: "Age",
      maxLines: 1,
      placeholder: { text: "Enter your age" }
    },
    {
      elementType: "dropdown",
      elementId: "gender",
      optional: false,
      label: "Gender",
      defaultValue: "male",
      options: [
        { label: "Male", value: "male" },
        { label: "Female", value: "female" }
      ]
    },
    {
      elementType: "Select",
      elementId: "interests",
      optional: true,
      label: "Interests",
      defaultValue: ["tech"],
      options: [
        { label: "Technology", value: "tech" },
        { label: "Sports", value: "sports" },
        { label: "Music", value: "music" }
      ]
    }
  ],
  submitElement: {
    elementType: "button",
    elementId: "submitButton",
    buttonText: "Submit",
    disableAfterInteracted: true,
    action: {
      actionType: "urlNavigation",
      url: "https://www.cometchat.com/"
    }
  }
};

let interactiveMessage = new CometChat.InteractiveMessage(
  receiverId,
  receiverType,
  "form",
  interactiveData
);

CometChat.sendInteractiveMessage(interactiveMessage).then(
  (message) => {
    console.log("Interactive message sent successfully", message);
  },
  (error) => {
    console.log("Interactive message sending failed with error:", error);
  }
);

TypeScript

let receiverId: string = "UID";
let receiverType: string = CometChat.RECEIVER_TYPE.USER;

let interactiveData: Object = {
  title: "Survey",
  formFields: [
    {
      elementType: "textInput",
      elementId: "name",
      optional: false,
      label: "Name",
      placeholder: { text: "Enter your name" }
    },
    {
      elementType: "textInput",
      elementId: "age",
      optional: true,
      label: "Age",
      maxLines: 1,
      placeholder: { text: "Enter your age" }
    },
    {
      elementType: "dropdown",
      elementId: "gender",
      optional: false,
      label: "Gender",
      defaultValue: "male",
      options: [
        { label: "Male", value: "male" },
        { label: "Female", value: "female" }
      ]
    },
    {
      elementType: "Select",
      elementId: "interests",
      optional: true,
      label: "Interests",
      defaultValue: ["tech"],
      options: [
        { label: "Technology", value: "tech" },
        { label: "Sports", value: "sports" },
        { label: "Music", value: "music" }
      ]
    }
  ],
  submitElement: {
    elementType: "button",
    elementId: "submitButton",
    buttonText: "Submit",
    disableAfterInteracted: true,
    action: {
      actionType: "urlNavigation",
      url: "https://www.cometchat.com/"
    }
  }
};

let interactiveMessage: CometChat.InteractiveMessage = new CometChat.InteractiveMessage(
  receiverId,
  receiverType,
  "form",
  interactiveData
);

CometChat.sendInteractiveMessage(interactiveMessage).then(
  (message: CometChat.InteractiveMessage) => {
    console.log("Interactive message sent successfully", message);
  },
  (error: CometChat.CometChatException) => {
    console.log("Interactive message sending failed with error:", error);
  }
);

On success, sendInteractiveMessage() returns an InteractiveMessage object.

Field	Getter	Return Type	Description
interactiveData	getInteractiveData()	Object	The structured JSON data for the interactive element
interactionGoal	getInteractionGoal()	InteractionGoal	The intended outcome of interacting with the message
interactions	getInteractions()	Interaction[]	List of user interactions performed on the message
allowSenderInteraction	getIsSenderInteractionAllowed()	boolean	Whether the sender can interact with the message

Interactive Elements

The interactiveData object defines the UI elements. Common element types:

Element Type	Description
textInput	Single or multi-line text field
dropdown	Single-select dropdown menu
Select	Multi-select checkbox group
button	Clickable button with action

Text Input

{
  elementType: "textInput",
  elementId: "name",
  optional: false,
  label: "Name",
  maxLines: 1,  // Optional: limit to single line
  placeholder: { text: "Enter text here" }
}

Dropdown (Single Select)

{
  elementType: "dropdown",
  elementId: "country",
  optional: false,
  label: "Country",
  defaultValue: "us",
  options: [
    { label: "United States", value: "us" },
    { label: "United Kingdom", value: "uk" },
    { label: "Canada", value: "ca" }
  ]
}

Checkbox (Multi Select)

{
  elementType: "Select",
  elementId: "preferences",
  optional: true,
  label: "Preferences",
  defaultValue: ["email"],
  options: [
    { label: "Email notifications", value: "email" },
    { label: "SMS notifications", value: "sms" },
    { label: "Push notifications", value: "push" }
  ]
}

Submit Button

{
  elementType: "button",
  elementId: "submitBtn",
  buttonText: "Submit",
  disableAfterInteracted: true,
  action: {
    actionType: "urlNavigation",
    url: "https://example.com/submit"
  }
}

Interaction Goals

An InteractionGoal defines when the user’s interaction with the message is considered complete. Use this to track engagement and trigger follow-up actions.

Goal Type	Constant	Description
Any Interaction	CometChat.GoalType.ANY_ACTION	Complete when any element is interacted with
Any of Specific	CometChat.GoalType.ANY_OF	Complete when any of the specified elements is interacted with
All of Specific	CometChat.GoalType.ALL_OF	Complete when all specified elements are interacted with
None	CometChat.GoalType.NONE	Never considered complete (default)

Set an Interaction Goal

JavaScript

let elementIds = ["name", "gender", "submitButton"];
let interactionGoal = new CometChat.InteractionGoal(
  CometChat.GoalType.ALL_OF,
  elementIds
);

let interactiveMessage = new CometChat.InteractiveMessage(
  receiverId,
  receiverType,
  "form",
  interactiveData
);
interactiveMessage.setInteractionGoal(interactionGoal);

CometChat.sendInteractiveMessage(interactiveMessage).then(
  (message) => {
    console.log("Interactive message sent successfully", message);
  },
  (error) => {
    console.log("Interactive message sending failed with error:", error);
  }
);

TypeScript

let elementIds: Array<String> = ["name", "gender", "submitButton"];
let interactionGoal: CometChat.InteractionGoal = new CometChat.InteractionGoal(
  CometChat.GoalType.ALL_OF,
  elementIds
);

let interactiveMessage: CometChat.InteractiveMessage = new CometChat.InteractiveMessage(
  receiverId,
  receiverType,
  "form",
  interactiveData
);
interactiveMessage.setInteractionGoal(interactionGoal);

CometChat.sendInteractiveMessage(interactiveMessage).then(
  (message: CometChat.InteractiveMessage) => {
    console.log("Interactive message sent successfully", message);
  },
  (error: CometChat.CometChatException) => {
    console.log("Interactive message sending failed with error:", error);
  }
);

Interactions

An Interaction represents a single user action on an interactive element.

Property	Type	Description
elementId	string	Identifier of the interacted element
interactedAt	number	Unix timestamp of the interaction

Mark as Interacted

Use markAsInteracted() to record when a user interacts with an element.

JavaScript

let messageId = 123;
let elementId = "submitButton";

CometChat.markAsInteracted(messageId, elementId).then(
  (response) => {
    console.log("Marked as interacted successfully", response);
  },
  (error) => {
    console.log("Failed to mark as interacted:", error);
  }
);

TypeScript

let messageId: number = 123;
let elementId: string = "submitButton";

CometChat.markAsInteracted(messageId, elementId).then(
  (response: string) => {
    console.log("Marked as interacted successfully", response);
  },
  (error: CometChat.CometChatException) => {
    console.log("Failed to mark as interacted:", error);
  }
);

Real-Time Events

Register a MessageListener to receive interactive message events.

Receive Interactive Messages

JavaScript

let listenerID = "UNIQUE_LISTENER_ID";

CometChat.addMessageListener(
  listenerID,
  new CometChat.MessageListener({
    onInteractiveMessageReceived: (message) => {
      console.log("Interactive message received", message);
      // Render the interactive UI based on message.getInteractiveData()
    }
  })
);

TypeScript

let listenerID: string = "UNIQUE_LISTENER_ID";

CometChat.addMessageListener(
  listenerID,
  new CometChat.MessageListener({
    onInteractiveMessageReceived: (message: CometChat.InteractiveMessage) => {
      console.log("Interactive message received", message);
      // Render the interactive UI based on message.getInteractiveData()
    }
  })
);

Interaction Goal Completed

Triggered when a user’s interactions satisfy the defined InteractionGoal.

JavaScript

let listenerID = "UNIQUE_LISTENER_ID";

CometChat.addMessageListener(
  listenerID,
  new CometChat.MessageListener({
    onInteractionGoalCompleted: (receipt) => {
      console.log("Interaction goal completed", receipt);
      // Handle goal completion (e.g., show confirmation, trigger next step)
    }
  })
);

TypeScript

let listenerID: string = "UNIQUE_LISTENER_ID";

CometChat.addMessageListener(
  listenerID,
  new CometChat.MessageListener({
    onInteractionGoalCompleted: (receipt: CometChat.InteractionReceipt) => {
      console.log("Interaction goal completed", receipt);
      // Handle goal completion (e.g., show confirmation, trigger next step)
    }
  })
);

Always remove listeners when they’re no longer needed to prevent memory leaks.

CometChat.removeMessageListener("UNIQUE_LISTENER_ID");

Allow Sender Interaction

By default, the sender cannot interact with their own interactive message. Enable sender interaction:

JavaScript

let interactiveMessage = new CometChat.InteractiveMessage(
  receiverId,
  receiverType,
  "form",
  interactiveData
);
interactiveMessage.setIsSenderInteractionAllowed(true);

CometChat.sendInteractiveMessage(interactiveMessage).then(
  (message) => {
    console.log("Interactive message sent successfully", message);
  },
  (error) => {
    console.log("Interactive message sending failed with error:", error);
  }
);

TypeScript

let interactiveMessage: CometChat.InteractiveMessage = new CometChat.InteractiveMessage(
  receiverId,
  receiverType,
  "form",
  interactiveData
);
interactiveMessage.setIsSenderInteractionAllowed(true);

CometChat.sendInteractiveMessage(interactiveMessage).then(
  (message: CometChat.InteractiveMessage) => {
    console.log("Interactive message sent successfully", message);
  },
  (error: CometChat.CometChatException) => {
    console.log("Interactive message sending failed with error:", error);
  }
);

---

Next Steps

Send Messages

Send text, media, and custom messages

Receive Messages

Listen for incoming messages in real time

Transient Messages

Send ephemeral messages that aren’t stored

Message Structure

Understand message types and hierarchy