Interactive Messages

Interactive messages let you send richer message types, option pickers, forms, cards, and article lists, inside the ChannelX web widget, instead of plain text. They are useful when you want the customer to choose from a set of options or fill in structured information without you guessing at free-text answers.

Interactive messages are created through the messages API by setting a content_type and a matching content_attributes payload. The sections below show the shape of each type.

Info

Interactive messages render in the ChannelX web widget. Build them by sending the payloads below through the API for creating a new message in a conversation.

Option picker

Presents a short list of selectable options. Each item has a title shown to the customer and a value returned when they choose it.

{
    "content": "Select one of the items below",
    "content_type": "input_select",
    "content_attributes": {
        "items": [
            { "title": "Option1", "value": "Option 1" },
            { "title": "Option2", "value": "Option 2" }
        ]
    },
    "private": false
}

Form

Collects several fields at once. Each item describes one input, its type, label, placeholder, and optional default. Supported types include email, text, text_area, and select (which takes its own options list).

{
  "content": "form",
  "content_type": "form",
  "content_attributes": {
    "items": [
      {
        "name": "email",
        "placeholder": "Please enter your email",
        "type": "email",
        "label": "Email",
        "default": "xyc@xyc.com"
      },
      {
        "name": "text_area",
        "placeholder": "Please enter text",
        "type": "text_area",
        "label": "Large Text",
        "default": "Sample text"
      },
      {
        "name": "text",
        "placeholder": "Please enter text",
        "type": "text",
        "label": "text",
        "default": "sample input"
      },
      {
        "name": "select",
        "label": "Select Option",
        "type": "select",
        "options": [
          { "label": "Burrito", "value": "Burrito" },
          { "label": "Pasta", "value": "Pasta" }
        ]
      }
    ]
  },
  "private": false
}

Cards

Displays a visual card with an image, title, description, and action buttons. Actions can be a link (opens a URL) or a postback (sends a payload back to your application).

{
   "content": "card message",
   "content_type": "cards",
   "content_attributes": {
      "items": [
         {
            "media_url": "https://example.com/product-image.jpg",
            "title": "Running Shoe 2.0",
            "description": "Lightweight everyday running shoe",
            "actions": [
               { "type": "link", "text": "View More", "uri": "example.com" },
               { "type": "postback", "text": "Add to cart", "payload": "ITEM_SELECTED" }
            ]
         }
      ]
   },
   "private": false
}

Articles

Shares a list of linked articles, each with a title, description, and link, handy for pointing customers at help content.

{
    "content": "articles",
    "content_type": "article",
    "content_attributes": {
        "items": [
            { "title": "API start guide", "description": "A quick start API guide", "link": "http://example.com" },
            { "title": "Development docs", "description": "Development docs and guidelines", "link": "http://example.com" }
        ]
    },
    "private": false
}

Tip

Set "private": false so the message is delivered to the customer. A private message stays as an internal note and won't render as an interactive element for them.