Interactive Messages - CometChat Docs

Quick Reference - Send an interactive message and listen for it:

// Send an interactive message
const interactiveMessage = new CometChat.InteractiveMessage(
  "UID", CometChat.RECEIVER_TYPE.USER, "form", { title: "Survey", formFields: [] }
);
await CometChat.sendInteractiveMessage(interactiveMessage);

// Listen for incoming interactive messages
CometChat.addMessageListener("interactive-listener", new CometChat.MessageListener({
  onInteractiveMessageReceived: (msg) => console.log("Interactive:", msg),
  onInteractionGoalCompleted: (msg) => console.log("Goal completed:", msg),
}));

Available via: SDK | REST API

An InteractiveMessage is a specialized object that encapsulates an interactive unit within a chat message, such as an embedded form that users can fill out directly within the chat interface. This enhances user engagement by making the chat experience more interactive and responsive to user input.

InteractiveMessage

InteractiveMessage is a chat message with embedded interactive content. It can contain the following properties:

Parameter	Description
`receiverId`	The UID or GUID of the recipient	Required
`receiverType`	The type of the receiver to whom the message is to be sent i.e `CometChat.RECEIVER_TYPE.USER (user)` or `CometChat.RECEIVER_TYPE.GROUP (group)`	Required
`messageType`	The type of the message that needs to be sent	Required
`interactiveData`	A JSONObject holding structured data for the interactive element	Required
`allowSenderInteraction`	A boolean determining whether the message sender can interact with the message by default it is set to false
`interactionGoal`	An InteractionGoal object encapsulating the intended outcome of interacting with the `InteractiveMessage` by default it is set to none

Interaction

An Interaction represents a user action involved with an InteractiveMessage. It includes:

elementId: An identifier for a specific interactive element.
interactedAt: A timestamp indicating when the interaction occurred.

Mark as Interacted

This method marks a message as interacted by identifying it with the provided Id. It also logs the interactive element associated with the interaction.

JavaScript
TypeScript

CometChat.markAsInteracted(message?.getId(), elementId)
  .then((response) => {
    console.log("Mark As Interacted", response);
  })
  .catch((error) => {
    console.log("error while markAsInteracted", error);
  });

CometChat.markAsInteracted(message?.getId(), elementId)
  .then((response) => {
    console.log("Mark As Interacted", response);
  })
  .catch((error) => {
    console.log("error while markAsInteracted", error);
  });

Response

On Success — markAsInteracted() returns a success message:

Parameter	Type	Description	Sample Value
`message`	string	Confirmation message	`"The message id 25308 has been marked as interacted for the user cometchat-uid-7."`

Goal Completion

A key feature of InteractiveMessage is checking whether a user’s interactions with the message meet the defined InteractionGoal. You would be tracking every interaction users perform on an InteractiveMessage (captured as Interaction objects) and comparing those with the defined InteractionGoal. The completion of a goal can vary depending on the goal type:

Goals	Description	Keys
Any Interaction	The goal is considered completed if there is at least one interaction.	CometChat.GoalType.ANY_ACTION
Any of Specific Interactions	The goal is achieved if any of the specified interactions occurred.	CometChat.GoalType.ANY_OF
All of Specific Interactions	The goal is completed when all specified interactions occur.	CometChat.GoalType.ALL_OF
None	The goal is never completed	CometChat.GoalType.NONE

This user interaction tracking mechanism provides a flexible and efficient way to monitor user engagement within an interactive chat session. By defining clear interaction goals and checking user interactions against these goals, you can manage user engagement and improve the overall chat experience in your CometChat-enabled application. InteractionGoal The InteractionGoal represents the desired outcome of an interaction with an InteractiveMessage. It includes:

elementIds: A list of identifiers for the interactive elements.
type: The type of interaction goal from the CometChat.

Sending InteractiveMessages

The InteractiveMessage can be sent using the sendInteractiveMessage method of the CometChat class. The method requires an InteractiveMessage object and a CallbackListener for handling the response. Here is an example of how to use it:

JavaScript
TypeScript

CometChat.sendInteractiveMessage(message)
  .then((message) => {
    console.log("message sent successfully", message.getSentAt());
  })
  .catch((error) => {
    console.log("error while sending message", { error });
  });

