> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-audit-mechanical-fixes.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Interactive Messages
> Send and handle CometChat interactive messages in Flutter apps with forms, cards, custom data, interaction goals, and user actions.
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` is a chat message with embedded interactive content. It can contain various properties:
| Parameter | Description |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| receiverId | The UID or GUID of the recipient |
| receiverType | The type of the receiver to whom the message is to be sent i.e `CometChatConstants.RECEIVER_TYPE_USER` (user) or `CometChatConstants.RECEIVER_TYPE_GROUP` (group) |
| messageType | The type of the message that needs to be sent |
| interactiveData | A JSONObject holding structured data for the interactive element |
| 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.
```dart theme={null}
await CometChat.markAsInteracted(messageId, interactedElementId,
onSuccess: (String message ){
//write code here for after success
}, onError:
(CometChatException excep){
//write code here for after err
});
```
### Goal Completion
A key feature of `InteractiveMessage` is checking whether a user's interactions with the message meet the defined `InteractionGoal`
| | | |
| -------------------------------- | ---------------------------------------------------------------------- | ----------------------------- |
| **Any Interaction** | The goal is considered completed if there is at least one interaction. | InteractionGoalType.anyAction |
| **Any of Specific Interactions** | The goal is achieved if any of the specified interactions occurred. | InteractionGoalType.anyOf |
| **All of Specific Interactions** | The goal is completed when all specified interactions occur. | InteractionGoalType.allOf |
| **None** | The goal is never completed | InteractionGoalType.none |
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.
### 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 `CometChatConstants`.
### 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:
```dart theme={null}
final Map 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);
});
```
### 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:
```dart theme={null}
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
}
}
```
### On Interaction Goal Completed
The `onInteractionGoalCompleted` event listener is invoked when an interaction goal is achieved.
Here is an exampl
```dart theme={null}
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.
### 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.