Interactive Messages

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

AI Integration Quick Reference

Field	Value
Key Classes	InteractiveMessage, InteractionGoal, Interaction, InteractionReceipt
Key Methods	CometChat.sendInteractiveMessage(), CometChat.markAsInteracted()
Key Constants	InteractionGoalType.anyAction, InteractionGoalType.anyOf, InteractionGoalType.allOf, InteractionGoalType.none
Listener Events	onInteractiveMessageReceived, onInteractionGoalCompleted
Prerequisites	SDK initialized, user logged in

// Create and send an interactive form message
InteractiveMessage interactiveMessage = InteractiveMessage(
  interactiveData: interactiveData,  // Map<String, dynamic> with form fields
  receiverUid: "UID",
  type: "form",
  receiverType: CometChatReceiverType.user,
  allowSenderInteraction: true,
  interactionGoal: InteractionGoal(type: InteractionGoalType.none),
);
CometChat.sendInteractiveMessage(interactiveMessage,
  onSuccess: (InteractiveMessage message) {},
  onError: (CometChatException e) {},
);

// Mark as interacted
CometChat.markAsInteracted(messageId, elementId,
  onSuccess: (String message) {},
  onError: (CometChatException e) {},
);

// Listen for interactive messages
CometChat.addMessageListener("LISTENER_ID", this);
// onInteractiveMessageReceived(InteractiveMessage message) { }
// onInteractionGoalCompleted(InteractionReceipt 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.

Available via: SDK | REST API | UI Kits

InteractiveMessage

The InteractiveMessage class extends BaseMessage and represents a message with embedded interactive content.

Parameter	Type	Description	Required
receiverUid	String	The UID of the user or GUID of the group	Yes
receiverType	String	CometChatReceiverType.user or CometChatReceiverType.group	Yes
type	String	Type identifier (e.g., "form", "card")	Yes
interactiveData	Map<String, dynamic>	JSON structure defining the interactive elements	Yes
allowSenderInteraction	bool	Whether sender can interact with the message	No (default: false)
interactionGoal	InteractionGoal	Defines when the interaction is considered complete	No (default: none)
tags	List<String>	Tags associated with the message	No
muid	String	Unique message identifier for deduplication	No
parentMessageId	int	ID of the parent message (for threads)	No
metadata	Map<String, dynamic>	Custom metadata attached to the message	No

Send an Interactive Message

Use CometChat.sendInteractiveMessage() to send an interactive message.

Dart

final Map<String, dynamic> interactiveData = {
  "title": "Survey",
  "formFields": [
    {
      "elementType":  "textInput" ,
      "elementId": "name",
      "optional": false,
      "label": "Name",
      "placeholder": {
        "text": "Enter text here"
        }
    },
    {
      "elementType":  "textInput",
      "elementId": "age",
      "optional": true,
      "label": "Age",
      "maxLines": 1,
      "placeholder": {
        "text": "Enter text here"
        }
    },
    {
      "elementType":  "Select",
      "elementId": "checkBox1",
      "optional": true,
      "label": "Check box element",
      "defaultValue":["chk_option_2"],
      "options" : [
        {
          "label": "Option 1",
          "value": "chk_option_1",
        },
        {
          "label": "Option 2",
          "value": "chk_option_2",
        }

      ]
    },
    {
      "elementType": "dropdown",
      "elementId": "gender",
      "optional": false,
      "label": "Gender",
      "defaultValue":"male",
      "options" : [
        {
          "label": "Male",
          "value": "male",
        },
        {
          "label": "Female",
          "value": "female",
        }

      ]
    },
  ],
  "submitElement": {
    "elementType": "button",
    "elementId": "submitButton",
    "buttonText": "Submit",
    "disableAfterInteracted": false,
    "action": {
      "actionType": "urlNavigation",
      "url": "https://www.cometchat.com/",
    }
  },
};



InteractiveMessage interactiveMessage =
InteractiveMessage(interactiveData: interactiveData,
                   receiverUid: "cometchat-uid-3", //Replace this with receiver id
                   type: "form",
                   receiverType: "user",//replace this with receiver type
                   allowSenderInteraction: true,
                   muid: DateTime.now().millisecondsSinceEpoch.toString(),
                   interactionGoal: InteractionGoal(
                     type: InteractionGoalType.none
                   )
                  );


