Interactive messages

Interactive messages let a bot or integration send more than plain text: buttons to pick from, product cards, short forms and article links. You send them through the Application API by setting a content type.

How to send one

Post a message to the conversation, the same way you send a normal reply, and add two fields:

• content_type: the kind of interactive message.
• content_attributes: an object with an items list that describes the buttons, cards, fields or articles.

curl -X POST "https://<your-engageone-domain>/api/v1/accounts/<account_id>/conversations/<conversation_id>/messages" \
  -H "api_access_token: <your-access-token>" \
  -H "Content-Type: application/json" \
  -d @message.json

You can use a personal access token or an agent bot token. See Access tokens.

Every content type needs at least one item. Unknown keys inside an item are rejected with a 422 error, so send only the keys shown below.

Options (input_select)

{
  "content": "How can we help you today?",
  "content_type": "input_select",
  "content_attributes": {
    "items": [
      { "title": "Track my order", "value": "track_order" },
      { "title": "Return an item", "value": "return_item" },
      { "title": "Talk to a person", "value": "agent" }
    ]
  }
}

Cards (cards)

{
  "content": "Here are our most popular plans",
  "content_type": "cards",
  "content_attributes": {
    "items": [
      {
        "media_url": "https://example.com/images/basic.png",
        "title": "Basic plan",
        "description": "For small teams getting started",
        "actions": [
          { "type": "link", "text": "View details", "uri": "https://example.com/plans/basic" },
          { "type": "postback", "text": "Choose Basic", "payload": "PLAN_BASIC" }
        ]
      }
    ]
  }
}

Each card needs at least one action.

A postback doesn't create a message in EngageOne. Instead, the widget fires a browser event on your website with the payload. The event's technical name comes from the underlying platform:

window.addEventListener('chatwoot:postback', (event) => {
  console.log(event.detail.payload); // "PLAN_BASIC"
});

Forms (form)

{
  "content": "Tell us a bit about your request",
  "content_type": "form",
  "content_attributes": {
    "items": [
      { "name": "full_name", "type": "text", "label": "Your name", "placeholder": "Asha Patel", "required": true },
      { "name": "email", "type": "email", "label": "Email", "placeholder": "you@example.com", "required": true },
      { "name": "topic", "type": "select", "label": "Topic",
        "options": [
          { "label": "Billing", "value": "billing" },
          { "label": "Technical", "value": "technical" }
        ]
      },
      { "name": "details", "type": "text_area", "label": "Details", "placeholder": "What happened?" }
    ]
  }
}

Articles (article)

{
  "content": "These articles might help",
  "content_type": "article",
  "content_attributes": {
    "items": [
      { "title": "How to reset your password", "description": "Step-by-step guide", "link": "https://help.example.com/reset-password" },
      { "title": "Update billing details", "description": "Change your card or address", "link": "https://help.example.com/billing" }
    ]
  }
}

Getting the customer's answer

When a website visitor picks an option or submits a form, EngageOne saves the answer on the original message in content_attributes.submitted_values. You get it in a message_updated webhook:

{
  "event": "message_updated",
  "content_type": "form",
  "content_attributes": {
    "items": ["..."],
    "submitted_values": [
      { "name": "full_name", "value": "Asha Patel" },
      { "name": "email", "value": "asha@example.com" }
    ]
  }
}

On WhatsApp, Messenger, Telegram and LINE, the customer's choice arrives as a normal incoming message instead.

Which channels show them

How options look on each channel:

• WhatsApp: up to 3 options without descriptions become reply buttons. More options, or any option with a description, become a list the customer opens. WhatsApp's own limits on button and list text apply.
• Facebook Messenger: quick reply buttons under the message.
• Telegram: buttons under the message.
• LINE: buttons inside a message bubble.

On other channels, the customer sees only the content text. Write it so it still makes sense on its own, for example "Reply 1 to track an order or 2 to talk to a person."

Tip: For API channel inboxes, EngageOne passes content_type and content_attributes to your webhook unchanged, so your own app can draw buttons, cards or forms however it likes.

Related articles

• API overview
• Agent bots
• Webhooks
• Website live chat