CometChat.sendInteractiveMessage(message)
  .then((message: CometChat.InteractiveMessage) => {
    console.log("message sent successfully", message.getSentAt());
  })
  .catch((error: CometChat.CometChatException) => {
    console.log("error while sending message", { error });
  });

Response

On Success — sendInteractiveMessage() returns the sent interactive message object:InteractiveMessage Object:

Parameter	Type	Description	Sample Value
`id`	string	Unique message identifier	`"25308"`
`conversationId`	string	Conversation identifier	`"cometchat-uid-6_user_cometchat-uid-7"`
`receiverId`	string	Receiver’s UID	`"cometchat-uid-7"`
`receiverType`	string	Type of receiver	`"user"`
`type`	string	Message type	`"form"`
`category`	string	Message category	`"interactive"`
`sentAt`	number	Unix timestamp when sent	`1771998776`
`updatedAt`	number	Unix timestamp when updated	`1771998776`
`interactiveData`	object	Interactive element data	See below ↓
`interactionGoal`	object	Goal for tracking interactions	See below ↓
`sender`	object	Sender user details	See below ↓
`receiver`	object	Receiver user details	See below ↓
`data`	object	Additional message data	See below ↓
`reactions`	array	Message reactions	`[]`
`mentionedUsers`	array	Users mentioned in message	`[]`
`mentionedMe`	boolean	Whether current user is mentioned	`false`

interactiveData Object:

Parameter	Type	Description	Sample Value
`title`	string	Form title	`"Quick Survey"`
`formFields`	array	Form field definitions	See below ↓
`submitElement`	object	Submit button configuration	See below ↓
`interactableElementIds`	array	IDs of interactable elements	`["submit_btn"]`

interactiveData.formFields Array (per item):

Parameter	Type	Description	Sample Value
`elementType`	string	Type of form element	`"textInput"`
`elementId`	string	Unique element identifier	`"field1"`
`label`	string	Field label text	`"How was your experience?"`
`optional`	boolean	Whether field is optional	`false`

interactiveData.submitElement Object:

Parameter	Type	Description	Sample Value
`elementType`	string	Type of element	`"button"`
`elementId`	string	Unique element identifier	`"submit_btn"`
`buttonText`	string	Button display text	`"Submit"`

interactionGoal Object:

Parameter	Type	Description	Sample Value
`elementIds`	array	Target element IDs for goal	`[]`
`type`	string	Goal type	`"anyAction"`

sender Object:

Parameter	Type	Description	Sample Value
`uid`	string	User’s unique identifier	`"cometchat-uid-6"`
`name`	string	User’s display name	`"Ronald Jerry"`
`avatar`	string	URL to user’s avatar	`"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-6.webp"`
`status`	string	User’s online status	`"online"`
`role`	string	User’s role	`"default"`
`lastActiveAt`	number	Last active timestamp	`1771998694`
`hasBlockedMe`	boolean	Whether user has blocked current user	`false`
`blockedByMe`	boolean	Whether current user blocked this user	`false`
`deactivatedAt`	number	Deactivation timestamp (0 if active)	`0`
`tags`	array	User tags	`[]`

receiver Object:

Parameter	Type	Description	Sample Value
`uid`	string	User’s unique identifier	`"cometchat-uid-7"`
`name`	string	User’s display name	`"Henry Marino"`
`avatar`	string	URL to user’s avatar	`"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-7.webp"`
`status`	string	User’s online status	`"online"`
`role`	string	User’s role	`"default"`
`lastActiveAt`	number	Last active timestamp	`1771998700`
`hasBlockedMe`	boolean	Whether user has blocked current user	`false`
`blockedByMe`	boolean	Whether current user blocked this user	`false`
`deactivatedAt`	number	Deactivation timestamp (0 if active)	`0`
`tags`	array	User tags	`[]`

data Object:

Parameter	Type	Description	Sample Value
`interactiveData`	object	Interactive element data	See below ↓
`interactionGoal`	object	Goal configuration	See below ↓
`resource`	string	SDK resource identifier	`"REACT_NATIVE-4_0_14-..."`
`allowSenderInteraction`	boolean	Whether sender can interact	`false`
`entities`	object	Sender and receiver entities	See below ↓

