Interactive Messages

Send messages with embedded forms, buttons, and interactive elements

Quick Reference for AI Agents & Developers

// Send interactive message (form, card, buttons)
const interactiveData = {
  title: "Quick Survey",
  formFields: [
    { elementType: "textInput", elementId: "name", label: "Your Name" },
    { elementType: "dropdown", elementId: "rating", label: "Rating",
      options: [{ label: "Good", value: "4" }, { label: "Great", value: "5" }] }
  ],
  submitElement: { elementType: "button", elementId: "submit", buttonText: "Submit" }
};

const message = new CometChat.InteractiveMessage(
  receiverID,
  CometChat.RECEIVER_TYPE.GROUP,
  "form",  // type: form, card, etc.
  interactiveData
);
await CometChat.sendInteractiveMessage(message);

// Listen for interactive messages
CometChat.addMessageListener("LISTENER", new CometChat.MessageListener({
  onInteractiveMessageReceived: (msg) => {
    const data = msg.getInteractiveData();
  }
}));

// Set interaction goal
message.setInteractionGoal(new CometChat.InteractionGoal(
  ["submitBtn"], CometChat.INTERACTION_TYPE.ANY_OF
));

Interactive messages contain embedded interactive elements like forms, buttons, and inputs that users can interact with directly in the chat interface.

Available via: SDK | REST API | UI Kits

---

Use Cases

Type	Description
Forms	Surveys, feedback forms, data collection
Buttons	Quick actions, confirmations, navigation
Cards	Product cards, booking confirmations
Polls	Voting, decision making

---

InteractiveMessage Properties

Property	Description	Required
receiverId	UID or GUID of recipient	Yes
receiverType	USER or GROUP	Yes
messageType	Type of interactive message (e.g., “form”)	Yes
interactiveData	JSON object with interactive content	Yes
allowSenderInteraction	Can sender interact (default: false)	No
interactionGoal	Defines completion criteria	No

---

Send an Interactive Message

Form Example

const interactiveData = {
  title: "Quick Survey",
  formFields: [
    {
      elementType: "textInput",
      elementId: "name",
      label: "Your Name",
      placeholder: { text: "Enter your name" }
    },
    {
      elementType: "dropdown",
      elementId: "rating",
      label: "How would you rate us?",
      options: [
        { label: "Excellent", value: "5" },
        { label: "Good", value: "4" },
        { label: "Average", value: "3" }
      ]
    }
  ],
  submitElement: {
    elementType: "button",
    elementId: "submitBtn",
    buttonText: "Submit",
    action: {
      actionType: "urlNavigation",
      url: "https://example.com/thanks"
    }
  }
};

const message = new CometChat.InteractiveMessage(
  "group-123",
  CometChat.RECEIVER_TYPE.GROUP,
  "form",
  interactiveData
);

CometChat.sendInteractiveMessage(message).then(
  (msg) => console.log("Interactive message sent:", msg),
  (error) => console.log("Failed:", error)
);

Button Card

const interactiveData = {
  title: "Order Confirmation",
  text: "Your order #12345 has been placed!",
  buttons: [
    {
      elementType: "button",
      elementId: "trackBtn",
      buttonText: "Track Order",
      action: {
        actionType: "urlNavigation",
        url: "https://example.com/track/12345"
      }
    },
    {
      elementType: "button",
      elementId: "supportBtn",
      buttonText: "Contact Support",
      action: {
        actionType: "urlNavigation",
        url: "https://example.com/support"
      }
    }
  ]
};

const message = new CometChat.InteractiveMessage(
  "user1",
  CometChat.RECEIVER_TYPE.USER,
  "card",
  interactiveData
);

CometChat.sendInteractiveMessage(message);

Async/Await

const sendInteractiveMessage = async () => {
  try {
    const interactiveData = {
      title: "Quick Survey",
      formFields: [
        {
          elementType: "textInput",
          elementId: "name",
          label: "Your Name",
          placeholder: { text: "Enter your name" }
        },
        {
          elementType: "dropdown",
          elementId: "rating",
          label: "How would you rate us?",
          options: [
            { label: "Excellent", value: "5" },
            { label: "Good", value: "4" },
            { label: "Average", value: "3" }
          ]
        }
      ],
      submitElement: {
        elementType: "button",
        elementId: "submitBtn",
        buttonText: "Submit"
      }
    };

    const message = new CometChat.InteractiveMessage(
      "group-123",
      CometChat.RECEIVER_TYPE.GROUP,
      "form",
      interactiveData
    );

    const sentMessage = await CometChat.sendInteractiveMessage(message);
    console.log("Interactive message sent:", sentMessage);
  } catch (error) {
    console.log("Failed:", error);
  }
};

---

Receive Interactive Messages

Listen for incoming interactive messages:

const listenerID = "INTERACTIVE_LISTENER";

CometChat.addMessageListener(
  listenerID,
  new CometChat.MessageListener({
    onInteractiveMessageReceived: (message) => {
      console.log("Interactive message received:", message);
      
      const data = message.getInteractiveData();
      const type = message.getType();
      
      // Render based on type
      renderInteractiveMessage(type, data);
    }
  })
);

// Remove listener when done
CometChat.removeMessageListener(listenerID);

---

Interaction Goals

Track when users complete interactions with your message.

Goal Types

Goal	Description
ANY	Completed with any interaction
ANY_OF	Completed when any specified element is interacted with
ALL_OF	Completed when all specified elements are interacted with
NONE	Never marked as completed

Set an Interaction Goal

const interactionGoal = new CometChat.InteractionGoal(
  ["submitBtn", "ratingInput"],  // Element IDs
  CometChat.INTERACTION_TYPE.ALL_OF  // All must be interacted with
);

const message = new CometChat.InteractiveMessage(
  "group-123",
  CometChat.RECEIVER_TYPE.GROUP,
  "form",
  interactiveData
);

message.setInteractionGoal(interactionGoal);

CometChat.sendInteractiveMessage(message);

Listen for Goal Completion

CometChat.addMessageListener(
  "GOAL_LISTENER",
  new CometChat.MessageListener({
    onInteractionGoalCompleted: (receipt) => {
      console.log("Interaction goal completed:", receipt);
      // User has completed the required interactions
    }
  })
);

---

Form Field Types

Type	Description
textInput	Single or multi-line text input
dropdown	Select from options
checkbox	Multiple selection
radio	Single selection
button	Action button

Text Input

{
  elementType: "textInput",
  elementId: "feedback",
  label: "Your Feedback",
  optional: false,
  maxLines: 3,
  placeholder: { text: "Enter your feedback" }
}

Dropdown

{
  elementType: "dropdown",
  elementId: "department",
  label: "Select Department",
  defaultValue: "sales",
  options: [
    { label: "Sales", value: "sales" },
    { label: "Support", value: "support" },
    { label: "Billing", value: "billing" }
  ]
}

Checkbox

{
  elementType: "checkbox",
  elementId: "interests",
  label: "Select Interests",
  defaultValue: ["tech"],
  options: [
    { label: "Technology", value: "tech" },
    { label: "Sports", value: "sports" },
    { label: "Music", value: "music" }
  ]
}

---

Allow Sender Interaction

By default, the sender cannot interact with their own interactive message. Enable it if needed:

const message = new CometChat.InteractiveMessage(
  "group-123",
  CometChat.RECEIVER_TYPE.GROUP,
  "form",
  interactiveData
);

message.setAllowSenderInteraction(true);

CometChat.sendInteractiveMessage(message);

---

Next Steps

Transient Messages

Send ephemeral real-time messages

Custom Messages

Send custom message types