CometChat.sendInteractiveMessage(interactiveMessage, onSuccess: (InteractiveMessage message){

print(interactiveMessage);

}, onError: (CometChatException excep){
print(excep);
});

The sendInteractiveMessage() method returns an InteractiveMessage object on success.

Response

On Success — An InteractiveMessage object containing all details of the sent interactive message:

InteractiveMessage Object:

Parameter	Type	Description	Sample Value
id	number	Unique message ID	501
metadata	object	Custom metadata attached to the message	{}
receiver	object	Receiver user object	See below ↓
editedBy	string	UID of the user who edited the message	null
conversationId	string	Unique conversation identifier	"cometchat-uid-1_user_cometchat-uid-3"
sentAt	number	Epoch timestamp when the message was sent	1745554729
receiverUid	string	UID of the receiver	"cometchat-uid-3"
type	string	Type of the message	"form"
readAt	number	Epoch timestamp when the message was read	0
deletedBy	string	UID of the user who deleted the message	null
deliveredAt	number	Epoch timestamp when the message was delivered	0
deletedAt	number	Epoch timestamp when the message was deleted	0
replyCount	number	Number of replies to this message	0
sender	object	Sender user object	See below ↓
receiverType	string	Type of the receiver	"user"
editedAt	number	Epoch timestamp when the message was edited	0
parentMessageId	number	ID of the parent message (for threads)	0
readByMeAt	number	Epoch timestamp when read by the current user	0
category	string	Message category	"interactive"
deliveredToMeAt	number	Epoch timestamp when delivered to the current user	0
updatedAt	number	Epoch timestamp when the message was last updated	1745554729
interactiveData	object	Structured data for the interactive element	{"title": "Survey", "formFields": [...]}
interactions	array	List of user interactions with the message	[]
interactionGoal	object	Intended outcome of interacting with the message	{"type": "none", "elementIds": []}
tags	array	List of tags associated with the message	[]
allowSenderInteraction	boolean	Whether the sender can interact with the message	true
unreadRepliesCount	number	Count of unread replies	0
quotedMessageId	number	ID of the quoted message	null

---

sender Object:

Parameter	Type	Description	Sample Value
uid	string	Unique identifier of the sender	"cometchat-uid-1"
name	string	Display name of the sender	"Andrew Joseph"
link	string	Profile link	null
avatar	string	Avatar URL	"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-1.webp"
metadata	object	Custom metadata	{}
status	string	Online status	"online"
role	string	User role	"default"
statusMessage	string	Status message	null
tags	array	User tags	[]
hasBlockedMe	boolean	Whether this user has blocked the current user	false
blockedByMe	boolean	Whether the current user has blocked this user	false
lastActiveAt	number	Epoch timestamp of last activity	1745554700

---

receiver Object:

Parameter	Type	Description	Sample Value
uid	string	Unique identifier of the receiver	"cometchat-uid-3"
name	string	Display name of the receiver	"Kevin Hart"
link	string	Profile link	null
avatar	string	Avatar URL	"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-3.webp"
metadata	object	Custom metadata	{}
status	string	Online status	"offline"
role	string	User role	"default"
statusMessage	string	Status message	null
tags	array	User tags	[]
hasBlockedMe	boolean	Whether this user has blocked the current user	false
blockedByMe	boolean	Whether the current user has blocked this user	false
lastActiveAt	number	Epoch timestamp of last activity	1745550000

Error

Parameter	Type	Description	Sample Value
code	string	Error code identifier	"ERR_CHAT_API_FAILURE"
message	string	Human-readable error message	"Failed to send the interactive message."
details	string	Additional technical details	"An unexpected error occurred while processing the request."

Interactive Elements

The interactiveData map 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.

InteractionGoal Parameters:

Parameter	Type	Description	Required
type	String	The type of interaction goal (see goal types below)	Yes
elementIds	List<String>	List of element IDs associated with this goal	No (default: [])