data.interactiveData Object:

Parameter	Type	Description	Sample Value
`title`	string	Form title	`"Quick Survey"`
`formFields`	array	Form field definitions	`[{"elementType": "textInput", "elementId": "field1", "label": "How was your experience?", "optional": false}]`
`submitElement`	object	Submit button configuration	`{"elementType": "button", "elementId": "submit_btn", "buttonText": "Submit"}`
`interactableElementIds`	array	IDs of interactable elements	`["submit_btn"]`

data.interactionGoal Object:

Parameter	Type	Description	Sample Value
`elementIds`	array	Target element IDs for goal	`[]`
`type`	string	Goal type	`"anyAction"`

data.entities Object:

Parameter	Type	Description	Sample Value
`sender`	object	Sender entity wrapper	See below ↓
`receiver`	object	Receiver entity wrapper	See below ↓

data.entities.sender Object:

Parameter	Type	Description	Sample Value
`entityType`	string	Type of entity	`"user"`
`entity`	object	User entity details	See below ↓

data.entities.sender.entity Object:

Parameter	Type	Description	Sample Value
`uid`	string	User’s unique identifier	`"cometchat-uid-6"`
`name`	string	User’s display name	`"Ronald Jerry"`
`avatar`	string	User’s avatar URL	`"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-6.webp"`
`status`	string	User’s online status	`"online"`
`role`	string	User’s role	`"default"`
`lastActiveAt`	number	Last active timestamp	`1771998694`
`tags`	array	User tags	`[]`

data.entities.receiver Object:

Parameter	Type	Description	Sample Value
`entityType`	string	Type of entity	`"user"`
`entity`	object	User entity details	See below ↓

data.entities.receiver.entity Object:

Parameter	Type	Description	Sample Value
`uid`	string	User’s unique identifier	`"cometchat-uid-7"`
`name`	string	User’s display name	`"Henry Marino"`
`avatar`	string	User’s avatar URL	`"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-7.webp"`
`status`	string	User’s online status	`"online"`
`role`	string	User’s role	`"default"`
`lastActiveAt`	number	Last active timestamp	`1771998700`
`conversationId`	string	Conversation identifier	`"cometchat-uid-6_user_cometchat-uid-7"`
`tags`	array	User tags	`[]`

Event Listeners

CometChat SDK provides event listeners to handle real-time events related to InteractiveMessage.

On InteractiveMessage Received

The onInteractiveMessageReceived event listener is triggered when an InteractiveMessage is received. Here is an example:

JavaScript
TypeScript

CometChat.addMessageListener(
  "UNIQUE_LISTENER_ID",
  new CometChat.MessageListener({
    onInteractiveMessageReceived: (message) => {
      console.log("on Interactive Message Received", message);
    }
  })
);

CometChat.addMessageListener(
  "UNIQUE_LISTENER_ID",
  new CometChat.MessageListener({
    onInteractiveMessageReceived: (message: CometChat.InteractiveMessage) => {
      console.log("on Interactive Message Received", message);
    }
  })
);

Response

On Event — onInteractiveMessageReceived returns the received interactive message object:InteractiveMessage Object:

Parameter	Type	Description	Sample Value
`id`	string	Unique message identifier	`"25308"`
`conversationId`	string	Conversation identifier	`"cometchat-uid-6_user_cometchat-uid-7"`
`receiverId`	string	Receiver’s UID	`"cometchat-uid-7"`
`receiverType`	string	Type of receiver	`"user"`
`type`	string	Message type	`"form"`
`category`	string	Message category	`"interactive"`
`sentAt`	number	Unix timestamp when sent	`1771998776`
`updatedAt`	number	Unix timestamp when updated	`1771998776`
`interactiveData`	object	Interactive element data	See below ↓
`interactionGoal`	object	Goal for tracking interactions	See below ↓
`sender`	object	Sender user details	See below ↓
`receiver`	object	Receiver user details	See below ↓
`data`	object	Additional message data	See below ↓
`reactions`	array	Message reactions	`[]`
`mentionedUsers`	array	Users mentioned in message	`[]`
`mentionedMe`	boolean	Whether current user is mentioned	`false`

