If you're hitting the INVALID_ON_CLICK_ACTION_PAYLOAD error in WhatsApp Flows with a message like:

"Value of 'Form' component cannot be used in form binding."

You're likely trying to use ${form.form_name} directly in your button’s payload — and that’s not allowed.

The Fix:

You can’t bind the entire form object (${form.form_name}) directly. Instead, you must reference individual fields from the form.

Do this:

"payload": {
  "text": "${form.form_name.input_name}"
}

Not this:

"payload": {
  "text": "${form.form_name}"
}

Why This Happens

WhatsApp Flows only allows dynamic binding to individual form fields. Trying to pass the entire form_name object (like ${form.form_name}) breaks the schema — hence the INVALID_ON_CLICK_ACTION_PAYLOAD error.

It's similar to referencing a whole <form> tag in HTML instead of a specific input value. WhatsApp Flows expects atomic data, not an object blob.

Best Practice

When setting up your on-click-action, always bind to specific form fields like this:

{
  "type": "Form",
  "name": "form_name",
  "children": [
    {
      "type": "Input.Text",
      "name": "user_name",
      "label": "Your Name"
    },
    {
      "type": "Footer",
      "label": "Done",
      "on-click-action": {
        "name": "navigate",
        "payload": {
          "text": "${form.form_name.user_name}"
        }
      }
    }
  ]
}

Pro Tip

Use meaningful field names (email, phone, feedback) so your bindings are easy to read and debug. Also, always validate bindings before publishing to avoid runtime failures.

For more troubleshooting insights related to WhatsApp Business API, check out heltar.com/blogs.