Goal Type	Constant	Description
Any Interaction	InteractionGoalType.anyAction	Complete when any element is interacted with
Any of Specific	InteractionGoalType.anyOf	Complete when any of the specified elements is interacted with
All of Specific	InteractionGoalType.allOf	Complete when all specified elements are interacted with
None	InteractionGoalType.none	Never considered complete (default)

Set an Interaction Goal

Dart

List<String> elementIds = ["name", "gender", "submitButton"];
InteractionGoal interactionGoal = InteractionGoal(
  type: InteractionGoalType.allOf,
  elementIds: elementIds,
);

InteractiveMessage interactiveMessage = InteractiveMessage(
  interactiveData: interactiveData,
  receiverUid: "cometchat-uid-3",
  type: "form",
  receiverType: "user",
  interactionGoal: interactionGoal,
);

CometChat.sendInteractiveMessage(interactiveMessage,
  onSuccess: (InteractiveMessage message) {
    debugPrint("Interactive message sent successfully: $message");
  },
  onError: (CometChatException excep) {
    debugPrint("Interactive message sending failed with error: ${excep.message}");
  },
);

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.

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.

Interactions

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

Property	Type	Description
elementId	String	Identifier of the interacted element
interactedAt	DateTime	Timestamp indicating when the interaction occurred

Mark as Interacted

Use CometChat.markAsInteracted() to record when a user interacts with an element. This method marks a message as interacted by identifying it with the provided ID and logs the interactive element associated with the interaction.

Dart

Future<void> recordInteraction() async {
  int messageId = 0; // set to your interactive message id
  String interactedElementId = ""; // set to the element id

  await CometChat.markAsInteracted(
    messageId,
    interactedElementId,
    onSuccess: (String message) {
      // after success
    },
    onError: (CometChatException excep) {
      // after error
    },
  );
}

Parameter	Type	Description	Required
messageId	int	The ID of the interactive message	Yes
interactedElementId	String	The element ID that was interacted with	Yes

Response

On Success — A String message confirming the interaction was recorded:

Parameter	Type	Description	Sample Value
message	string	Success confirmation message	"Message marked as interacted successfully."

Error

Parameter	Type	Description	Sample Value
code	string	Error code identifier	"ERR_CHAT_API_FAILURE"
message	string	Human-readable error message	"Failed to mark the message as interacted."
details	string	Additional technical details	"An unexpected error occurred while processing the request."

Real-Time Events

Register a MessageListener to receive interactive message events.

Receive Interactive Messages

The onInteractiveMessageReceived event listener is triggered when an InteractiveMessage is received.

Dart

class DemoClass with MessageListener{

String listenerId = "UNIQUE_LISTENER_ID"; //Replace with unique listener id


CometChat.addMessageListener(_listenerId, this);



  @override
void onInteractiveMessageReceived(InteractiveMessage message){

  //TODO  implement onInteractiveMessageReceived event 
}

}

Interaction Goal Completed

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

InteractionReceipt Properties:

Property	Type	Description
messageId	int	The ID of the interactive message
sender	User	The user who completed the interaction
receiverType	String	Type of the receiver ("user" or "group")
receiverId	String	UID or GUID of the receiver
interactions	List<Interaction>	List of interactions that satisfied the goal

Dart

class DemoClass with MessageListener{

String listenerId = "UNIQUE_LISTENER_ID"; //Replace with unique listener id


CometChat.addMessageListener(_listenerId, this);



@override
void onInteractionGoalCompleted(InteractionReceipt receipt) {
  //TODO implement onInteractionGoalCompleted
}

}

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.

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. Set allowSenderInteraction to true to enable sender interaction:

Dart

InteractiveMessage interactiveMessage = InteractiveMessage(
  interactiveData: interactiveData,
  receiverUid: "cometchat-uid-3",
  type: "form",
  receiverType: "user",
  allowSenderInteraction: true,
);

CometChat.sendInteractiveMessage(interactiveMessage,
  onSuccess: (InteractiveMessage message) {
    debugPrint("Interactive message sent successfully: $message");
  },
  onError: (CometChatException excep) {
    debugPrint("Interactive message sending failed with error: ${excep.message}");
  },
);

---

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