JSON Payload Examples

Connecting your server backend to the WhatsApp Business API requires building correct request schemas. Unlike simple messaging APIs that accept flat parameters, the WhatsApp gateway processes structured, nested JSON objects. Formatting errors in these payloads cause immediate validation rejections.

Integrating messaging templates, interactive quick-replies, dynamic buttons, and webhooks requires a clear payload reference. Implementing the correct schemas ensures payloads are accepted by the gateway and route accurately.

This developer guide details WhatsApp JSON payload examples. We will examine templates, interactive buttons, media objects, status payloads, setup checklists, and developer integration examples to help you structure your API calls.

The WhatsApp Business API groups requests by message type. Every payload requires standard rooting fields (`to`, `messaging_product`, and `type`) alongside the specific object container representing the content.

This table compares the primary message types and their schema structures.

By connecting systems, you can trigger specific messages based on customer behavior—such as confirming a booking, following up on a delivery, or recovering an abandoned shopping cart.

Implement these JSON payload formats across all high-volume automated messaging channels.

1. Transactional order confirmations

Send confirmations and purchase details instantly when checkout completes. These transactional updates keep customers reassured and reduce check-in inquiries.

2. E-commerce cart recovery

Trigger recovery reminders when shopping carts are abandoned. Personalizing templates with product names and checkout links helps recover lost sales.

3. Automated shipping and tracking updates

Integrate delivery updates to notify customers as their package changes hands, providing proactive transparency throughout fulfillment.

4. Out-of-office and away responders

Set up automated responders to handle inbound chats outside business hours, set response expectations, and route urgent queries to triage queues.

Setting up your WhatsApp automation workflows requires careful planning. Follow this step-by-step guide to get started.

Automations route messages systematically using logical rules. This workflow diagram illustrates how messages move through an automated routing queue.

Incoming user messages are parsed for active intent. Standard FAQs are resolved instantly by your AI support agent. Complex issues route to human queues, where agents collaborate to resolve them and log performance metrics.

A reliable customer support setup requires seamless sync between Meta's WhatsApp servers, your help desk software, and your business backend databases.

When an internal event occurs, your system fires a webhook. The Waplix engine validates the phone format, checks active marketing opt-ins, selects the target template, and submits the payload to Meta's servers for delivery.

This section provides complete JSON examples for common messaging requests and webhook events.

1. Send interactive quick-reply buttons

Expose dynamic buttons to users. Buttons return defined payloads to your server when clicked.

{
  "to": "+15550144983",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "header": {
      "type": "text",
      "text": "Support Ticket Update"
    },
    "body": {
      "text": "Your ticket #1029 has been resolved. Would you like to close it?"
    },
    "footer": {
      "text": "Please reply below"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "btn_close_yes",
            "title": "Yes, close it"
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "btn_close_no",
            "title": "Keep it open"
          }
        }
      ]
    }
  }
}

2. Webhook payload: Button click event

Incoming payload when a user clicks one of the interactive quick-reply buttons.

{
  "event": "message.received",
  "data": {
    "from": "+15550144983",
    "message_id": "msg_b78290acde",
    "type": "interactive",
    "interactive": {
      "type": "button_reply",
      "button_reply": {
        "id": "btn_close_yes",
        "title": "Yes, close it"
      }
    }
  }
}

For more detailed code samples, visit the API documentation and review our webhook documentation.

Operating a customer support desk on WhatsApp requires strict adherence to Meta's messaging policies and local data privacy laws.

• Opt-in verification. Businesses must secure explicit consent before sending outbound transactional alerts or ticket updates to customers.
• The 24-hour service window. Free-form messages can be sent within a 24-hour service window opened by a user's message. Messages sent outside this window must use pre-approved templates.
• Opt-out controls. Include clear opt-out options (such as quick-reply buttons like "STOP") in your templates to make unsubscribing easy and protect your quality rating.
• Follow local privacy laws. Ensure compliance with GDPR, TCPA, and other relevant regional regulations.

Waplix provides small businesses with official WhatsApp API access, eliminating the complexity of managing server infrastructure. Build workflows, manage templates, route replies to a shared inbox, and view campaign analytics—all from a single, unified platform.

• Incorrect E.164 phone formats. Including spaces, brackets, or leading zeros causes sends to fail.
• Exceeding quick-reply character limits. Meta limits quick-reply button text to 20 characters.
• Incorrect component indexing. Not matching index levels in template parameters causes rejection.
• Missing type parameters. Omitting structural type fields results in HTTP 400 validation failures.
• Failing to parse button reply payload IDs. Reading only button titles instead of IDs makes routing fragile.

Understanding and formatting JSON payloads correctly is essential for building a reliable integration. Following Meta's schemas for text, media, templates, and buttons prevents API validation errors.

Verify number formats, construct test schemas, send validation requests in the sandbox, and parse responses to begin your integration.