interactiveData Object:

Parameter	Type	Description	Sample Value
`title`	string	Form title	`"Quick Survey"`
`formFields`	array	Form field definitions	See below ↓
`submitElement`	object	Submit button configuration	See below ↓
`interactableElementIds`	array	IDs of interactable elements	`["submit_btn"]`

interactiveData.formFields Array (per item):

Parameter	Type	Description	Sample Value
`elementType`	string	Type of form element	`"textInput"`
`elementId`	string	Unique element identifier	`"field1"`
`label`	string	Field label text	`"How was your experience?"`
`optional`	boolean	Whether field is optional	`false`

interactiveData.submitElement Object:

Parameter	Type	Description	Sample Value
`elementType`	string	Type of element	`"button"`
`elementId`	string	Unique element identifier	`"submit_btn"`
`buttonText`	string	Button display text	`"Submit"`

interactionGoal Object:

Parameter	Type	Description	Sample Value
`elementIds`	array	Target element IDs for goal	`[]`
`type`	string	Goal type	`"anyAction"`

sender Object:

Parameter	Type	Description	Sample Value
`uid`	string	User’s unique identifier	`"cometchat-uid-6"`
`name`	string	User’s display name	`"Ronald Jerry"`
`avatar`	string	URL to user’s avatar	`"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-6.webp"`
`status`	string	User’s online status	`"online"`
`role`	string	User’s role	`"default"`
`lastActiveAt`	number	Last active timestamp	`1771998694`
`hasBlockedMe`	boolean	Whether user has blocked current user	`false`
`blockedByMe`	boolean	Whether current user blocked this user	`false`
`deactivatedAt`	number	Deactivation timestamp (0 if active)	`0`
`tags`	array	User tags	`[]`

receiver Object:

Parameter	Type	Description	Sample Value
`uid`	string	User’s unique identifier	`"cometchat-uid-7"`
`name`	string	User’s display name	`"Henry Marino"`
`avatar`	string	URL to user’s avatar	`"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-7.webp"`
`status`	string	User’s online status	`"online"`
`role`	string	User’s role	`"default"`
`lastActiveAt`	number	Last active timestamp	`1771998700`
`hasBlockedMe`	boolean	Whether user has blocked current user	`false`
`blockedByMe`	boolean	Whether current user blocked this user	`false`
`deactivatedAt`	number	Deactivation timestamp (0 if active)	`0`
`tags`	array	User tags	`[]`

data Object:

Parameter	Type	Description	Sample Value
`interactiveData`	object	Interactive element data	See below ↓
`interactionGoal`	object	Goal configuration	See below ↓
`resource`	string	SDK resource identifier	`"REACT_NATIVE-4_0_14-..."`
`allowSenderInteraction`	boolean	Whether sender can interact	`false`
`entities`	object	Sender and receiver entities	See below ↓

data.interactiveData Object:

Parameter	Type	Description	Sample Value
`title`	string	Form title	`"Quick Survey"`
`formFields`	array	Form field definitions	`[{"elementType": "textInput", "elementId": "field1", "label": "How was your experience?", "optional": false}]`
`submitElement`	object	Submit button configuration	`{"elementType": "button", "elementId": "submit_btn", "buttonText": "Submit"}`
`interactableElementIds`	array	IDs of interactable elements	`["submit_btn"]`

data.interactionGoal Object:

Parameter	Type	Description	Sample Value
`elementIds`	array	Target element IDs for goal	`[]`
`type`	string	Goal type	`"anyAction"`

data.entities Object:

Parameter	Type	Description	Sample Value
`sender`	object	Sender entity wrapper	See below ↓
`receiver`	object	Receiver entity wrapper	See below ↓

data.entities.sender Object:

Parameter	Type	Description	Sample Value
`entityType`	string	Type of entity	`"user"`
`entity`	object	User entity details	See below ↓

data.entities.sender.entity Object:

Parameter	Type	Description	Sample Value
`uid`	string	User’s unique identifier	`"cometchat-uid-6"`
`name`	string	User’s display name	`"Ronald Jerry"`
`avatar`	string	User’s avatar URL	`"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-6.webp"`
`status`	string	User’s online status	`"online"`
`role`	string	User’s role	`"default"`
`lastActiveAt`	number	Last active timestamp	`1771998694`
`tags`	array	User tags	`[]`

