Interactive Messages - CometChat Docs

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

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

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

​InteractiveMessage

​Send an Interactive Message

​Interactive Elements

​Text Input

​Dropdown (Single Select)

​Checkbox (Multi Select)

​Submit Button

​Interaction Goals

​Set an Interaction Goal

​Interactions

​Mark as Interacted

​Real-Time Events

​Receive Interactive Messages

​Interaction Goal Completed

​Allow Sender Interaction

​Next Steps

Send Messages

Receive Messages

Transient Messages

Message Structure

InteractiveMessage

Send an Interactive Message

Interactive Elements

Text Input

Dropdown (Single Select)

Checkbox (Multi Select)

Submit Button

Interaction Goals

Set an Interaction Goal

Interactions

Mark as Interacted

Real-Time Events

Receive Interactive Messages

Interaction Goal Completed

Allow Sender Interaction

Next Steps