Skip to main content
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 various properties:
ParameterDescription
receiverIdThe UID or GUID of the recipientRequired
receiverTypeThe type of the receiver to whom the message is to be sent. Options: CometChatConstants.RECEIVER_TYPE_USER (user) or CometChatConstants.RECEIVER_TYPE_GROUP (group)Required
messageTypeThe type of the message that needs to be sentRequired
interactiveDataA JSONObject holding structured data for the interactive element.Required
allowSenderInteractionA boolean determining whether the message sender can interact with the message. Default is set to false.
interactionGoalAn InteractionGoal object encapsulating the intended outcome of interacting with the InteractiveMessage. Default 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.
val messageId = 1
val elementId = "elementId"

CometChat.markAsInteracted(messageId, elementId, object : CometChat.CallbackListener<Void?>() {
    override fun onSuccess(unused: Void?) {

    }

    override fun onError(e: CometChatException) {
      
    }
}) 

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:
GoalsDescriptionKeys
Any InteractionThe goal is considered completed if there is at least one interaction.CometChatConstants.INTERACTION_TYPE_ANY
Any of Specific InteractionsThe goal is achieved if any of the specified interactions occurred.CometChatConstants.INTERACTION_TYPE_ANY_OF
All of Specific InteractionsThe goal is completed when all specified interactions occur.CometChatConstants.INTERACTION_TYPE_ALL_OF
NoneThe goal is never completed.CometChatConstants.INTERACTION_TYPE_NONE

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.

Send an Interactive Message

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. Before sending interactive messages, ensure you have initialized the SDK and logged in a user. Here is an example of how to use it:
val interactiveData = JSONObject()
try {
    interactiveData.put("title", "Demo Form")
    val jsonArray = JSONArray()
    val textInput = JSONObject()
    textInput.put("elementType", "textInput")
    textInput.put("elementId", "element1")
    textInput.put("label", "Name")
    textInput.put("optional", false)
    textInput.put("maxLines", 1)
    jsonArray.put(textInput)
    interactiveData.put("formFields", jsonArray)
    val submitElement = JSONObject()
    submitElement.put("elementType", "button")
    submitElement.put("elementId", "element8")
    submitElement.put("buttonText", "Submit")
    submitElement.put("disableAfterInteracted", true)
    val action = JSONObject()
    action.put("actionType", "urlNavigation")
    action.put("url", "https://www.cometchat.com/")
    submitElement.put("action", action)
    interactiveData.put("submitElement", submitElement)
} catch (e: JSONException) {
    throw RuntimeException(e)
}

val interactiveMessage = InteractiveMessage(receiverId, receiverType, "form", interactiveData)

CometChat.sendInteractiveMessage(interactiveMessage, object : CometChat.CallbackListener<InteractiveMessage>() {
    override fun onSuccess(interactiveMessage: InteractiveMessage) {
        // This block is executed when the InteractiveMessage is sent successfully.
    }

    override fun onError(e: CometChatException) {
        // This block is executed if an error occurs while sending the InteractiveMessage.
    }
})

Real-time Events

CometChat SDK provides event listeners to handle real-time events related to InteractiveMessage. For more details on listener management, see Real-Time Listeners. On InteractiveMessage Received The onInteractiveMessageReceived event listener is triggered when an InteractiveMessage is received. Here is an example:
CometChat.addMessageListener("UNIQUE_ID", object : CometChat.MessageListener() {
  override fun onInteractiveMessageReceived(interactiveMessage: InteractiveMessage) {
      // This block is executed when an InteractiveMessage is received.
      // Here you can define logic to handle the received InteractiveMessage and display it in your chat interface.
  }
})
Always remove listeners when they’re no longer needed (e.g., in onDestroy() or when navigating away). Failing to remove listeners can cause memory leaks and duplicate event handling.

On Interaction Goal Completed

The onInteractionGoalCompleted event listener is invoked when an interaction goal is achieved. Here is an example:
CometChat.addMessageListener("UNIQUE_ID", object : CometChat.MessageListener() {
  override fun onInteractionGoalCompleted(interactionReceipt: InteractionReceipt) {
      // This block is executed when an interaction goal is completed.
      // Here you can specify the actions your application should take once an interaction goal is achieved, such as updating the UI or notifying the user.
  }
})
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.