data.entities.receiver Object:

Parameter	Type	Description	Sample Value
`entityType`	string	Type of entity	`"user"`
`entity`	object	User entity details	See below ↓

data.entities.receiver.entity Object:

Parameter	Type	Description	Sample Value
`uid`	string	User’s unique identifier	`"cometchat-uid-7"`
`name`	string	User’s display name	`"Henry Marino"`
`avatar`	string	User’s avatar URL	`"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-7.webp"`
`status`	string	User’s online status	`"online"`
`role`	string	User’s role	`"default"`
`lastActiveAt`	number	Last active timestamp	`1771998700`
`conversationId`	string	Conversation identifier	`"cometchat-uid-6_user_cometchat-uid-7"`
`tags`	array	User tags	`[]`

On Interaction Goal Completed

The onInteractionGoalCompleted event listener is invoked when an interaction goal is achieved. Here is an example:

JavaScript
TypeScript

CometChat.addMessageListener(
  "UNIQUE_LISTENER_ID",
  new CometChat.MessageListener({
    onInteractionGoalCompleted: (message) => {
      console.log("on Interaction Goal Completed", message);
    }
  })
);

CometChat.addMessageListener(
  "UNIQUE_LISTENER_ID",
  new CometChat.MessageListener({
    onInteractionGoalCompleted: (message: CometChat.InteractiveMessage) => {
      console.log("on Interaction Goal Completed", message);
    }
  })
);

These event listeners offer your application a way to provide real-time updates in response to incoming interactive messages and goal completions, contributing to a more dynamic and responsive user chat experience.

Listener Cleanup: Always remove message listeners when they are no longer needed. Remove the listener in componentWillUnmount() or the cleanup function of a useEffect hook to prevent memory leaks.

CometChat.removeMessageListener("UNIQUE_LISTENER_ID");

Usage

An InteractiveMessage is constructed with the receiver’s UID, the receiver type, the interactive type, and interactive data as a JSONObject. Once created, the InteractiveMessage can be sent using CometChat’s sendInteractiveMessage() method. Incoming InteractiveMessages can be received and processed via CometChat’s message listener framework.

Best Practices

Use descriptive, unique listener IDs (e.g., "interactive-form-listener") to avoid conflicts with other listeners
Always remove message listeners on component unmount to prevent memory leaks
Set allowSenderInteraction to true only when the sender needs to interact with their own message (e.g., previewing a form)
Define clear InteractionGoal types to accurately track user engagement with interactive elements
Handle both onInteractiveMessageReceived and onInteractionGoalCompleted events to provide a complete interactive experience

Troubleshooting

Interactive message not sending: Verify that interactiveData is a valid JSON object and all required fields (receiverId, receiverType, messageType) are set
Not receiving interactive messages: Ensure the message listener is registered with onInteractiveMessageReceived and the user is logged in
Goal not completing: Check that the InteractionGoal type matches the expected interactions — use ANY_ACTION for simple cases and ALL_OF only when every specified element must be interacted with
markAsInteracted failing: Confirm that the message ID and element ID are valid and that the user has permission to interact with the message
Duplicate events: Verify you are not registering the same listener ID multiple times without removing the previous one

Next Steps

Send a Message

Send text, media, custom, and interactive messages to users and groups

Receive Messages

Listen for real-time messages and fetch missed or unread messages

Message Structure

Understand message categories, types, and hierarchy including interactive messages

Messaging Overview

Explore the full range of CometChat messaging capabilities

​InteractiveMessage

​Interaction

​Mark as Interacted

​Goal Completion

​Sending InteractiveMessages

​Event Listeners

​On InteractiveMessage Received

​On Interaction Goal Completed

​Usage

​Next Steps

Send a Message

Receive Messages

Message Structure

Messaging Overview

InteractiveMessage

Interaction

Mark as Interacted

Goal Completion

Sending InteractiveMessages

Event Listeners

On InteractiveMessage Received

On Interaction Goal Completed

Usage

Next Steps