Interactive Messages - CometChat Docs

InteractiveMessage

InteractiveMessage

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.

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:

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.

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: 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:

let interMessage = InteractiveMessage()
        interMessage.messageCategory = .interactive
         
        let jsonString:[String:Any] = [
          "goalCompletionText": "Goal completed YAY",
          "title":"By Shantanu",
          "formFields":[
            [
              "defaultValue" : "",
              "elementId" : "element1",
              "elementType" : "textInput",
              "label" : "Name",
              "maxLines" : 1,
              "optional" : false
            ],
            [
              "elementId" : "element2",
              "elementType" : "textInput",
              "label" : "Last Name",
              "maxLines" : 1,
              "optional" : false
            ],
            [
              "defaultValue" : "",
              "elementId" : "element3",
              "elementType" : "textInput",
              "label" : "Address",
              "maxLines" : 5,
              "optional" : false
            ],
            [
              "defaultOption" : "",
              "elementId" : "element4",
              "elementType" : "dropdown",
              "label" : "Country",
              "optional" : false,
              "options" :               [
                [
                  "label" : "INDIA",
                  "value" : "option1"
                ],
                [
                  "label" : "AUSTRALIA",
                  "value" : "option2"
                ],
                [
                  "label" : "RUSSIA",
                  "value" : "option3"
                ],
                [
                  "label" : "AMERICA",
                  "value" : "option4"
                ]
              ]
            ],
            [
              "defaultValue" :               [
              ],
              "elementId" : "element5",
              "elementType" : "checkbox",
              "label" : "Country",
              "optional" : false,
              "options" :               [
                [
                  "label" : "INDIA",
                  "value" : "option1"
                ],
                [
                  "label" : "AUSTRALIA",
                  "value" : "option2"
                ],
                [
                  "label" : "RUSSIA",
                  "value" : "option3"
                ],
                [
                  "label" : "AMERICA",
                  "value" : "option4"
                ]
              ]
            ],
            [
              "defaultValue" : "",
              "elementId" : "element6",
              "elementType" : "singleSelect",
              "label" : "Country",
              "optional" : false,
              "options" : [
                [
                  "label" : "INDIA",
                  "value" : "option1"
                ],
                [
                  "label" : "AUSTRALIA",
                  "value" : "option2"
                ]
              ]
            ],
            [
              "defaultValue" : "option1",
              "elementId" : "element7",
              "elementType" : "radio",
              "label" : "Country",
              "optional" : false,
              "options" : [
                [
                  "label" : "INDIA",
                  "value" : "option1"
                ],
                [
                  "label" : "AUSTRALIA",
                  "value" : "option2"
                ],
                [
                  "label" : "RUSSIA",
                  "value" : "option3"
                ],
                [
                  "label" : "AMERICA",
                  "value" : "option4"
                ]
              ]
            ],
            [
              "action" : [
                "actionType" : "urlNavigation",
                "url" : "https://www.cometchat.com/"
              ],
              "buttonText" : "About us",
              "disableAfterInteracted" : false,
              "elementId" : "element9",
              "elementType" : "button"
            ]
          ],
          "submitElement" : [
            "action" : [
              "actionType" : "apiAction",
              "dataKey" : "CometChatData",
              "headers" : [
                "Content-Type" : "application/json",
                "apiKey" : "5797f2d3d103d7d78f085eb46bfd14d5c45ddfdf",
                "appId" : "10893f2ae68f59",
                "onBehalfOf" : "shantanu"
              ],
              "method" : "POST",
              "payload" : [
                "category" : "message",
                "data" :                 [
                  "text" : "Thanks For filling the Form!"
                ],
                "receiver" : "group_1695921003310",
                "receiverType" : "group",
                "type" : "text"
              ] as [String : Any],
              "url" : "https://10893f2ae68f59.api-us.cometchat-staging.com/v3.0/messages"
            ] as [String : Any],
            "buttonText" : "Submit",
            "disableAfterInteracted" : true,
            "elementId" : "element8",
            "elementType" : "button"
          ] as [String : Any]
        ]
        interMessage.interactiveData = jsonString
        let goal = InteractionGoal()
        goal.elementIds = ["element9","element8"]
        goal.interactionType = .allOf
         
        interMessage.interactionGoal = goal
        interMessage.allowSenderInteraction = true
        interMessage.type = "form"
        interMessage.receiverType = .user
        interMessage.receiverUid = "cometchat-uid-1"
        interMessage.muid = "1697025959995609"
        interMessage.senderUid = CometChat.getLoggedInUser()?.uid ?? ""
        interMessage.sender = CometChat.getLoggedInUser()
         
        CometChat.sendInteractiveMessage(message: interMessage, onSuccess: {
          succes in
          print("successs",succes)
          interMessage.sentAt = Int(Date().timeIntervalSince1970)
        }, onError: {
          error in
            print("errorr",error?.description)
        })

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:

class DemoClass : CometChatMessageDelegate {
    init() {
        CometChat.addMessageListener("sdk-listener", self)
    }
  public func onInteractiveMessageReceived(_ baseMessage: BaseMessage) {
        //TODO  implement onInteractiveMessageReceived event 
    }
}

On Interaction Goal Completed

The onInteractionGoalCompleted event listener is invoked when an interaction goal is achieved. Here is an example: 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.