How to Structure JSON Payloads for Interactive DM Quick-Reply Buttons

Interactive direct messages convert significantly higher than static text because they remove mobile typing friction. By utilizing Meta Graph API's structured message schemas—including Quick Reply pills, Generic Template carousel cards, and interactive CTA buttons—brands can guide users through multi-step funnels with simple taps. Constructing these JSON payloads requires strict adherence to character limits, payload schemas, and action types. This technical guide provides production-ready JSON templates and architectural best practices for interactive Instagram DMs.

1. The Three Primary Interactive Message Types

Meta's Messenger Platform for Instagram supports three distinct interactive message schemas:

• Quick Replies: Compact horizontal pills that appear directly above the user's mobile keyboard. When tapped, the button value is sent as a message, and the pills disappear. Ideal for qualifying questions and email capture.
• Button Templates: Structured cards containing body text and up to 3 persistent vertical action buttons (e.g. Open URL, Call Phone, or Trigger Postback).
• Generic Templates (Carousels): Horizontally scrollable carousels featuring an image, headline, subtitle, and up to 3 buttons per card. Optimal for e-commerce product catalogs and multi-resource libraries.

2. Production JSON Payload: Quick Reply Qualification Flow

Below is a production-ready payload for a two-tap coaching qualification flow with an email opt-in quick reply:

{
  "recipient": {"id": "17841400192837461"},
  "messaging_type": "RESPONSE",
  "message": {
    "text": "Welcome! What is your primary revenue goal for the next 90 days?",
    "quick_replies": [
      {"content_type": "text", "title": "Under $5k/mo", "payload": "GOAL_TIER_1"},
      {"content_type": "text", "title": "$5k - $15k/mo", "payload": "GOAL_TIER_2"},
      {"content_type": "text", "title": "$15k+/mo", "payload": "GOAL_TIER_3"}
    ]
  }
}

3. Generic Template Carousel Schema for E-Commerce

When delivering product recommendations or multiple lead magnets, use the generic template schema:

{
  "recipient": {"id": "17841400192837461"},
  "message": {
    "attachment": {
      "type": "template",
      "payload": {
        "template_type": "generic",
        "elements": [{
          "title": "Apex Performance Hoodie",
          "image_url": "https://brand.com/images/hoodie.jpg",
          "subtitle": "Heavyweight 450GSM Organic Cotton",
          "buttons": [{
            "type": "web_url",
            "url": "https://brand.com/cart/394821:1?discount=VIP15",
            "title": "Shop Now (15% Off)"
          }]
        }]
      }
    }
  }
}

4. Strict Technical Character Limits & Constraints

Meta enforces rigid length limits on interactive message fields. Exceeding these limits causes the API to return HTTP 400 Bad Request:

• Message Body Text: Maximum 1,000 characters. Recommended: under 120 characters for mobile readability.
• Quick Reply Title: Maximum 20 characters. Longer strings will be truncated with an ellipsis.
• Button Title: Maximum 20 characters.
• Quick Replies Limit: Maximum 13 quick reply pills per message.
• Carousel Elements: Up to 10 cards per generic template carousel.

Recommended Implementation Tooling

Design stunning interactive direct messages without writing raw JSON by hand using the AP3K platform's visual flow builder, which includes drag-and-drop quick replies, image carousels, and live mobile previews.

Frequently Asked Questions

Can I mix quick replies and button templates in the same message payload?

No. A single message object can contain either a text message with quick replies OR an attachment template (such as button or generic carousel), but not both simultaneously.

What happens if a user types a text reply instead of tapping a quick reply button?

The quick reply pills disappear, and your webhook receives a standard inbound message event. Your bot should be configured with fallback NLP or keyword matching to interpret typed responses gracefully.

Do interactive buttons work on both Instagram Desktop and Mobile apps?

Yes. Interactive quick replies and button templates render seamlessly on iOS, Android, and Instagram Web browser interfaces.