Interactive Messages

Guide to creating and sending interactive messages (forms, cards, schedulers) using the CometChat iOS SDK.

Quick Reference for AI Agents & Developers

• Create interactive: InteractiveMessage() — set receiverUid, receiverType, type, interactiveData
• Send interactive: CometChat.sendInteractiveMessage(message:onSuccess:onError:)
• Types: Form, Card, Scheduler, Custom Interactive
• Interaction goal: Set interactionGoal to define completion criteria
• Related: Send Message · Messaging Overview

InteractiveMessage Properties

Property	Type	Description
receiverUid	String	UID or GUID of recipient
receiverType	ReceiverType	.user or .group
type	String	form, card, scheduler, or custom
interactiveData	[String: Any]	JSON structure for content
allowSenderInteraction	Bool	Can sender interact (default: false)
interactionGoal	InteractionGoal	Completion criteria
messageCategory	MessageCategory	.interactive

---

Interaction Goal Types

Type	Description	Value
Any Action	Goal completed if any interaction occurs	.anyAction
Any Of	Goal achieved if any specified interaction occurs	.anyOf
All Of	Goal completed when all specified interactions occur	.allOf
None	Goal is never completed	.none

---

Form Element Types

Element Type	Description
textInput	Single or multi-line text input
dropdown	Dropdown select with options
checkbox	Multiple selection checkboxes
radio	Single selection radio buttons
singleSelect	Single selection list
button	Action button (submit, navigate)

---

Button Action Types

Action Type	Description
urlNavigation	Opens a URL in browser
apiAction	Makes an API call with specified parameters
customAction	Custom action handled by app

---

Send Form Interactive Message

Swift

let interMessage = InteractiveMessage()
interMessage.messageCategory = .interactive
interMessage.type = "form"
interMessage.receiverType = .user
interMessage.receiverUid = "cometchat-uid-2"
interMessage.allowSenderInteraction = true

interMessage.interactiveData = [
    "title": "Contact Form",
    "formFields": [
        [
            "elementId": "name_field",
            "elementType": "textInput",
            "label": "Name",
            "optional": false
        ],
        [
            "elementId": "country_dropdown",
            "elementType": "dropdown",
            "label": "Country",
            "options": [
                ["label": "USA", "value": "usa"],
                ["label": "UK", "value": "uk"],
                ["label": "India", "value": "india"]
            ]
        ]
    ],
    "submitElement": [
        "elementId": "submit_btn",
        "elementType": "button",
        "buttonText": "Submit",
        "disableAfterInteracted": true
    ],
    "goalCompletionText": "Thank you for submitting!"
]

let goal = InteractionGoal()
goal.elementIds = ["submit_btn"]
goal.interactionType = .anyOf
interMessage.interactionGoal = goal

CometChat.sendInteractiveMessage(message: interMessage, onSuccess: { message in
    print("Interactive message sent: \(message)")
}, onError: { error in
    print("Error: \(error?.errorDescription ?? "")")
})

Sample Payloads - Form Message

Request

Method: CometChat.sendInteractiveMessage(message:)

Message Parameters:

Parameter	Type	Value
receiverUid	String	"cometchat-uid-2"
receiverType	CometChat.ReceiverType	.user
type	String	"form"
messageCategory	CometChat.MessageCategory	.interactive
allowSenderInteraction	Bool	true

Interaction Goal:

Parameter	Type	Value
elementIds	[String]	["submit_btn"]
interactionType	InteractionGoalType	.anyOf

Success Response

Base Message Properties:

Parameter	Type	Value
id	Int	38227
muid	String	""
conversationId	String	"cometchat-uid-2_user_cometchat-uid-2"
senderUid	String	"cometchat-uid-2"
receiverUid	String	"cometchat-uid-2"
receiverType	CometChat.ReceiverType	0 (.user)
messageCategory	CometChat.MessageCategory	4 (.interactive)
sentAt	Int	1772028517

Interactive Message Properties:

Parameter	Type	Value
type	String	"form"
allowSenderInteraction	Bool	true
interactiveData	[String: Any]	Form JSON structure

Error Response

Object Type: CometChatException

Parameter	Type	Value
errorCode	String	"ERR_BAD_REQUEST"
errorDescription	String	"Failed to validate the data sent with the request."

---

Send Card Interactive Message

Swift

let interMessage = InteractiveMessage()
interMessage.messageCategory = .interactive
interMessage.type = "card"
interMessage.receiverType = .user
interMessage.receiverUid = "cometchat-uid-2"
interMessage.allowSenderInteraction = true

interMessage.interactiveData = [
    "title": "Product Card",
    "subtitle": "Special Offer",
    "text": "Check out this amazing product with 20% discount!",
    "imageUrl": "https://example.com/product.png",
    "cardActions": [
        [
            "elementId": "buy_btn",
            "elementType": "button",
            "buttonText": "Buy Now",
            "action": [
                "actionType": "urlNavigation",
                "url": "https://example.com/buy"
            ]
        ],
        [
            "elementId": "details_btn",
            "elementType": "button",
            "buttonText": "View Details",
            "action": [
                "actionType": "urlNavigation",
                "url": "https://example.com/details"
            ]
        ]
    ]
]

let goal = InteractionGoal()
goal.elementIds = ["buy_btn", "details_btn"]
goal.interactionType = .anyOf
interMessage.interactionGoal = goal

CometChat.sendInteractiveMessage(message: interMessage, onSuccess: {...}, onError: {...})

Sample Payloads - Card Message

Request

Message Parameters:

Parameter	Type	Value
receiverUid	String	"cometchat-uid-2"
receiverType	CometChat.ReceiverType	.user
type	String	"card"
messageCategory	CometChat.MessageCategory	.interactive
allowSenderInteraction	Bool	true

Success Response

Base Message Properties:

Parameter	Type	Value
id	Int	38229
conversationId	String	"cometchat-uid-2_user_cometchat-uid-2"
senderUid	String	"cometchat-uid-2"
receiverType	CometChat.ReceiverType	0 (.user)
messageCategory	CometChat.MessageCategory	4 (.interactive)
sentAt	Int	1772028521

Interactive Message Properties:

Parameter	Type	Value
type	String	"card"
allowSenderInteraction	Bool	true

Interaction Goal:

Parameter	Type	Value
elementIds	[String]	["buy_btn", "details_btn"]
interactionType	InteractionGoalType	.anyOf

---

Send Scheduler Interactive Message

Swift

let interMessage = InteractiveMessage()
interMessage.messageCategory = .interactive
interMessage.type = "scheduler"
interMessage.receiverType = .user
interMessage.receiverUid = "cometchat-uid-2"
interMessage.allowSenderInteraction = true

interMessage.interactiveData = [
    "title": "Schedule a Meeting",
    "duration": 30,
    "bufferTime": 5,
    "availability": [
        "monday": ["09:00-12:00", "14:00-17:00"],
        "tuesday": ["09:00-12:00", "14:00-17:00"],
        "wednesday": ["09:00-12:00", "14:00-17:00"]
    ],
    "scheduleElement": [
        "elementId": "schedule_btn",
        "elementType": "button",
        "buttonText": "Schedule",
        "disableAfterInteracted": true
    ],
    "goalCompletionText": "Meeting scheduled successfully!"
]

CometChat.sendInteractiveMessage(message: interMessage, onSuccess: {...}, onError: {...})

Sample Payloads - Scheduler Message

Request

Message Parameters:

Parameter	Type	Value
receiverUid	String	"cometchat-uid-2"
receiverType	CometChat.ReceiverType	.user
type	String	"scheduler"
messageCategory	CometChat.MessageCategory	.interactive
allowSenderInteraction	Bool	true

Scheduler Data:

Parameter	Type	Value
title	String	"Schedule a Meeting"
duration	Int	30
bufferTime	Int	5

Error Response

Object Type: CometChatException

Parameter	Type	Value
errorCode	String	"ERR_BAD_REQUEST"
errorDescription	String	"Failed to validate the data sent with the request."

---

Send Form to Group

Swift

let interMessage = InteractiveMessage()
interMessage.messageCategory = .interactive
interMessage.type = "form"
interMessage.receiverType = .group
interMessage.receiverUid = "cometchat-guid-1"
interMessage.allowSenderInteraction = true

interMessage.interactiveData = [
    "title": "Group Poll",
    "formFields": [
        [
            "elementId": "poll_radio",
            "elementType": "radio",
            "label": "What's your favorite?",
            "optional": false,
            "options": [
                ["label": "Option A", "value": "a"],
                ["label": "Option B", "value": "b"],
                ["label": "Option C", "value": "c"]
            ]
        ]
    ],
    "submitElement": [
        "elementId": "vote_btn",
        "elementType": "button",
        "buttonText": "Vote",
        "disableAfterInteracted": true
    ]
]

CometChat.sendInteractiveMessage(message: interMessage, onSuccess: {...}, onError: {...})

Sample Payloads - Group Form

Request

Message Parameters:

Parameter	Type	Value
receiverUid	String	"cometchat-guid-1"
receiverType	CometChat.ReceiverType	.group
type	String	"form"
messageCategory	CometChat.MessageCategory	.interactive

Success Response

Base Message Properties:

Parameter	Type	Value
id	Int	38228
conversationId	String	"group_cometchat-guid-1"
senderUid	String	"cometchat-uid-2"
receiverUid	String	"cometchat-guid-1"
receiverType	CometChat.ReceiverType	1 (.group)
messageCategory	CometChat.MessageCategory	4 (.interactive)
sentAt	Int	1772028520

---

Interaction Object Properties

Property	Type	Description
elementId	String	ID of interacted element
interactedAt	Double	Timestamp of interaction

---

InteractionGoal Object Properties

Property	Type	Description
elementIds	[String]	IDs of target elements
interactionType	InteractionGoalType	.anyAction, .anyOf, .allOf, .none

---

Real-time Interactive Message Events

To receive interactive message events, implement CometChatMessageDelegate:

Swift

class YourClass: CometChatMessageDelegate {
    
    init() {
        CometChat.addMessageListener("listener-id", self)
    }
    
    func onInteractiveMessageReceived(_ message: InteractiveMessage) {
        print("Interactive message received")
        print("Type: \(message.type ?? "")")
        print("Interactive Data: \(message.interactiveData ?? [:])")
    }
    
    func onInteractionGoalCompleted(_ message: InteractiveMessage) {
        print("Interaction goal completed")
        print("Message ID: \(message.id)")
    }
}

Sample Payloads - Event Listeners

onInteractiveMessageReceived

Method: onInteractiveMessageReceived(_ message: InteractiveMessage)

Parameter	Type	Description
message	InteractiveMessage	The interactive message object
message.type	String?	form, card, scheduler, or custom
message.interactiveData	[String: Any]?	JSON structure of content
message.interactionGoal	InteractionGoal?	Goal definition

onInteractionGoalCompleted

Method: onInteractionGoalCompleted(_ message: InteractiveMessage)

Parameter	Type	Description
message	InteractiveMessage	Message with completed goal
message.interactions	[Interaction]?	User interactions performed