InteractiveMessage Payload Structure

The InteractiveMessage object contains interactive content like forms and buttons:
ParameterTypeDescription
idlongUnique message identifier
muidStringDeveloper-defined message ID
senderUserUser who sent the message
receiverAppEntityMessage receiver (User or Group)
typeStringMessage type (e.g., "form", "card")
receiverTypeStringType of receiver. Values: "user", "group"
categoryStringMessage category. Value: "interactive"
sentAtlongUnix timestamp when sent
metadataJSONObjectCustom message metadata
conversationIdStringAssociated conversation ID
interactiveDataJSONObjectInteractive content data
tagsArray<String>Message tags
interactionGoalInteractionGoalGoal for interactions
interactionsArray<Interaction>User interactions
allowSenderInteractionbooleanIf sender can interact
Sample InteractiveMessage Object:
{
  "id": 12345,
  "muid": "msg_abc123",
  "sender": {
    "uid": "user_123",
    "name": "John Doe",
    "avatar": "https://example.com/avatar.png",
    "status": "online",
    "role": "default"
  },
  "receiver": {
    "uid": "user_456",
    "name": "Jane Smith"
  },
  "type": "form",
  "receiverType": "user",
  "category": "interactive",
  "sentAt": 1699900000,
  "metadata": {"priority": "high"},
  "conversationId": "user_123_user_456",
  "interactiveData": {
    "title": "Demo Form",
    "formFields": [
      {
        "elementType": "textInput",
        "elementId": "element1",
        "label": "Name",
        "optional": false,
        "maxLines": 1
      }
    ],
    "submitElement": {
      "elementType": "button",
      "elementId": "element8",
      "buttonText": "Submit",
      "disableAfterInteracted": true,
      "action": {
        "actionType": "urlNavigation",
        "url": "https://www.cometchat.com/"
      }
    }
  },
  "tags": ["interactive"],
  "interactionGoal": {
    "type": "anyOf",
    "elementIds": ["element1", "element8"]
  },
  "interactions": [],
  "allowSenderInteraction": false
}
The InteractionGoal object defines the desired outcome of interactions:
ParameterTypeDescription
typeStringGoal type. Values: "none", "anyAction", "anyOf", "allOf"
elementIdsArray<String>Target element IDs for the goal
Sample InteractionGoal Object:
{
  "type": "anyOf",
  "elementIds": ["button_1", "input_1"]
}
The Interaction object represents a user action on an interactive element:
ParameterTypeDescription
elementIdStringIdentifier of the interacted element
interactedAtlongUnix timestamp when interaction occurred
Sample Interaction Object:
{
  "elementId": "element1",
  "interactedAt": 1699900500
}
The nested User object in sender contains:
ParameterTypeDescription
uidStringUnique identifier of the user
nameStringDisplay name of the user
avatarStringURL to user’s profile picture
linkStringURL to user’s profile page
roleStringUser role for access control
metadataJSONObjectCustom data set by developer
statusStringUser online status. Values: "online", "offline"
statusMessageStringCustom status message
lastActiveAtlongUnix timestamp of last activity
hasBlockedMebooleanWhether this user has blocked the logged-in user
blockedByMebooleanWhether the logged-in user has blocked this user
tagsArray<String>List of tags for user identification
deactivatedAtlongUnix timestamp when user was deactivated (0 if active)
Sample User Object:
{
  "uid": "user_123",
  "name": "John Doe",
  "avatar": "https://example.com/avatar.png",
  "link": "https://example.com/profile/user_123",
  "role": "default",
  "metadata": {"department": "engineering"},
  "status": "online",
  "statusMessage": "Available",
  "lastActiveAt": 1699900000,
  "hasBlockedMe": false,
  "blockedByMe": false,
  "tags": ["premium"],
  "deactivatedAt": 0
}

Next Steps

Send Messages

Learn how to send text, media, and custom messages

Mentions

Mention specific users in messages for better engagement

Receive Messages

Handle incoming messages with real-time listeners

Real-Time Listeners

Manage event listeners for real-time updates