When designing WhatsApp Flows, you might encounter this error:

INVALID_ON_CLICK_ACTION_PAYLOAD

The DocumentPicker component's value is not allowed in the payload of the navigate action.

Or:

The native component's value is not allowed in the payload of the navigate action.

This happens when you try to include a document picked by the user in a navigate action’s payload—something that’s not supported.

What's Going Wrong?

Here’s an example of problematic flow JSON:

{

  "children": [

    {

      "type": "DocumentPicker",

      "name": "doc",

      "label": "PASS_CUSTOM_VALUE"

    },

    {

      "type": "Footer",

      "label": "PASS_CUSTOM_VALUE",

      "on-click-action": {

        "name": "navigate",

        "payload": {

          "doc": "${screen.FIRST_SCREEN.form.doc}"

        }

      }

    }

  ]

}

In this structure, the navigate action is trying to carry the value of doc, which comes from a DocumentPicker. Since that’s a file upload, it’s not allowed.

Why It Fails

The navigate action is only meant to:

  • Move a user from one screen to another.

  • Optionally carry lightweight data like text, strings, or selected options.

But:

  • File inputs like those from DocumentPicker, PhotoPicker, or LocationPicker are native components.

  • Their values are not supported in navigate payloads because they contain binary or complex data.

How to Fix It?

Option 1: Use complete Instead

If you're collecting a document and need to submit it, use the complete action instead of navigate.

{
  "type": "Footer",
  "label": "Submit",
  "on-click-action": {
    "name": "complete",
    "payload": {
      "doc": "${form.doc}"
    }
  }
}

complete supports file-type payloads and is the right choice when submitting a form with document data.

Option 2: Exclude the File from the Navigate Payload

If your goal is to simply navigate without using the uploaded document in the transition, remove it from the payload:

{
  "type": "Footer",
  "label": "Next",
  "on-click-action": {
    "name": "navigate",
    "payload": {
      "doc_status": "uploaded"
    }
  }
}

Let the document upload happen, but don’t try to pass it directly between screens. You can process it later or handle the transition separately.

  • Never include native component values (PhotoPicker, DocumentPicker, etc.) in a navigate action.

  • Use complete for form submissions involving files.

  • Keep navigate actions clean, simple, and file-free.

Best Practices

  • Never include native component values (PhotoPicker, DocumentPicker, etc.) in a navigate action.

  • Use complete for form submissions involving files.

  • Keep navigate actions clean, simple, and file-free.

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